Type Hints

def parse(raw: str, *, strict: bool = False) -> dict[str, int | None]:
    ...

names: list[str] = []
counts: dict[str, int] = {}
pair: tuple[str, int] = ("a", 1)          # exactly two items
row: tuple[int, ...] = (1, 2, 3)          # any length, all int
maybe: str | None = None
handler: Callable[[str, int], bool]
nested: dict[str, list[tuple[int, str]]] = {}

def first[T](items: Sequence[T]) -> T:        # 3.12+
    return items[0]

class Box[T]:                                  # generic class, no Generic[T]
    def __init__(self, item: T) -> None:
        self.item = item
    def get(self) -> T:
        return self.item

def clamp[T: (int, float)](x: T, lo: T, hi: T) -> T:   # constrained
    return max(lo, min(x, hi))

def key_of[K, V](d: Mapping[K, V], value: V) -> K | None:
    ...

def load[T = dict](raw: str) -> T:             # 3.13, default type argument
    ...

type Point = tuple[float, float]               # 3.12 alias statement, lazy
type Json = str | int | float | bool | None | list[Json] | dict[str, Json]
type Pair[T] = tuple[T, T]                     # generic alias

from typing import TypeVar, Generic
from collections.abc import Sequence

T = TypeVar("T")                              # unconstrained
S = TypeVar("S", bound=Sequence[int])         # any subtype of Sequence[int]
N = TypeVar("N", int, float)                  # exactly int or float
T_co = TypeVar("T_co", covariant=True)        # read-only position
T_contra = TypeVar("T_contra", contravariant=True)

class Stack(Generic[T]):
    def __init__(self) -> None:
        self._items: list[T] = []
    def push(self, item: T) -> None:
        self._items.append(item)
    def pop(self) -> T:
        return self._items.pop()

s: Stack[int] = Stack()

from collections.abc import Iterable, Mapping, Callable, Iterator

def total(values: Iterable[float]) -> float:       # takes list, tuple, genexp
    return sum(values)

def lookup(cfg: Mapping[str, str], key: str) -> str | None:
    return cfg.get(key)

def chunk(items: Iterable[T], n: int) -> Iterator[list[T]]:   # generator returns Iterator
    ...

from typing import Any, Never, NoReturn, Literal, Final, ClassVar, LiteralString

def loose(x: Any) -> Any: ...        # opts OUT of checking, silently allows all
def strict(x: object) -> None:       # accepts anything, allows NOTHING on it
    if isinstance(x, str):           # must narrow before use
        print(x.upper())

def die(msg: str) -> Never:          # 3.11, never returns normally
    raise RuntimeError(msg)
def serve() -> NoReturn:             # same idea, older spelling
    while True: ...

Mode = Literal["r", "w", "a"]        # only these three strings
def openf(path: str, mode: Mode = "r") -> None: ...
def flag(on: Literal[True]) -> None: ...

MAX_RETRIES: Final = 3               # reassignment is a checker error
TIMEOUT: Final[float] = 5.0

class Config:
    registry: ClassVar[dict[str, str]] = {}   # class attribute, not per instance
    name: str                                 # instance attribute

from typing import TypedDict, NotRequired, Required, ReadOnly, NamedTuple

class Movie(TypedDict):
    title: str
    year: NotRequired[int]            # 3.11, per-key optional
    slug: ReadOnly[str]               # 3.13, cannot be reassigned

class Partial(TypedDict, total=False):
    a: int
    b: Required[str]                  # required inside a total=False dict

m: Movie = {"title": "Alien", "slug": "alien"}
Movie.__required_keys__               # frozenset({'title', 'slug'})
Movie.__optional_keys__               # frozenset({'year'})

class Point(NamedTuple):
    x: int
    y: int = 0                        # defaults must come last

p = Point(1)                          # Point(x=1, y=0)
p.x, p[0]                             # both work
p._replace(y=5)                       # Point(x=1, y=5)
p._asdict()                           # {'x': 1, 'y': 0}

from typing import Protocol, runtime_checkable, Self
import io

class SupportsWrite(Protocol):
    def write(self, s: str, /) -> int: ...

def emit(sink: SupportsWrite, msg: str) -> None:
    sink.write(msg + "\n")

emit(open("out.txt", "w"), "hi")       # files match, no relationship declared
emit(io.StringIO(), "hi")

@runtime_checkable                     # enables isinstance, METHOD NAMES ONLY
class Closable(Protocol):
    def close(self) -> None: ...

isinstance(some_file, Closable)        # True, signatures are NOT checked

class Comparable(Protocol):
    def __lt__(self, other: Self, /) -> bool: ...

from typing import overload, cast, assert_type, TypeGuard, TypeIs, Self

@overload
def get(key: str) -> str | None: ...
@overload
def get(key: str, default: str) -> str: ...
def get(key: str, default: str | None = None) -> str | None:   # the only real body
    return store.get(key, default)

raw = cast(dict[str, int], json.loads(text))   # asserts a type, zero runtime cost
assert_type(raw, dict[str, int])               # 3.11, fails the CHECK if wrong

def is_strs(v: list[object]) -> TypeIs[list[str]]:      # 3.13, narrows BOTH branches
    return all(isinstance(x, str) for x in v)

def is_strs_old(v: list[object]) -> TypeGuard[list[str]]:   # 3.10, True branch only
    return all(isinstance(x, str) for x in v)

class Query:
    def where(self, cond: str) -> Self:        # 3.11, subclasses return themselves
        return self

from typing import ParamSpec, TypeVar, Concatenate, Unpack, TypedDict, Annotated
from collections.abc import Callable
import functools

P = ParamSpec("P")          # 3.10, captures a full signature
R = TypeVar("R")

def logged(fn: Callable[P, R]) -> Callable[P, R]:      # signature preserved
    @functools.wraps(fn)
    def inner(*args: P.args, **kwargs: P.kwargs) -> R:
        return fn(*args, **kwargs)
    return inner

def with_conn(fn: Callable[Concatenate[Conn, P], R]) -> Callable[P, R]:
    ...       # Concatenate adds or strips leading args, here the injected Conn

def stats[*Ts](*args: *Ts) -> tuple[*Ts]:              # 3.11 TypeVarTuple
    return args

class Opts(TypedDict):
    retries: int
    timeout: float
def fetch(url: str, **kwargs: Unpack[Opts]) -> None:   # 3.11, typed **kwargs
    ...

Age = Annotated[int, "years"]        # 3.9, extra metadata for other tools
Port = Annotated[int, Field(gt=0, lt=65536)]     # pydantic Field, FastAPI reads it
get_type_hints(f)                     # strips Annotated metadata
get_type_hints(f, include_extras=True)   # keeps it

from __future__ import annotations       # every annotation becomes a string
from typing import TYPE_CHECKING

if TYPE_CHECKING:                        # import only for the checker, no cycle
    from myapp.models import User        # and no runtime import cost

class Node:
    def __init__(self, parent: Node | None = None) -> None:   # no quotes needed
        self.parent = parent
    def sibling(self) -> "Node":                              # quotes always work
        ...

def save(user: User) -> None:            # fine, the annotation is never evaluated
    ...

python -m pip install mypy
mypy --strict src/                     # the setting that actually finds bugs
mypy --ignore-missing-imports app.py   # third-party libs without stubs
python -m pip install types-requests   # stub package for a library

python -m pip install pyright
pyright                                # faster, stricter inference, VS Code default
pyright --outputjson

# pyproject.toml
[tool.mypy]
python_version = "3.13"
strict = true
warn_unreachable = true
disallow_untyped_defs = true

[tool.pyright]
typeCheckingMode = "strict"