annotations

name	annotations
description	Workflow for adding type annotations to Plain packages. Use this when adding or improving type coverage.

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%