---
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
```bash
# 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%
```
