Generics and Protocols: PEP 695 syntax, variance without hand-waving, structural typing

From TypeVar ceremony to class Stack[T]

If you’ve ever opened a library’s source and seen five module-level TypeVar declarations before a single line of business logic, you know the tax. PEP 695 eliminates most of it.

For a decade Python generics meant declaring a module-level TypeVar, threading it through Generic[T], and remembering which of your seventeen Ts was bound to what. PEP 695 (Python 3.12, 2023) folds all of it into the definition site:

# Old ceremony (still valid, still everywhere in legacy code)
from typing import Generic, TypeVar
T = TypeVar("T")
class OldStack(Generic[T]):
    def push(self, item: T) -> None: ...

# PEP 695: the type parameter lives where it is used
class Stack[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()

class Repo[M: Model]:                  # bound: M must subtype Model
    def get(self, pk: int) -> M | None: ...

def first[T](items: list[T]) -> T | None:   # generic function
    return items[0] if items else None

type Result[T] = T | None              # generic type alias

The new syntax is not sugar only: parameters are scoped to the class or function (no leaking module-level T), bounds read inline ([M: Model]), and type aliases are lazily evaluated, which kills a whole family of forward-reference headaches. A checker infers Stack[int] from Stack[int]() and then proves every push/pop against it. The honest tradeoff: PEP 695 requires 3.12+, so libraries supporting older Pythons still ship TypeVar — you must read both dialects even if you write only the new one.

Variance, honestly

Variance answers one question: if Dog subtypes Animal, what is the relationship between list[Dog] and list[Animal]? For mutable containers the answer is none — list is invariant. The Hook is the proof: if list[Dog] were accepted as list[Animal], the callee could legally append(Cat()), corrupting the caller’s list. Read-only views are safe in one direction: Sequence[Dog] is a Sequence[Animal] (covariant), because a type you can only read Dogs from can be safely read as producing Animals. Functions flip the arrow: Callable[[Animal], None] is usable where Callable[[Dog], None] is expected (contravariant in parameters) — a handler that accepts any Animal certainly handles Dogs. The practical rules that fall out: accept Sequence/Iterable/Mapping in signatures unless you genuinely mutate, and the invariance error disappears for free; return concrete types; never “fix” a variance error with cast — the checker is describing a real aliasing hazard, and the fix is choosing a read-only type or copying the list.

Protocol: structural typing, and where runtime_checkable lies

When you design a typed API for a function that only needs to emit metrics or close a resource, why should the caller’s class inherit from some base you control? Protocol answers: it shouldn’t. Any class with the right methods qualifies — including test fakes your teammates write without ever importing your module.

Protocol (PEP 544) is Python’s answer to Go interfaces: conformance by shape, not by inheritance. The consumer declares what it needs; any class with matching methods satisfies it, with zero imports between the two sides:

from typing import Protocol, overload, runtime_checkable

@runtime_checkable
class Closeable(Protocol):
    def close(self) -> None: ...

class MetricsSink(Protocol):
    def emit(self, name: str, value: float) -> None: ...

def flush_all(sinks: list[MetricsSink]) -> None:
    for s in sinks:
        s.emit("flush", 1.0)   # statsd, datadog, a test fake — all conform

class Config:
    @overload
    def get(self, key: str) -> str | None: ...
    @overload
    def get(self, key: str, default: str) -> str: ...
    def get(self, key, default=None):
        return self._data.get(key, default)

This is how you design typed APIs at senior level: depend on the narrowest protocol the function needs (Closeable, not IOBase), and test fakes conform automatically — no mock inheritance gymnastics. overload completes the toolkit: Config.get returns str | None without a default but a guaranteed str with one, so callers do not write dead None-checks. Now the limits, because they bite: @runtime_checkable makes isinstance(x, Closeable) work, but the check verifies method existence only — a close(self, force: bool) with an incompatible signature still passes isinstance and explodes when called; data-member protocols and non-method details are not checked at runtime either. isinstance against a protocol is also measurably slow (it introspects attributes per call) — fine at a boundary, wrong in a hot loop. Static checking verifies full signatures; the runtime check is a name-presence sniff. Treat runtime_checkable as a boundary heuristic, never as validation.