Type Hints & Annotations

Annotations That Express Intent

Annotations document the types functions expect and return; Python stores them in __annotations__ but does not enforce them at runtime.

def retry(fn: Callable[[], T], attempts: int = 3) -> T: ...
counts: dict[str, int] = {}          # PEP 585 builtins, Python 3.9+
opt: str | None = None               # PEP 604 unions, Python 3.10+

Prefer builtin generics (list[int], tuple[str, int]) over legacy typing.List in modern code, use Optional[X]/X | None for possibly-absent values, and -> None for procedures. Annotations are the contract static checkers read — they do nothing when the program runs, so treat them as documentation plus verification, not protection.

Checking with mypy

Add a configuration block and run the checker in CI alongside tests:

# pyproject.toml
[tool.mypy]
python_version = "3.12"
strict = true            # enables disallow_untyped_defs, warn_return_any, ...
files = ["src"]

mypy src          # type-check the package
mypy --follow-imports=skip module.py   # check one file with untyped deps

mypy is gradual: untyped functions are checked leniently unless --strict or per-module overrides demand annotations. Adopt incrementally — start with check_untyped_defs, then tighten modules you actively change. cast(T, value) and # type: ignore[assignment] are escape hatches; each one should carry a comment justifying it.

Pitfalls and Interview Angles

Annotations are erased from runtime behavior. Passing a wrong int where str is declared raises no error until some downstream string operation fails. Validate untrusted input with pydantic, dataclasses, or hand-written checks; let mypy guard internal logic.

Any spreads silently. One Any in a signature disables checking for every caller that value touches. Prefer object (must narrow before use), TypeVar, or a Protocol.

Interview angle: explain gradual typing — untyped legacy code coexists with strict modules — then contrast static checking with runtime validation and name a bug each one would catch that the other misses.