In a Generic[T] class, when should a method declare its own TypeVar?

## Two scopes, one syntax Both kinds of parameter are ordinary `TypeVar` objects; what distinguishes them is **where they are bound**. * A parameter named in the class's generic base — `class Leg(Generic[T])` — is **class-scoped**. It is solved when an instance is created (or when an annotation writes `Leg[int]` explicitly) and stays fixed for that object. Every method body may rely on it, and every method signature that mentions `T` means *this instance's* `T`. * A parameter that appears only inside one method's signature is **method-scoped**. It is solved at each call of that method, independently of the instance and independently of previous calls. ```python class Leg(Generic[T]): def __init__(self, payload: T) -> None: self.payload = payload def map(self, fn: Callable[[T], R]) -> "Leg[R]": return Leg(fn(self.payload)) ``` `T` is class-scoped and pinned by construction; `R` is method-scoped and comes out of whatever callable this particular call was handed. `Leg(3).map(str)` is a `Leg[str]` built from a `Leg[int]`, and the checker tracks that without any casting. ## The decision rule Ask: **does this type vary per object, or per call?** * *Per object* — the element type of a container, the payload a wrapper holds, the row type a repository returns. Class-scoped. * *Per call* — the result type of a transform, the type of a caller-supplied fallback, the type a converter produces. Method-scoped. A related test is whether the type appears in `__init__` or in any attribute annotation. If it does, it describes the instance's state and belongs on the class. If it appears only in one method's parameters and return, it belongs on that method. ## The classic failure The mistake is to reuse the class parameter for a per-call type, because it is already in scope and looks convenient: ```python class Leg(Generic[T]): def map(self, fn: Callable[[T], T]) -> "Leg[T]": ... # too tight ``` Now `map` can only apply transformations that return the *same* type it started with. A route-optimisation job that stores `Leg[int]` distances and wants formatted labels out of them has no way to say so; the checker will reject `leg.map(str)`, and the usual reaction is to reach for a cast or `Any`, which throws away exactly the information the class was written to preserve. The same trap appears on lookup helpers: `def get(self, key: str, default: T) -> T` forces the caller's fallback to match the stored type, whereas a method-scoped second parameter lets `get(k, default=None)` widen the result honestly. ## The other direction is also a bug The mirror-image mistake is declaring a method-scoped parameter for a type that *is* the instance's own. If `def replace(self, item: R) -> "Leg[R]"` is meant to swap the payload in place, the checker now believes an arbitrary unrelated type can be stored in a container whose class parameter says otherwise. A parameter that describes stored state and is not in the class's parameter list is a hole in the class's own invariant. ## What a class-scoped parameter buys the body Inside a generic class, `T` behaves in method bodies exactly as it does in generic functions: unless it carries a bound, the body may only do object-level things with it. Storing it, returning it and passing it on are fine; calling methods on it is not. Attributes annotated with `T` are the normal way to carry it, and constructing a *new* instance of the class parameterised differently — `return Leg(fn(self.payload))` — is how transforms are written, because the class parameter of the new object is solved from its own constructor argument. ## Runtime notes None of this scoping exists at runtime. `Leg[int]` produces a subscripted alias object rather than a new class; calling it constructs an ordinary `Leg`, and the instance's `type()` is `Leg` with no record of the argument. `isinstance` against a subscripted generic raises `TypeError` outright, precisely because the information needed to check it was never kept. So the scoping discipline above is entirely for the checker, the editor and the reader — which is also why getting it wrong is cheap to fix and easy to leave broken: nothing crashes, callers just quietly lose type information or reach for escape hatches.