singledispatch and Generic Functions

## The resolution walk Every call does two things: read the class of the first positional argument, then find the best implementation for that class. The first step reads `__class__` rather than calling `type()`, which matters only for proxy objects that lie about `__class__` — such an object is dispatched as the class it claims to be. The second step is the interesting one. The registry is keyed by class, and the argument's class is usually not in it — you register `collections.abc.Mapping` and the caller hands you some concrete mapping class. So the resolver walks the argument class's **method resolution order**: the linearised list of ancestors that the class itself uses for attribute lookup, starting at the class and ending at `object`. The first ancestor that has a registration wins. Because `object` is always registered (that is the decorated body), the walk always terminates with an answer. Two consequences follow immediately. **Registration order is irrelevant.** Whether you register `date` before or after `datetime` changes nothing; the ancestor list decides. This is the single biggest behavioural difference from an `if/elif isinstance` chain, where a base-class branch written first silently swallows every subclass and the subclass branch below it is unreachable. **Inheritance you forgot about still counts.** The classic traps in the standard library's own hierarchy: - `bool` is a subclass of `int`, so an implementation registered for `int` handles `True` and `False` unless you register `bool` separately. - `datetime.datetime` is a subclass of `datetime.date`, so registering `date` quietly handles datetimes — usually not what a formatter wants. - `str` is a `collections.abc.Sequence`, so registering `Sequence` to mean "a list-like thing" also captures strings, which are then iterated character by character. ```python import functools, datetime @functools.singledispatch def fmt(value): return "generic" @fmt.register def _(value: datetime.date): return "date" print(fmt(datetime.datetime(2026, 1, 1))) # 'date' ``` ## Abstract base classes and virtual subclasses A class can be an ancestor without appearing in the ordinary ancestor list: abstract base classes accept *virtual* subclasses, either registered explicitly or recognised structurally by a subclass hook. `list` is not literally derived from `collections.abc.Sequence`, yet it counts as one. The resolver handles this by composing a merged ordering that splices the relevant abstract base classes into the class's own ancestor list before walking it. So abstract base classes are fully usable as registration keys, and a concrete class registered directly still beats an abstract base class that the same object also satisfies. ## Ambiguity is an error, not a guess The merged ordering can be genuinely undecidable. If an object satisfies two abstract base classes that are unrelated to each other — neither is an ancestor of the other — and both have registrations, there is no principled "nearest". Rather than pick arbitrarily, the resolver raises `RuntimeError: Ambiguous dispatch` naming both candidates. ```python import functools from collections.abc import Sized, Container @functools.singledispatch def size(value): return "generic" @size.register(Sized) def _(value): return "sized" @size.register(Container) def _(value): return "container" size([1, 2]) # RuntimeError: Ambiguous dispatch ``` The fix is to be explicit: register the concrete class you actually care about, so the walk finds it before reaching either abstract base class. Note that this error surfaces at **call** time, on whatever class first triggers the collision — a registration that looks fine in isolation can blow up on one caller's input months later, which is a good argument for asserting coverage in tests. ## Proving what will happen Two attributes make the behaviour testable without calling anything. `name.registry` is a read-only mapping of registered class to implementation. `name.dispatch(cls)` runs exactly the resolution walk described above and hands back the function that `cls` would select. A test that asserts `fmt.dispatch(bool) is not fmt.dispatch(int)` is a direct, readable way to pin down the `bool`/`int` trap, and one that asserts `fmt.dispatch(SomeClass) is not fmt.dispatch(object)` proves a plugin module was actually imported. ## The cache Resolution results are memoised per class in a weak-keyed cache, so the walk runs once per class rather than once per call and steady-state dispatch is close to a dictionary lookup plus a call. Calling `register` invalidates that cache, because a new registration can change the answer for classes already resolved. Registration is therefore an import-time activity: mutating the registry while other callers are dispatching changes shared state underneath them for no benefit.