What does typing.Self mean as a return annotation on a Python method?

### What the annotation has to express A method that ends in `return self` — a fluent builder step, an `__enter__`, an in-place mutator that hands the object back so calls can be chained — has a return type that cannot be written down as a fixed class. The honest answer is "whatever class the caller was actually holding", and until Python 3.11 the type system had no direct way to say that. `typing.Self`, specified by PEP 673, is that way: a special form, valid only inside a class body, that a checker re-resolves at every call site to the type of the receiver. Concretely, given ```python from typing import Self class Query: def where(self, clause: str) -> Self: self.parts.append(clause) return self ``` a checker reading `Query().where("x")` types the expression as `Query`. Reading `AuditedQuery().where("x")`, where `AuditedQuery` subclasses `Query` and does not override `where`, it types the expression as `AuditedQuery`. One annotation, two answers, and nothing duplicated into the subclass. ### The three canonical places it belongs **Fluent chains.** Every step of a builder that mutates the receiver and returns it is annotated `-> Self`. This is the case the feature is named for: without it, the first inherited step in a chain widens the static type back to the base class, and every subclass-only step after it is reported as an unknown attribute. **Alternative constructors.** A `@classmethod` that builds an instance — `from_row`, `from_percent`, `parse` — is annotated `-> Self` and constructs with `cls(...)`. Inside such a method `cls` is implicitly typed `type[Self]`, so the object it builds is the receiver's class and the signature now says so. **`__enter__`.** A context manager whose `__enter__` hands back the object itself annotates `-> Self`, so `with Subclass() as handle:` binds `handle` to the subclass rather than to the base class. There is a fourth, quieter case: a method that returns a *fresh* object of the receiver's class, built as `type(self)(...)`. `Self` describes the returned type, not object identity, so this is entirely legitimate — and a checker will object if such a body hard-codes a class name instead, which is a useful extra check you get for free. ### What happens at run time Nothing at all. `Self` is an annotation, and annotations do not constrain execution. Since Python 3.14 they are not even evaluated when the function is defined: PEP 649 replaced eager evaluation with lazy evaluation, so the annotation expression runs only when something actually asks for a function's annotations. Either way, `Self` imposes no check. A method annotated `-> Self` whose body returns `42` runs happily; only the checker complains. Two useful consequences follow. Importing `Self` costs nothing measurable, and there is no forward-reference problem to solve: `Self` is an ordinary name in `typing`, always resolvable, never needing quotes — unlike writing the class's own name inside its own body, which on Python 3.13 and earlier had to be quoted because the class did not exist yet. ### Where it is legal, and where it is not `Self` only means something where there is a receiver. It is valid inside a class body — as a method's return annotation, as a parameter annotation, and as an attribute annotation — and meaningless at module level or in a plain function, where checkers reject it. It is also rejected in a `@staticmethod`, which by construction has no receiver for it to bind to; if a static helper needs the class, make it a classmethod so `cls` exists. Inside nested classes, `Self` refers to the innermost enclosing class. One modelling limit is worth naming out loud. `Self` has exactly one meaning per class, so it cannot express a relationship between two *different* types — "accepts another object of the receiver's own class and returns a pair of them", say, or "returns a related but distinct class". Signatures like that still need a named type variable you can mention in several positions. `Self` makes the overwhelmingly common case cheap; it is not a replacement for every parametrised signature. ### Why it matters more than it looks The alternative to `Self` is not merely "slightly less precise hints" — it is casts. Once a chain's static type has collapsed to the base class, the fastest way for a caller to silence the checker is `typing.cast` or a blanket ignore comment, and both of those switch off checking for everything else in that expression too. A single narrow annotation on a popular base class therefore buys suppressed diagnostics across every consumer that chains from it. `Self` costs one import and removes the pressure entirely, which is why it is now the default habit rather than a refinement.