Why does @functools.singledispatch always run the fallback when applied to a method?

This is the single most common way a first attempt at type dispatch goes wrong, and it is nasty because it fails **silently**. ## The failure ```python from functools import singledispatch class Importer: @singledispatch def visit(self, node): return "fallback" @visit.register def _(self, node: int): return "int" Importer().visit(3) # -> 'fallback', not 'int' ``` `visit` is a generic function like any other. When you call `Importer().visit(3)`, ordinary method binding passes the instance as the first positional argument, so dispatch inspects `type(self)` — `Importer` — not `type(3)`. `Importer` matches nothing but the `object` entry, so the fallback runs. Every registration on the method is unreachable, on every call, forever. No exception, no warning; the tests that only exercise the fallback path pass. ## The fix: singledispatchmethod `functools.singledispatch` **method** (3.8+) exists precisely for this. It is a descriptor: accessing it through an instance or a class returns a bound wrapper that holds onto `self`/`cls` and dispatches on the **next** positional argument. ```python from functools import singledispatchmethod class Importer: @singledispatchmethod def visit(self, node): return "fallback" @visit.register def _(self, node: int): return "int" Importer().visit(3) # -> 'int' ``` The registration forms are the same as for the plain decorator — an annotation on the dispatched parameter (which is now the *second* parameter, after `self`), or an explicit class passed to `register`. The registry lives on the `singledispatchmethod` object created in the class body, so it is shared by all instances of the class; there is no per-instance registry, and registering at runtime from one instance affects every instance. ## Ordering with classmethod and staticmethod `singledispatchmethod` composes with the other method decorators, and the order is not symmetric: ```python class Row: @singledispatchmethod @classmethod def parse(cls, raw): return f"unhandled {type(raw).__name__}" @parse.register @classmethod def _(cls, raw: int): return f"count {raw}" ``` `singledispatchmethod` has to be **outermost**, both on the base implementation and on each registration. The reason is mechanical: `register` is an attribute of the `singledispatchmethod` object, so whatever ends up on the outside must be the object that carries it. Wrap it the other way round — ```python @classmethod @singledispatchmethod def parse(cls, raw): ... ``` — and the class body raises `AttributeError: 'classmethod' object has no attribute 'register'` at import time, because a `classmethod` object has no `register`. Getting the import-time error is the lucky case; the truly silent failure is the plain-`singledispatch`-on-a-method version above. `@staticmethod` nests the same way, and there dispatch is on the first parameter because there is no `self` to skip. ## Inheritance and overrides Dispatch and inheritance are two independent mechanisms here, and it pays to say so explicitly in an interview. A subclass that redefines the method replaces the whole generic method, registry and all — it does not "add to" the parent's registry. To extend rather than replace, register additional implementations against the parent's method object, or design the base class to expose a registration hook. There is also no way to register an implementation "for subclasses of this class, but only when called on that subclass" — the registry keys on the *argument's* type, never on the receiver's. ## How to catch it in review Two cheap habits: make the base implementation `raise TypeError(...)` rather than returning something plausible, so an unresolved type is loud rather than quietly wrong; and assert dispatch in tests via the generic function's `dispatch()` attribute with the class you expect, which fails immediately when a registration is unreachable.