must-annotate 0.1.0

Static analysis tool that enforces type annotation presence in Python code

typestrict

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

Unlike mypy or pyright which verify annotation correctness, typestrict 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 typestrict

Requires Python 3.10+.

---

Usage

# Check a single file
typestrict check app/models.py

# Check a directory recursively
typestrict check src/

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

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

# Exit with code 1 if errors are found (pre-commit / CI)
typestrict 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.typestrict]
# 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)  # typestrict: ignore

Suppress a specific rule code:

data = json.loads(response.text)  # typestrict: ignore[TF001]

---

Pre-commit integration

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

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

---

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.