In Python type hints, why does hard-coding the class name as a fluent method's return type break subclasses?

### The checker believes the signature, not the body A type annotation is a promise, not a description. When a checker analyses `ScoredRule().tagged("fraud")`, it does not read the body of `tagged` to discover that it returns `self`; it reads the declared return type and uses that. So if the base class says ```python class Rule: def tagged(self, tag: str) -> "Rule": self.steps.append(tag) return self class ScoredRule(Rule): def with_threshold(self, t: float) -> "ScoredRule": self.steps.append(f"threshold={t}") return self ``` then `ScoredRule().tagged("fraud")` has static type `Rule`, and the next link, `.with_threshold(0.9)`, is an error: `Rule` has no such attribute. At run time nothing is wrong — `return self` returned the `ScoredRule` and the whole chain executes correctly. The defect lives entirely in the contract. ### Why it is contagious rather than local The failure is not one bad annotation in one place. Every inherited method that names the base class widens the expression again, so the damage compounds along a chain: reorder two links and the error moves; add a base-class method to the middle of a chain and a previously-clean subclass chain starts failing. Subclass authors cannot fix it from their side either. Overriding the method and re-annotating it with the subclass's own name works for that one method — narrowing a return type in an override is allowed — but every *other* inherited method still returns the base type, so the chain simply breaks at the first link you did not override. Re-declaring the entire fluent surface in every subclass is the maintenance cost `typing.Self` exists to abolish. ### The real damage is the workaround Consider a fraud-scoring service whose rule builder lives in a shared base class. The subclass adds `.with_features(...)` and `.with_threshold(...)`; the base class supplies `.tagged(...)` and `.named(...)` with their return types written as `Rule`. Chains stop checking, and the pragmatic fix that ships under time pressure is a `typing.cast` around the chain, or `# type: ignore` on the line. That is where a static-typing annoyance becomes a production bug. A cast asserts a type and stops the checker reasoning about the expression; an ignore comment suppresses *every* diagnostic on that line, not the one you meant. Later, a refactor drops a `.with_features(...)` link from the chain — and the suppression that was added to work around the annotation also hides the missing call. The scorer now runs on a truncated feature set, produces plausible-looking scores, and nothing fails. A checker that has been talked out of checking a chain is worse than never having annotated it, because the team believes it is covered. ### The fix, and what it costs Replace the hard-coded class name with `typing.Self`, added in Python 3.11 by PEP 673: ```python from typing import Self class Rule: def tagged(self, tag: str) -> Self: self.steps.append(tag) return self ``` The checker now re-binds `Self` per call site, so `ScoredRule().tagged("fraud")` is a `ScoredRule` and the chain continues cleanly. Run-time behaviour is byte-for-byte identical; the diff is one import and one word per method. There is one thing `Self` adds that the class name did not: it also constrains the body. Under `-> Self`, a body that returns a hard-coded `Rule()` is an error, because a subclass caller would receive a base instance. That is exactly the bug you want caught, and naming the class in the return type never caught it. Before 3.11 the same effect required a type variable bounded by the class and annotated onto the `self` parameter; libraries still supporting older interpreters carry that idiom. What was never correct, on any version, is simply writing the class's own name and hoping subclasses cope. ### How to spot it in review Two heuristics do most of the work. First, any method whose body ends in `return self` and whose return annotation is a concrete class name is a candidate — the annotation should almost always be `Self`. Second, treat a `cast` or an ignore comment wrapped around a method chain as a symptom, not a fix: it usually means somebody hit a widened return type and paid for silence rather than correcting the base class. Fixing the base class is a one-line change that deletes the suppression, and deleting the suppression is what restores checking to everything else on that line.