TypeVar and Generic Classes

## What a type parameter actually is `typing.TypeVar` creates a **type parameter**: a named hole in a signature that a static checker fills in per call site. It is a variable whose values are *types*, not objects. Declaring one is a runtime statement like any other: ```python from typing import TypeVar T = TypeVar("T") ``` The string argument is the parameter's name and, by convention and by most checkers' enforcement, must match the variable it is bound to — `T = TypeVar("U")` is a diagnosable error, not a stylistic quirk. ## Why `Any` is not a substitute `Any` is the escape hatch of the type system: it is assignable to every type and every type is assignable to it. A helper annotated `def first(items: Sequence[Any]) -> Any` type-checks against every call, and — the real cost — every *use of its result* also type-checks. Call `.bit_length()` on what is actually a `str` and nothing complains; the error surfaces at runtime, in whatever code path happened to run first. A TypeVar preserves information instead of discarding it: ```python def first(items: Sequence[T]) -> T: return items[0] first([3, 1, 2]) # checker infers int first(["north", "south"]) # checker infers str ``` The checker sees `T` in the parameter position, *solves* it from the argument (`list[str]` matches `Sequence[T]` with `T = str`), and substitutes that solution into the return annotation. Each call is solved independently — nothing is remembered between calls. ## The "appears twice" rule The single most useful heuristic: **a TypeVar earns its place only when it occurs in at least two positions in one signature.** Two parameters, or a parameter and the return, or a parameter and a nested position such as `Sequence[T]` and `T`. Those repetitions are the *relationship* the parameter expresses. ```python def repeat(item: T, times: int) -> list[T]: ... # useful: T links input to output def log(item: T) -> None: ... # pointless: use object ``` A parameter appearing once constrains nothing, and the honest annotation for "I accept anything and look at none of it" is `object` — which, unlike `Any`, still refuses attribute access you have not proved is safe. ## Unbound TypeVars accept anything A bare `TypeVar("T")` is *unbounded*: it can be solved to any type, so inside the function body the checker lets you do only what you can do to `object`. You cannot call `item.label()` or `item + item` on a value typed as a bare `T`, because the next caller might pass something without that operation. Widening what the body may assume is exactly what `bound=` and a value-constraint list are for. ## Runtime versus checking Everything above happens **before** the program runs. At runtime the annotation is just an object stored on the function; `TypeVar` performs no validation, no coercion, and no dispatch. Passing a `str` where the checker inferred `int` raises nothing at the boundary — it fails later, wherever an integer operation actually runs. This trips up candidates who describe generics as "enforcing" a type: Python's generics are entirely erased at execution time, and the value of writing them is that a checker, an editor's completions and the next reader all get the information. ## Generic functions versus generic classes A function using a TypeVar is a **generic function**: it needs no base class and no registration, just the shared placeholder. A generic *class* is the other half of the story — it inherits `Generic[T]` (or a base already parameterised by `T`) so the parameter is fixed once per instance rather than once per call. The two mechanisms use the same `TypeVar` object; what differs is the scope over which the solution holds. ## Where beginners go wrong Three recurring mistakes: reusing one module-level TypeVar in unrelated signatures and assuming that links them (it does not — solving is per call site); expecting `TypeVar` to reject bad arguments at runtime; and reaching for `Any` to silence a checker complaint that a TypeVar would have answered properly. The last one is the expensive one, because `Any` is contagious: it propagates through every expression built from the value, and a single `Any` in a hot helper can quietly de-type a whole call chain.