Why does a functools.singledispatch handler registered for int also receive True?

Dispatch here is a *resolution*, not a lookup by exact type — and that is exactly what makes it useful and what makes it surprising. ## How the implementation is chosen Given a call, `singledispatch` takes `type(args[0])` and finds the implementation registered for the most derived class in that type's method resolution order, taking registered abstract base classes into account as well. The result is cached per type, and the cache is dropped whenever a new implementation is registered. Registration order is irrelevant; class relationships decide. The three traps that follow are all the same trap wearing different clothes. ### 1. `bool` is an `int` `bool` subclasses `int` in Python. An implementation registered for `int` therefore handles `True` and `False` too: ```python @to_cm.register def _(value: int): return float(value) to_cm(True) # 1.0 -- the int implementation ran ``` Consider a museum-catalogue importer normalising heterogeneous field values. A boolean "on display" flag arrives in the same column stream as integer dimensions, and the int implementation cheerfully turns it into `1.0` centimetres. If booleans are not valid input, register `bool` explicitly and raise from it — a registration for the narrower class always wins over the broader one. ### 2. Abstract base classes are wider than they look `str` is a registered virtual subclass of `collections.abc.Sequence`, as are `bytes`, `tuple` and `list`. A handler registered for `Sequence` that recurses into its elements will therefore recurse into a string, whose elements are one-character strings, which are also Sequences — an unbounded recursion ending in `RecursionError`. Register `str` (and usually `bytes`) explicitly before registering any Sequence handler, or key on `list`/`tuple` rather than the abstraction. The same abstraction width produces a second, rarer failure: if a class is a registered virtual subclass of two abstract base classes that both have implementations, and neither is more derived than the other, the resolution is genuinely ambiguous and `singledispatch` raises `RuntimeError: Ambiguous dispatch: <class 'A'> or <class 'B'>`. That is the library refusing to guess, and the fix is to register the concrete class directly. ### 3. The fallback catches everything, quietly The most expensive trap is the one that neither raises nor recurses. A type that matches no registration is not an error — it lands on the `object` implementation you wrote as the base. In the importer, `decimal.Decimal` is **not** a subclass of `float` and is not registered as one, so a decimal measurement slips past the float implementation and into a fallback that does `float(value)`. Everything still runs, and the catalogue quietly acquires a floating-point rounding drift: ```python round(float(Decimal("2.675")), 2) # 2.67, not 2.68 ``` Two centimetres of drift across a few thousand rows is exactly the kind of defect that is found months later by someone reconciling totals. The reason it survived is that the fallback made a plausible-looking value out of a type nobody had thought about. ## Defences * **Make the fallback raise.** `raise TypeError(f"no handler for {type(value).__name__}")` in the base implementation converts every unforeseen type from a silent guess into an immediate, named failure. Reserve a permissive fallback for cases where "do the generic thing" is genuinely correct. * **Register the narrow type when you mean to exclude it.** `bool` under `int`, `str` and `bytes` under `Sequence`. An explicit registration is the only way to say "not this one". * **Assert resolution in tests.** The generic function's `dispatch()` attribute returns the implementation that would be chosen for a class, so a test can pin `bool`, `Decimal` and `str` to the implementations you intend, without going through behaviour. * **Prefer concrete classes to abstractions** in registrations unless you have deliberately reasoned about everything the abstraction covers — which, for the sequence and number abstractions, is more than most people expect. An `isinstance` ladder has the very same subclass semantics; the difference is that the ladder makes the ordering visible in one place, while `singledispatch` resolves it by class relationship. Neither saves you from `bool` being an `int`.