Annotations

Type Annotation Workflow

We are gradually adding type annotations using Python 3.13+.

Workflow

1. Check current coverage:

   uv run plain code annotations <directory> --details
   

2. Add annotations: Focus on function/method signatures (parameters and return types)

3. Type check:

   ./scripts/type-check <directory>
   

4. Format: ./scripts/fix

5. Test: ./scripts/test <package>

6. Verify improvement:

   uv run plain code annotations <directory>
   

7. 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%