Why can't @functools.singledispatch dispatch a method's argument, and what does functools.singledispatchmethod do?

## The silent failure The generic-function wrapper built by `@functools.singledispatch` looks at exactly one thing: the class of the first positional argument. It has no concept of a receiver. Put it on a method and the first positional argument is the instance: ```python import functools class Broken: @functools.singledispatch def render(self, value): return "fallback" @render.register def _(self, value: int): return "int" Broken().render(3) # 'fallback' ``` Nothing raises. The registration for `int` is real and sits in the registry, but resolution is performed against the class of the instance — `Broken` — which is not registered, so the walk lands on `object` and the fallback runs. Every call on every instance of that class picks the same implementation, and the only symptom is that your carefully registered branches never execute. Registering the *class* would work, but that dispatches on the receiver, which is what ordinary method overriding already does. ## What singledispatchmethod adds `functools.singledispatchmethod`, added in 3.8, wraps the same registry machinery in a **descriptor** — an object that defines `__get__` and therefore gets a say in what attribute access on an instance produces. Accessing `instance.render` calls `__get__`, which returns a small bound callable that resolves the implementation from the class of the *next* positional argument, then calls it with the instance reinstated in front. So the receiver is passed through untouched, and dispatch happens on the argument you actually care about. ```python import functools class Report: @functools.singledispatchmethod def render(self, value): return f"raw {value!r}" @render.register def _(self, value: int): return f"int {value}" @render.register def _(self, value: list): return f"list of {len(value)}" ``` Every implementation still takes `self` first and the dispatched value second, and the annotation that drives registration is on that second parameter. Resolution rules are identical to the plain function case: the nearest registered ancestor of the argument's class wins, registration order is irrelevant, and the decorated body is the `object` fallback. ## Stacking with classmethod and staticmethod Both combinations work, with one hard ordering rule: `singledispatchmethod` must be the **outermost** decorator, because the registration API lives on it and the inner decorator would otherwise hide it. Applied to a class method, dispatch is on the first argument after `cls`: ```python import functools class Loader: @functools.singledispatchmethod @classmethod def load(cls, source): return f"generic {cls.__name__}" @load.register @classmethod def _(cls, source: str): return f"{cls.__name__} from {source}" ``` The inner decorator has to be repeated on each registered implementation, not just on the base definition. ## The registry is shared with subclasses The descriptor object — and the registry inside it — is an attribute of the class where it was defined. A subclass that registers an extra implementation on the inherited generic method is mutating that same shared registry, so the base class and every sibling subclass see the new implementation too: ```python import functools class Base: @functools.singledispatchmethod def render(self, value): return "base-fallback" class Sub(Base): @Base.render.register def _(self, value: float): return "sub-float" Base().render(1.0) # 'sub-float' — the base class changed too ``` That is rarely what a reader expects. If a subclass needs its own set of implementations, define a fresh `singledispatchmethod` in the subclass — which shadows the inherited attribute and starts with an empty registry — and delegate to the base implementation from its fallback if you still want the old behaviour. ## When to reach for it A generic *method* is worth the machinery when the operation belongs to an object with state — a renderer holding configuration, a differ holding options — but must branch on the class of the thing it is handed, and that set of classes is open. If the receiver carries no state, a module-level `singledispatch` function is simpler. And if you own the classes being dispatched on, an ordinary method on each of those classes remains the most discoverable answer: dispatch machinery earns its place mainly for classes you cannot or should not modify. ## Introspection is thinner here A plain generic function exposes both a registry mapping and a way to resolve a class to its implementation without calling it. The bound callable you get from attribute access on a generic *method* is thinner: it carries the registration API and nothing else, so there is no registry or resolution helper on `instance.render` or on `Report.render`. To inspect coverage — in a test that proves a registration landed, for instance — reach the descriptor object itself out of the class dictionary and use its dispatcher, which is an ordinary generic function with the full introspection surface. It is a small wrinkle, but one that surprises people who try to write the same coverage assertion they use for module-level generic functions.