Metadata-Version: 2.4
Name: transformers-mlinter
Version: 0.1.4
Summary: Lint Hugging Face Transformers model integration files for structural conventions.
Author-email: The Hugging Face Team <transformers@huggingface.co>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/huggingface/transformers-mlinter
Project-URL: Repository, https://github.com/huggingface/transformers-mlinter
Keywords: linter,transformers,huggingface,ast,modeling
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich
Requires-Dist: tomli; python_version < "3.11"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: ty; extra == "dev"
Dynamic: license-file

<!-- Absolute URL on purpose: this README is also the PyPI long_description, and PyPI does not resolve
     repo-relative image paths. -->
<p align="center">
  <img src="https://raw.githubusercontent.com/huggingface/transformers-mlinter/main/docs/assets/images/mlinter-logo.png"
       alt="mlinter" width="360">
</p>

# mlinter

A standalone linter for [Hugging Face Transformers](https://github.com/huggingface/transformers) model
integration files — `modeling_*.py`, `modular_*.py`, `configuration_*.py`, `processing_*.py`,
`image_processing_*.py`, `video_processing_*.py` and `feature_extraction_*.py` under
`src/transformers/models/`, plus `test_tokenization_*.py` under `tests/models/`. It enforces the
structural conventions that keep hundreds of model implementations consistent with each other.

**📖 Documentation: <https://huggingface.github.io/transformers-mlinter/>**

The docs site is generated from `mlinter/rules.toml`, so its
[rule reference](https://huggingface.github.io/transformers-mlinter/rules/) is always in step with the
installed rules.

## Installation

```bash
pip install transformers-mlinter
```

When working on the transformers repo, mlinter is included in the `quality` extras:

```bash
pip install -e ".[quality]"
```

## Quick start

Run from the root of a transformers checkout:

```bash
mlinter                                     # check every model integration file
mlinter --changed-only --base-ref origin/main   # only what you changed
mlinter --list-rules                        # list rules and their default state
mlinter --rule TRF001                       # explain one rule
```

Pass a path to check code that lives outside a transformers checkout — a model repository shipped on
the Hub with `trust_remote_code`, for instance, which has to honour the same conventions:

```bash
mlinter ~/models/LLaDA-8B-Instruct          # a directory, searched recursively
mlinter path/to/modeling_llada.py           # or a single file
```

See the [CLI reference](https://huggingface.github.io/transformers-mlinter/usage/) for every flag, the
Python API, and cache locations.

## Documentation map

| Page | What's there |
|:-----|:-------------|
| [Home](https://huggingface.github.io/transformers-mlinter/) | What mlinter checks and why, installation, how rule registration works |
| [Rules](https://huggingface.github.io/transformers-mlinter/rules/) | All rules, filterable, one page each with examples and exemptions |
| [CLI usage](https://huggingface.github.io/transformers-mlinter/usage/) | Every flag, output formats, cache, Python API |
| [Suppressing rules](https://huggingface.github.io/transformers-mlinter/suppressing/) | `# trf-ignore`, whole-file directives, cutoff dates, allowlists |
| [Contributing a rule](https://huggingface.github.io/transformers-mlinter/contributing/) | Adding a rule, the `add-mlinter-rule` skill, constraints on a rule |
| [Releasing](https://huggingface.github.io/transformers-mlinter/release/) | The tag-driven release process |

## Development

```bash
git clone https://github.com/huggingface/transformers-mlinter
cd transformers-mlinter
pip install -e ".[dev]"
```

```bash
make test        # pytest under tests/
make lint        # ruff check + format --check
make format      # auto-fix style
make typecheck   # ty on mlinter/
```

### Building the docs site

The rule pages are generated and git-ignored. Building needs the Ruby toolchain once:

```bash
cd docs && bundle install && cd ..
make docs         # regenerate rule pages, build the site, check internal links
make docs-serve   # live preview on http://localhost:4000/transformers-mlinter/
```

## License

Apache-2.0. See [LICENSE](LICENSE).
