What does the @functools.singledispatch decorator do to the function it decorates?

A **generic function** in Python's standard-library sense is a single callable name backed by several implementations, one chosen per call from the type of an argument. `functools.singledispatch` (added in 3.4) is the standard library's way of building one, and "single" is literal: it dispatches on exactly one argument, the first positional one. ## What the decorator actually returns `@singledispatch` does not return your function. It returns a wrapper function that carries a small registry, and it enters your original function into that registry under `object`. Because every class derives from `object`, your original body becomes the **fallback** — the implementation used whenever no more specific one matches. Metadata such as `__name__` and `__doc__` is copied onto the wrapper, the same way `functools.wraps` copies it, so the generic function still looks like the function you wrote. The wrapper exposes three useful attributes: * `register()` — add an implementation for a type. * `dispatch(cls)` — return the implementation that *would* be used for that class, without calling it. Excellent in tests. * `registry` — a read-only mapping of type to implementation, which always contains at least the `object` entry. ## The three registration forms ```python from functools import singledispatch @singledispatch def describe(value): # the object fallback return f"object: {value!r}" @describe.register # by annotation (3.7+) def _(value: int): return f"int: {value}" @describe.register(list) # by explicit type def _(value): return f"list of {len(value)}" describe.register(float, lambda v: f"float: {v:.2f}") # call form ``` The annotation form reads the annotation of the **first parameter**; anything else on the signature is ignored for registration. Since 3.11 a union annotation such as `def _(v: int | float)` registers the implementation for both members. The explicit-type form is what you need when there is no annotation to read — a lambda, or a callable you did not write. Note the third, non-decorator call form: `register(type, function)` — handy for registering something defined elsewhere. Every registration returns the *undecorated* function, which is why the idiom of naming each implementation `_` works: the name is rebound each time and nothing depends on it. Give them real names if you would rather read a traceback that says `describe_int`. ## What happens on a call Dispatch is per call and cheap. The wrapper takes `type(args[0])`, looks it up in a cache, and on a miss walks the argument type's method resolution order (plus any abstract base classes registered as virtual parents) to find the most derived registered class. The chosen implementation is then called with *all* the original arguments unchanged — dispatch selects, it does not rewrite the call. Two consequences trip people up early: * **Keyword arguments never dispatch.** Calling `describe(value=3)` does not select the `int` implementation; it raises `TypeError: describe requires at least 1 positional argument`, because there is no first positional argument to look at. * **Only the first argument matters.** `def merge(a, b)` dispatches on `a` alone. Multiple dispatch on `(a, b)` is not something `singledispatch` does; you would need a nested dispatch or a third-party library. The cache is invalidated whenever the registry changes, so registering a new implementation later — from another module, at import time — takes effect immediately, including for types that had already been dispatched. ## Why reach for it The alternative shape is a chain of `isinstance` tests inside one function. That chain is *closed*: every new type means editing the function, and the branch order silently decides which test wins. `singledispatch` is *open*: a plugin module can register a handler for its own type without touching the original code, and resolution follows class relationships rather than the order you happened to write the branches in. The cost is that the dispatch decision is now spread across the codebase, so `dispatch()` and `registry` matter for debugging.