Skip to main content
Change of provenance

The repository or configuration that created this release differ from a previous release. View details.

must-annotate

must-annotate is a Python static analysis tool that enforces the presence of type annotations in Python code.

Unlike mypy or pyright which verify annotation correctness, must-annotate simply checks that every variable, function argument, and return value has an annotation. If it is missing — that is an error.

# ERROR: missing type annotation
a = 3
result = get_user()

# OK: annotation present
a: int = 3
result: User = get_user()

Installation

pip install must-annotate

Requires Python 3.10+.


Usage

# Check a single file
must-annotate check app/models.py

# Check a directory recursively
must-annotate check src/

# Output as JSON (for CI/CD)
must-annotate check src/ --format json

# Check only specific rules
must-annotate check src/ --select TF001,TF002

# Exit with code 1 if errors are found (pre-commit / CI)
must-annotate check src/ --fail-on-error

Example output

src/app/models.py:15:4  TF001  Variable 'result' missing type annotation
src/app/models.py:23:0  TF002  Argument 'user_id' missing type annotation
src/app/views.py:8:0    TF003  Function 'get_data' missing return type annotation

Found 3 errors in 2 files

Error codes

Code Description Example violation
TF001 Variable assignment without a type annotation a = 3
TF002 Function argument without a type annotation def f(x):
TF003 Function missing a return type annotation def f():
TF004 Class attribute assigned without a type annotation self.name = "test"
TF005 Loop/context-manager variable without annotation (opt-in) for i in range(10):

Configuration (pyproject.toml)

[tool.must-annotate]
# Exclude directories or files from analysis
exclude = ["tests/", "migrations/", "conftest.py"]

# Disable specific rules globally
ignore = ["TF005"]

# Disable rules for specific files
per_file_ignores = { "conftest.py" = ["TF001"], "settings.py" = ["TF001"] }

# Strict mode: enables ALL rules, including TF005
strict = false

Inline suppression

Suppress an error on a specific line:

data = json.loads(response.text)  # must-annotate: ignore

Suppress a specific rule code:

data = json.loads(response.text)  # must-annotate: ignore[TF001]

Pre-commit integration

Add to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/example/must-annotate
    rev: v0.1.0
    hooks:
      - id: must-annotate

What is skipped automatically

  • Dunder variables: __all__, __version__, etc.
  • The unused-value convention: _ = some_func()
  • Tuple unpacking: a, b = func() (hard to annotate inline)
  • Augmented assignment: counter += 1 (type already declared)
  • self and cls as the first argument of methods

Development

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Type-check the library itself
mypy

License

MIT — see LICENSE.

Metadata

Release files for must-annotate 0.1.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Change of provenance

The repository or configuration that created these release files differ from that of a previous release.

We recommend inspecting the repository and configuration before proceeding. View details.

Source distribution (sdist)

Source distribution for must-annotate 0.1.2
File Size Uploaded Provenance Actions
must_annotate-0.1.2.tar.gz 18.1 kB With provenance Details for must_annotate-0.1.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for must-annotate 0.1.2
File Interpreter ABI Platform Actions
must_annotate-0.1.2-py3-none-any.whl Python 3 none any Details for must_annotate-0.1.2-py3-none-any.whl

Total release size: 37.2 kB

Release files / must_annotate-0.1.2.tar.gz

Change of provenance

This file belongs to a release with changed provenance: the repository or configuration that created the release files differ from that of a previous release.

We recommend inspecting the repository and configuration before proceeding. View details.

Download URL must_annotate-0.1.2.tar.gz
Size 18.1 kB
Tags Source
SHA-256 checksum
How to use checksums
b95c2b4ee3abc966739496e1261d26274bab3b01c6ddb806e0b63bbce323601b
BLAKE2b-256 checksum
How to use checksums
d030f259349cb986d6ebbb205af793e7a55c686f38d4f9a31a924af9cb2817eb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Mar 22, 2026.

Transparency log

Release files / must_annotate-0.1.2-py3-none-any.whl

Change of provenance

This file belongs to a release with changed provenance: the repository or configuration that created the release files differ from that of a previous release.

We recommend inspecting the repository and configuration before proceeding. View details.

Download URL must_annotate-0.1.2-py3-none-any.whl
Size 19.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3692ecb72a650887909104ad18fa43e20b61160c05d9ec0fe4dad260ec3799da
BLAKE2b-256 checksum
How to use checksums
d8c9991c07fa63ffadd211cfc256b04823ea152d4a4ca1bf4ba5a618f5dc93d3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Mar 22, 2026.

Transparency log

Security for must-annotate 0.1.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Change of provenance

The repository and configuration that created this release differ from a previous release.

While this could reflect a routine change by the project maintainers, it may also indicate that the release files have been compromised.

Select from 2 files

Attestation for must_annotate-0.1.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Mar 22, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page