Type Annotation Workflow
We are gradually adding type annotations using Python 3.13+.
Workflow
Check current coverage:
uv run plain code annotations <directory> --details
Add annotations: Focus on function/method signatures (parameters and return types)
Type check:
./scripts/type-check <directory>
Format: ./scripts/fix
Test: ./scripts/test <package>
Verify improvement:
uv run plain code annotations <directory>
Add to validation: Once a directory reaches 100% coverage, add it to FULLY_TYPED_PATHS in scripts/type-validate
Guidelines
-
Add from future import annotations when necessary
-
Focus on public APIs and user-facing methods first
-
Don't annotate init return types (type checkers infer None )
-
Use explicit return None for functions with -> Type | None return type
-
Some Django-style ORM patterns are inherently difficult to type - that's okay
-
Goal is progress, not perfection
Example
Check coverage
uv run plain code annotations plain/plain/assets --details
After adding annotations...
./scripts/type-check plain/plain/assets ./scripts/fix ./scripts/test plain uv run plain code annotations plain/plain/assets # Should show 100%