How do you annotate a Python @classmethod alternative constructor so subclasses get their own type?

### The two halves of an alternative constructor An alternative constructor in Python is a `@classmethod` that builds and returns an instance — `from_row`, `from_json`, `parse`, `from_percent`. Getting it right for subclasses has a run-time half and a static half, and both have to be done. The run-time half is to construct through `cls`, never through a hard-coded class name. Because a classmethod's first argument is bound to the class the call was made on, `CappedScore.from_percent(250)` binds `cls` to `CappedScore`, and `return cls(pct / 100)` therefore produces a `CappedScore`. Write `return Score(pct / 100)` instead and the subclass silently gets a base instance — a run-time defect, not merely a typing one, and one that inheritance was supposed to prevent. The static half is to annotate the return as `typing.Self`, the special form added in Python 3.11 by PEP 673: ```python from typing import Self class Score: def __init__(self, value: float) -> None: self.value = value @classmethod def from_percent(cls, pct: float) -> Self: return cls(pct / 100) ``` Inside the method `cls` is implicitly typed `type[Self]`, so `cls(...)` produces a `Self` and the annotation is satisfied. At a call site the checker re-binds `Self` to the receiver: `Score.from_percent(...)` is a `Score`, `CappedScore.from_percent(...)` is a `CappedScore`, and a chained subclass-only method after it still checks. Annotate the return as `-> Score` instead and every subclass caller gets the base type back — the same widening bug that breaks fluent chains, just arriving through the constructor. ### `__enter__` is the same shape A context manager whose `__enter__` returns the receiver wants the identical annotation, and for the identical reason: ```python def __enter__(self) -> Self: return self ``` With `-> Self`, `with CappedScore(0.5) as s:` binds `s` to `CappedScore`. With the base class named there, `s` is a `Score` for the entire body of every `with` block in every subclass — which is a worse blast radius than a broken chain, because the widened name is then used repeatedly rather than once. (The protocol itself — pairing with `__exit__`, suppression semantics, re-entrancy — is a separate subject; the point here is only which type the annotation should carry.) The same rule extends to any method that returns a *fresh* sibling object rather than the receiver, built as `type(self)(...)`. `Self` promises the type, not object identity, so that is a correct use. ### The contract you are signing This is where the interesting judgement lives. Declaring `-> Self` on a classmethod is an assertion that `cls(...)` works for **every** subclass — that is, that the base constructor's signature is inherited unchanged, or at least remains callable with the arguments the base method passes. If a subclass adds a required `__init__` parameter, the inherited classmethod raises `TypeError` at run time for that subclass, while the annotation continues to promise a valid `Self`. Almost nothing catches this. Type checkers deliberately exempt `__init__` and `__new__` from the override-compatibility rules they apply to ordinary methods, precisely because constructors routinely differ between a base class and its subclasses. So the promise made by `-> Self` on a classmethod is enforced by convention, not by tooling. Library base classes handle that in one of three ways. They document the constructor signature as part of the subclassing contract and treat changing it as a breaking change. They route construction through an overridable hook — a classmethod like `_create` that a subclass can redefine — so the alternative constructor never calls `__init__` positionally. Or they close the hierarchy: keep construction behind module-level factory functions and do not invite subclassing at all, which leaves the constructor free to change later. ### Rules of thumb Use `-> Self` on: a `@classmethod` that constructs via `cls`, an `__enter__` that returns the receiver, any method that returns `self`, and any method that returns `type(self)(...)`. Do not use it on a `@staticmethod` — there is no receiver for it to bind to and checkers report it as an error; if the class is needed, make the method a classmethod. Do not annotate `cls` explicitly; the checker supplies `type[Self]` and writing it out by hand mostly produces noise or mistakes. And do not read `-> Self` as a guarantee the interpreter enforces. Like every annotation it is erased — since Python 3.14, annotations are not even evaluated until something asks for them (PEP 649). It is a promise to readers and to checkers, and on a classmethod it is a promise about your subclasses' constructors as much as about your own return statement.