How does TypeVar('T', bound=X) differ from TypeVar('T', X, Y)?

## Two different questions Both forms narrow what a type parameter may be solved to, but they answer different questions. * **`bound=`** answers *what must this type be able to do?* It sets an **upper bound**: the solution may be the bound itself or any subtype of it. * **A value-constraint list** answers *which of these exact types is it?* It enumerates a **closed set**, and the solution must be one member of that set. ```python from typing import TypeVar S = TypeVar("S", bound=Stop) # Stop or any subtype N = TypeVar("N", str, bytes) # exactly str, or exactly bytes ``` ## What the checker does differently With a bound, solving is ordinary subtype inference and the **concrete argument type survives**. Pass a `Depot` (a subclass of `Stop`) to `def announce(place: S) -> S` and the call's type is `Depot`, so the caller can still use `Depot`-only members on the result. Inside the body you may use anything `Stop` provides, because every possible solution is at least a `Stop`. With constraints, the checker type-checks the *body once per listed type* and, at a call site, picks the single member the arguments fit. Two consequences follow, and both are commonly missed: 1. **Mixing is rejected.** For `def join(a: N, b: N) -> N` with `N` constrained to `str` and `bytes`, `join("a", b"b")` has no single solution and is an error — which is precisely the point, since concatenating the two is a runtime `TypeError` anyway. 2. **Subclasses are widened.** Pass an instance of a `str` subclass and the parameter is solved to `str`, not to the subclass; the return type comes back as `str`. A bound would have preserved it. ## When each is right Reach for a **bound** in the overwhelming majority of cases: * the function calls methods on the value, so it needs a guaranteed interface; * the set of acceptable types is open — callers add subclasses you have never seen; * the caller should get its own concrete type back rather than a widened one. The bound need not be a class: it may be a `Protocol`, so the constraint is structural ("anything with these methods") rather than nominal, and it may be written as a string forward reference when the class is defined later in the file. Reach for **constraints** only when the function truly has a separate meaning per listed type and no meaningful common supertype: the `str`/`bytes` split is the archetype, and `typing.AnyStr` was the stdlib's own instance of exactly that pattern. The list must contain **at least two** types — a one-element constraint list is an error, because it would just be a rename of that type — and you may not combine `bound=` with constraints in one declaration. ## A concrete way it goes wrong Consider a route-optimisation job whose helper is meant to accept any kind of stop and hand back the same kind. Written with constraints as `TypeVar("S", Stop, Depot)`, the code passes review and then misbehaves in two ways at once: a `Warehouse` subclass added three weeks later is rejected outright even though it is a perfectly good `Stop`, and passing a `Depot` may be solved to `Stop`, so the call site loses the `Depot`-only attributes it wanted. With `bound=Stop` both problems vanish — new subclasses are accepted for free and the concrete type is preserved. The rule of thumb: if you find yourself listing a base class *and* its subclasses in a constraint list, you wanted a bound. ## Runtime and declaration details Both forms are recorded on the `TypeVar` object at declaration time and neither is enforced when the program runs; a call that a checker rejects still executes. The bound expression is evaluated lazily on modern versions, which is why a string forward reference works. And note the asymmetry in reading the call: `TypeVar("N", str, bytes)` has no keyword to signal its meaning — positional arguments after the name *are* the constraint list, which is why the two forms are so easily confused in review. Say it out loud when you read one: "bound means subtypes allowed and preserved; a list means exactly these, widened."