Type Hints: Python That Documents Itself¶

Estimated time: 20 min read · Part: Values, Variables & Expressions

Python stays dynamically typed at runtime, but since 3.5 you can annotate code with the types you intend. These type hints don't change runtime behaviour — Python ignores them when running — but tools like mypy and Pyright read them to catch bugs before you run, and your editor uses them for autocomplete and error highlighting. In a professional codebase, typed code is the norm, and showing it in an interview signals that you ship maintainable code, not one-off scripts.

The evolution of Python's type system has been rapid. Python 3.9 allowed using built-in types directly (list[int] instead of typing.List[int]). Python 3.10 introduced the X | Y union syntax (instead of typing.Union[X, Y]). Python 3.12 added type aliases and generic classes. In 2026 projects, the 3.10+ syntax is the default — clean, readable, and what code reviewers expect to see.

Basic annotation syntax¶

# Function annotations: parameters and return type
def discount(price: float, pct: float) -> float:
    """Return price after applying a percentage discount."""
    return price * (1 - pct / 100)

# Variable annotations:
name: str = "Acme"
count: int = 0
active: bool = True

# Modern composite types (Python 3.9+ syntax, no imports needed):
names: list[str]          = ["Acme", "Globex"]
scores: dict[str, int]    = {"Ada": 95}
point: tuple[int, int]    = (10, 20)
tags: set[str]            = {"enterprise", "saas"}

# Union types — Python 3.10+ syntax:
def find_deal(deal_id: int) -> dict | None:
    """Return a deal dict, or None if not found."""
    ...

# Any value (opt out of type checking — use sparingly):
from typing import Any
def log(value: Any) -> None: ...

TypedDict and dataclasses: structure your data¶

Plain dict[str, Any] tells the type checker almost nothing useful. When a dictionary has a fixed schema — a deal record, an API response — you have two good options: TypedDict (for dict-shaped data) and dataclasses (for object-shaped data with methods). Both give the type checker full visibility into what keys/attributes exist and what types they hold.

from typing import TypedDict
from dataclasses import dataclass, field

# TypedDict: typed schema for dict-shaped data
class DealRecord(TypedDict):
    id: int
    name: str
    mrr: float
    closed: bool

def process_deal(deal: DealRecord) -> str:
    return f"{deal['name']}: ${deal['mrr']:,.2f}"

# @dataclass: typed class with auto-generated __init__, __repr__, __eq__
@dataclass
class Deal:
    id: int
    name: str
    mrr: float
    closed: bool = False
    tags: list[str] = field(default_factory=list)  # correct mutable default!

    def display(self) -> str:
        return f"Deal({self.name}, ${self.mrr:,.2f})"

d = Deal(id=1, name="Acme", mrr=4999.99)
print(d)            # Deal(id=1, name='Acme', mrr=4999.99, closed=False, tags=[])
print(d.display())   # Deal(Acme, $4,999.99)

Deal(id=1, name='Acme', mrr=4999.99, closed=False, tags=[]) Deal(Acme, $4,999.99)

Callable, Final, Literal, and the typing toolbox¶

from typing import Callable, Final, Literal, TypeVar
from collections.abc import Sequence, Iterator

# Callable: annotate functions-as-arguments
def apply_transform(data: list[float], fn: Callable[[float], float]) -> list[float]:
    return [fn(x) for x in data]

# Final: a name that should never be rebound
MAX_RETRIES: Final[int] = 3

# Literal: constrain to specific values
def set_status(status: Literal["open", "closed", "pending"]) -> None: ...

# TypeVar: generic functions
T = TypeVar("T")
def first(items: Sequence[T]) -> T:
    return items[0]

# Sequence: read-only, accepts list, tuple, str — prefer over list[T] when
# you only need to iterate (more flexible for callers)
def total_mrr(deals: Sequence[Deal]) -> float:
    return sum(d.mrr for d in deals)

  TYPE CHECKING PIPELINE IN 2026
  ═══════════════════════════════════════════════════════

  Source code with hints (.py)
          │
          ├──► mypy / Pyright ──► Static analysis
          │    (pre-commit hook, CI)   │
          │                            ├── Type errors flagged BEFORE run
          │                            └── Editor shows squiggles live
          │
          ├──► Python runtime ──► Hints IGNORED, no enforcement
          │
          └──► Pydantic / attrs ──► Runtime validation
               (for API inputs,       (DOES enforce at runtime)
                user data, configs)

WHY type hints if Python doesn't enforce them Three compounding benefits: (1) Documentation — the signature tells you what a function expects without reading the body. (2) Editor support — autocomplete, parameter hints, and red squiggles on type mismatches. (3) Static checking — mypy/Pyright catch "passed a str where int expected" before the code ships. None of these require runtime enforcement to be valuable, and together they prevent a large class of bugs in large codebases.

HOW to adopt type hints incrementally You don't have to annotate everything at once. Start by annotating all function signatures (parameters and returns) — that gives you the best documentation-to-effort ratio. Then annotate module-level variables. Run mypy with --ignore-missing-imports at first to avoid noise from untyped third-party libraries. Add mypy to your pre-commit hooks and CI to prevent regressions. Progressively tighten the config over time.

WHERE runtime validation is still needed At system boundaries — API endpoints receiving JSON, config files loaded from disk, CSV data ingested from unknown sources. These inputs are not controlled by your code and can contain anything. Type hints tell you what you expect; Pydantic (or similar) validates that the actual data conforms at runtime and produces a clear error when it doesn't. Static hints + runtime validation are complementary, not redundant.

# Version 1: TypedDict (type-checker only, no runtime validation)
from typing import TypedDict

class WebhookPayload(TypedDict):
    event_type: str
    account_id: int
    mrr_change: float
    metadata: dict[str, str]

def handle_webhook(payload: WebhookPayload) -> str:
    return (
        f"Event '{payload['event_type']}' for account {payload['account_id']}: "
        f"MRR change ${payload['mrr_change']:+,.2f}"
    )

sample: WebhookPayload = {
    "event_type": "upgrade",
    "account_id": 42,
    "mrr_change": 500.0,
    "metadata": {"plan": "enterprise"},
}
print(handle_webhook(sample))

# Version 2: Pydantic (type-checker + runtime validation)
from pydantic import BaseModel, field_validator

class WebhookPayloadModel(BaseModel):
    event_type: str
    account_id: int
    mrr_change: float
    metadata: dict[str, str]

    @field_validator("mrr_change")
    @classmethod
    def mrr_must_be_non_negative(cls, v: float) -> float:
        if v < 0:
            raise ValueError("mrr_change must be >= 0")
        return v

def handle_webhook_v2(payload: WebhookPayloadModel) -> str:
    return (
        f"Event '{payload.event_type}' for account {payload.account_id}: "
        f"MRR change ${payload.mrr_change:+,.2f}"
    )

# Valid payload:
p = WebhookPayloadModel(event_type="upgrade", account_id=42,
                        mrr_change=500.0, metadata={"plan": "enterprise"})
print(handle_webhook_v2(p))

# Invalid payload (raises ValidationError):
try:
    bad = WebhookPayloadModel(event_type="downgrade", account_id=42,
                              mrr_change=-100.0, metadata={})
except Exception as e:
    print(f"Validation error: {e}")