Generic functions and decorators with TypeVar, ParamSpec and the PEP 695 syntax

What it is

A type variable means "some type, the same one wherever it appears in this signature". def first[T](xs: Sequence[T]) -> T tells the checker that the result has the element type of the argument. Python 3.12 (PEP 695) added the bracket syntax for functions, classes and type aliases; earlier code writes T = TypeVar("T") and inherits from Generic[T]. The typing documentation distinguishes bounded type variables ([S: str]: any subtype, solved to the most specific type) from constrained ones ([A: (str, bytes)]: exactly one of the listed types, as in AnyStr). ParamSpec (PEP 612, written **P) captures a whole parameter list, so a decorator can be typed Callable[P, R] -> Callable[P, R] without reducing the wrapped signature to Callable[..., Any]. Concatenate[Arg, P] describes a wrapper that adds or removes a leading parameter.

Why it matters

Untyped generic code degrades to Any, and everything flowing through it loses checking. Decorators are the most common leak: a retry or caching decorator annotated with Callable[..., Any] erases the signature of every function it decorates, so wrong arguments at call sites are no longer reported.

How to apply

• Use the bracket syntax on 3.12 and newer; with PEP 695 the variance of class type parameters is inferred, so covariant=/contravariant= flags are no longer written by hand.
• Type decorators as def deco[**P, R](f: Callable[P, R]) -> Callable[P, R] and forward *args: P.args, **kwargs: P.kwargs in the wrapper.
• Prefer a bound when the function needs a capability; use constraints when behaviour genuinely differs per concrete type and the two must not mix.
• Use typing.Self for methods returning the instance instead of a hand-made bound type variable; the documentation shows the two as equivalent.
• Give a type parameter a default ([T = str], Python 3.13) only for optional parameters of generic classes.

Pitfalls

A type variable that appears only once in a signature links nothing to anything and so constrains nothing; checkers commonly warn about it. Type variables of different functions are unrelated even when named alike. P.args and P.kwargs are plain objects at run time; they exist for checkers. Generic classes are not specialised at run time: Box[int]() creates a Box, and isinstance(x, Box[int]) raises TypeError. Code that must run on 3.11 or older needs the manual TypeVar form; PEP 695 states that traditional type variables should not be combined with new-syntax type parameters and that checkers should flag the combination as an error.