Type Hints Best Practices

Types should reduce incidents without drowning the team in ceremony. These rules focus effort where static analysis prevents real production bugs.

How to Use This List

• Apply to all new modules and touched code in review.
• Pair with mypy/pyright CI on typed packages.
• Revisit when Any count grows or strict overrides multiply.
• Onboard juniors with Type Hints Basics then this checklist.

A - Where to Type

• Type every public function signature in application code. Private helpers when non-obvious.
• Type HTTP/CLI/config boundaries first. Pydantic 2 models for FastAPI/Django REST payloads.
• Use Protocols for injected dependencies (storage, clock, notifier). Test doubles without inheritance.
• Annotate container contents: list[str], not bare list. Bare generics defeat checking.
• Stop at hot inner loops unless bugs proved. Profile before typing numpy kernels exhaustively.

B - Syntax and Style

• Use X | Y union syntax on Python 3.10+. Consistent with 3.14 codebase.
• Use collections.abc types in parameters (Sequence, Mapping). Accept wider read-only inputs.
• Prefer TypedDict/NamedTuple for JSON rows; dataclass for domain objects. Match runtime shape.
• Use Literal and StrEnum for fixed string sets. Prevent typos at check time.
• Avoid Any - use object when truly unknown then narrow. Track Any with lint rule where possible.

C - Tooling and CI

• Run mypy or pyright in CI on typed packages. Block regressions on merged modules.
• Install types-* stubs for untyped dependencies. requests, pyyaml, etc.
• Enable warn_unused_ignores and warn_return_any. Clean stale ignores promptly.
• Use per-package mypy overrides, not global ignore_errors. Quarantine with sunset dates.
• Keep ruff 0.9+ separate from type checking. Formatter/linter does not replace mypy.

D - Runtime vs Static

• Remember hints are not runtime validation. Use Pydantic/isinstance at trust boundaries.
• Do not rely on typing.cast to fix logic. cast silences checker only.
• Use isinstance / match narrowing after optional checks. if x is not None pattern.
• Validate external JSON before treating as TypedDict shape. Schema or Pydantic first.
• Document when type: ignore unavoidable with error code and ticket link.

E - Gradual Typing Hygiene

• Type new code 100%; legacy follows gradual strategy. See gradual typing article.
• Shrink quarantined legacy modules over time. ignore_errors must have owner and date.
• Prefer generics (TypeVar) when utility preserves input types. Not Any in/out.
• Use @overload sparingly for real signature dependence. Not for cosmetic hints.
• Review Protocol/ABC choice in design docs. Structural vs nominal consistency.

FAQs

Related

• Type Hints Basics - syntax tour
• Gradual Typing Strategy - brownfield rollout
• mypy & pyright Setup - configuration
• Python Fundamentals Best Practices - general habits

Stack versions: This page was written for Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.