What does @functools.singledispatch do to a function, and how do you register an implementation for a type?

## The shape of a generic function A *generic function* in the `functools` sense is a single public name whose behaviour is chosen from the class of one argument, with the implementations stored in a registry rather than written as branches in one body. `@functools.singledispatch` (in the standard library since 3.4) builds one for you. It returns a wrapper that carries the registry plus a small API, and it registers the function you decorated under `object` — so the decorated body is not dead code, it is the fallback that runs whenever nothing more specific matches. ```python import functools @functools.singledispatch def describe(value): return f"object: {value!r}" ``` At this point `describe` behaves exactly like the function you wrote. What changed is that it now has a `register` attribute. ## Three ways to register **By class.** `@describe.register(str)` names the class explicitly and ignores annotations entirely. Use it when the parameter has no annotation, or when the annotation is not the class you want to dispatch on. **By annotation.** Since 3.7 a bare `@describe.register` reads the class from the first annotated parameter: ```python @describe.register def _(value: int): return f"int: {value}" ``` The annotation is resolved when the decorator runs, not when the function is called, so the class has to exist at that moment; a forward reference to a class defined later fails at registration with a `TypeError`. Since 3.11 the annotation may be a union — `def _(value: int | float)` registers one implementation for both members. Before 3.11 that raised `TypeError`. **As a plain call.** `describe.register(str, my_impl)` registers an existing function without decorator syntax, which is what you want when the implementation is defined elsewhere or built dynamically. The common idiom names every implementation `_`, because `register` returns the function unchanged and the name is never used again — dispatch reaches the implementation through the registry, not through its name. Giving each one a real name is equally valid and makes tracebacks and direct unit tests nicer. ## What is dispatched on, and what is not Only the **first positional argument** participates, and the wrapper reads its `__class__`. Everything else about the call — the second argument, keyword arguments, the return annotation — is irrelevant to the choice. Two consequences bite in practice. First, if there is no positional argument at all the wrapper raises `TypeError: <name> requires at least 1 positional argument`. A caller that writes `describe(value=3)` gets that error, not the `int` implementation. If your API must accept the dispatched value by keyword, either keep the first parameter positional-only in spirit or resolve the implementation yourself with `name.dispatch(...)`. Second, the registry key must be a **class**. A subscripted generic is not one: registering an implementation annotated `list[int]` raises `TypeError: Invalid annotation for 'value'. list[int] is not a class.` Register `list` and inspect the elements inside the body if you need element-level behaviour. ## Introspection The wrapper exposes two useful attributes. `name.registry` is a read-only mapping from registered class to implementation, always containing at least `object`. `name.dispatch(cls)` returns the implementation that `cls` would select, without calling it — the direct way to unit-test that a registration landed where you expected, and the tool for resolving an implementation once and calling it in a loop. There is also an internal per-class cache so repeated calls with the same class skip the resolution walk. Registering a new implementation clears that cache, which is one reason registration belongs at import time rather than in the middle of a request. ## Where it earns its place The motivating case is an operation you want to extend for classes you do not own or do not want to touch: serialising builtins and third-party classes, formatting values for a report, converting between representations. Each type's owner registers its own implementation from its own module, and the operation's original module never grows another branch. That is also the limit of the tool: when the behaviour genuinely belongs to the data, an ordinary method on the class is more discoverable and does not need a registry at all. ## The wrapper is still an ordinary function Nothing about the result is exotic. The decorator copies the original function's metadata onto the wrapper, so the name and docstring survive and the generic function documents and introspects like the function you wrote. It can be assigned, passed as a callback, imported by other modules and called normally; the registry is simply extra state hanging off it. That matters for a practical reason: swapping an existing plain function for a generic one is a non-breaking change for every caller, because the call signature and the behaviour for already-handled inputs are unchanged. You add the decorator, then add registrations one class at a time, and the fallback keeps the old behaviour for everything you have not covered yet.