Python Typing Checker

Deep analysis of type annotation coverage and quality across Python codebases. Finds untyped functions, incorrect annotations, missing generics, improper Protocol usage, and patterns that break type checker inference.

Use when: auditing type safety, preparing to enable strict mypy, reviewing annotation quality, or migrating from untyped to typed Python.

Analysis Steps

1. Project Discovery

cat pyproject.toml 2>/dev/null | head -30
python3 --version 2>/dev/null

# Mypy config
cat pyproject.toml 2>/dev/null | grep -A30 '\[tool.mypy\]'
cat mypy.ini 2>/dev/null || cat setup.cfg 2>/dev/null | grep -A20 '\[mypy\]'

# py.typed marker (PEP 561)
find . -name "py.typed" -not -path '*/venv/*' 2>/dev/null
find . -name "*.pyi" -not -path '*/venv/*' 2>/dev/null | head -10
find . -name "*.py" -not -path '*/venv/*' -not -path '*/__pycache__/*' | wc -l

Determine: Python version, type checker config and strictness, whether package ships types (py.typed), project size.

2. Type Annotation Coverage

# Functions without return type annotation
grep -rn 'def [a-zA-Z_]\+(' --include="*.py" . 2>/dev/null \
  | grep -v 'venv/\|__pycache__\|_test\.py\|test_' | grep -v '\-> ' | head -30

# Completely untyped files
for f in $(find . -name "*.py" -not -path '*/venv/*' -not -path '*/__pycache__/*' \
  -not -name '*_test.py' 2>/dev/null); do
  if ! grep -q ':\s*[A-Z]\|-> \|: str\|: int\|: float\|: bool\|: list\|: dict' "$f" 2>/dev/null; then
    echo "UNTYPED: $f"
  fi
done | head -15

# Coverage estimate
total=$(grep -rc 'def ' --include="*.py" . 2>/dev/null | grep -v 'venv/' | awk -F: '{s+=$2} END {print s}')
typed=$(grep -rc '\-> ' --include="*.py" . 2>/dev/null | grep -v 'venv/' | awk -F: '{s+=$2} END {print s}')
echo "Coverage: $typed / $total functions have return type annotations"

3. Type Import Patterns

# Deprecated typing imports (use builtins in 3.9+)
grep -rn 'from typing import List\|from typing import Dict\|from typing import Tuple\|from typing import Set' \
  --include="*.py" . 2>/dev/null | grep -v 'venv/' | head -15

# from __future__ import annotations (PEP 563)
grep -rn 'from __future__ import annotations' --include="*.py" . 2>/dev/null | grep -v 'venv/' | head -10

# TYPE_CHECKING guard
grep -rn 'TYPE_CHECKING' --include="*.py" . 2>/dev/null | grep -v 'venv/' | head -10

Flag:

Deprecated typing imports: typing.List/Dict/Tuple/Set deprecated since 3.9 — use list/dict/tuple/set
Missing TYPE_CHECKING guard: types imported only for annotations should be under if TYPE_CHECKING: to avoid runtime overhead and circular imports
Inconsistent style: mixing List[int] and list[int] in same codebase

4. Any, Union, and Escape Hatches

# Any usage (excluding imports)
grep -rn '\bAny\b' --include="*.py" . 2>/dev/null | grep -v 'venv/\|_test\.py\|from typing' | head -20

# type: ignore comments
grep -rn 'type:\s*ignore' --include="*.py" . 2>/dev/null | grep -v 'venv/' | head -15

# cast() usage
grep -rn 'cast(' --include="*.py" . 2>/dev/null | grep -v 'venv/' | head -10

# Optional without None check patterns
grep -rn 'Optional\[' --include="*.py" . 2>/dev/null | grep -v 'venv/' | head -10

Flag:

Excessive Any: each Any is a hole in type safety — each usage should be justified
Functions returning Any: callers lose all type information
type: ignore without error code: should specify like # type: ignore[assignment] for maintainability
cast() overuse: runtime no-op that lies to the type checker — prefer isinstance narrowing
Optional without None handling: annotating Optional[X] but never checking for None

5. Generics, TypeVar, and Protocol

# TypeVar definitions
grep -rn 'TypeVar(' --include="*.py" . 2>/dev/null | grep -v 'venv/' | head -10

# ParamSpec (decorator typing, 3.10+)
grep -rn 'ParamSpec' --include="*.py" . 2>/dev/null | grep -v 'venv/' | head -5

# Protocol definitions
grep -rn 'class.*Protocol' --include="*.py" . 2>/dev/null | grep -v 'venv/\|from typing' | head -10

# ABC vs Protocol
grep -rn '@abstractmethod\|class.*ABC' --include="*.py" . 2>/dev/null | grep -v 'venv/' | head -10

# Complex Callable types
grep -rn 'Callable\[' --include="*.py" . 2>/dev/null | grep -v 'venv/' | head -10

# dict[str, Any] (could be TypedDict)
grep -rn 'dict\[str,\s*Any\]\|Dict\[str,\s*Any\]' --include="*.py" . 2>/dev/null | grep -v 'venv/' | head -10

Flag:

Unconstrained TypeVar: T = TypeVar('T') accepts anything — add bound= if function needs specific capabilities
Missing ParamSpec for decorators: decorators without ParamSpec lose the decorated function's signature
ABC where Protocol fits: if base class has no shared implementation, Protocol gives structural subtyping without inheritance
Complex Callable types: Callable[[str, int, Optional[dict]], Awaitable[list[str]]] — use Protocol with __call__ instead
dict[str, Any] for structured data: use TypedDict for type-safe key access

6. Dataclass & Async Patterns

# Dataclass issues
grep -A20 '@dataclass' --include="*.py" . 2>/dev/null | grep '^\s\+[a-z_]\+ =' | grep -v ':' | head -10

# TypedDict
grep -rn 'TypedDict' --include="*.py" . 2>/dev/null | grep -v 'venv/\|from typing' | head -10

# Async functions without return type
grep -rn 'async def' --include="*.py" . 2>/dev/null | grep -v 'venv/\|_test\.py' | grep -v '\->' | head -10

Flag:

Dataclass fields without types: required in strict mode
Mutable default in dataclass: field: list = [] shared across instances — use field(default_factory=list)
Async functions without return annotation: type checker infers Coroutine[Any, Any, Any]

7. Mypy Strictness Audit

grep -i 'strict\|disallow_untyped_defs\|disallow_any_generics\|warn_return_any\|check_untyped_defs' \
  pyproject.toml mypy.ini setup.cfg 2>/dev/null | head -15

Recommended strictness progression:

check_untyped_defs = true — type-check bodies even without annotations
no_implicit_optional = true — require explicit Optional[X] for = None
warn_return_any = true — flag functions returning Any via untyped calls
disallow_untyped_defs = true — require annotations on all functions
disallow_any_generics = true — require type params (list[int] not list)
strict = true — all strict flags (goal state)

Output Template

# Python Typing Analysis — [Project Name]

## Summary
- Files: N | Python: 3.XX | Type checker: mypy/pyright/none
- Functions with return types: N/M (XX%) | Any usages: N | type:ignore: N

## Coverage by Package
| Package | Functions | Typed | Coverage |
|---------|-----------|-------|----------|
| src/core/ | 30 | 12 | 40% |
| src/api/ | 45 | 40 | 89% |

## Critical Findings
### [C1] Function Returns Any, Callers Assume str
- **File**: src/utils/parser.py:34 — Fix: `def parse(data: bytes) -> ParseResult:`
### [C2] Optional Without None Check
- **File**: src/api/handlers.py:56 — Fix: add None guard before access

## Recommendations
1. Enable `check_untyped_defs = true` in mypy config
2. Add return types to N functions in highest-priority packages
3. Replace N deprecated `typing.List/Dict` imports with builtins
4. Add error codes to N `type: ignore` comments
5. Replace N `dict[str, Any]` with TypedDict, add `ParamSpec` to N decorators
6. Add `py.typed` marker if package is distributed as library

Tips

Run mypy --strict --show-error-codes . to see all strict violations
Use reveal_type(expr) to debug inference, typing.assert_type() (3.11+) for tests
Run pyright --verifytypes <package> to check exported API completeness
Use stubgen for .pyi stubs, monkeytype for runtime-traced annotations
For complex dict structures, use datamodel-code-generator to generate TypedDict from JSON