Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Python Single Dispatch: Type-Based Function Overloading

Learn how Python's functools.singledispatch replaces isinstance chains with registered type-specific handlers for type-based function overloading.

~4 min readPython
#functools#generic functions#type dispatch#polymorphism
Illustration of a Python function dispatching to different type-specific implementations based on the first argument's type.

Python's functools.singledispatch decorator turns a plain function into a generic function that dispatches on the type of its first argument. Python single dispatch is the standard library's answer to function overloading: instead of writing isinstance chains, you register type-specific implementations and let the runtime pick the right one.

The Problem: Type-Checking Chains

Consider a function that formats values for display:

python
def format_value(value): if isinstance(value, int): return f"integer: {value}" elif isinstance(value, float): return f"float: {value:.2f}" elif isinstance(value, str): return f"string: {value!r}" elif isinstance(value, list): return f"list of {len(value)} items" else: return f"unknown: {type(value).__name__}"

This works, but every new type means editing the function and extending the chain. The dispatch logic is entangled with the formatting logic, and the order of checks matters: if you add a bool check after int, True and False will be treated as integers because bool subclasses int. Each addition makes the function harder to read and test.

Basic singledispatch Syntax

The same logic with singledispatch separates dispatch from implementation:

python
from functools import singledispatch @singledispatch def format_value(value): return f"unknown: {type(value).__name__}" @format_value.register def _(value: int): return f"integer: {value}" @format_value.register def _(value: float): return f"float: {value:.2f}" @format_value.register def _(value: str): return f"string: {value!r}" @format_value.register def _(value: list): return f"list of {len(value)} items"

The base function decorated with @singledispatch becomes the generic entry point. Its body serves as the fallback for unregistered types. Each registered function is keyed by the type annotation on its first parameter. Calling format_value(42) resolves to the int implementation; calling format_value([1, 2]) resolves to the list implementation.

How Dispatch Resolves Types

When you call the generic function, singledispatch checks the argument's exact type in its registry. If that type isn't registered, it looks for a registered base class, including virtual subclasses recognized through ABC registration. This is why registering for object catches everything, and why registering for a base class like collections.abc.Sequence catches list, tuple, and str — unless a more specific registration for that type exists, in which case the specific one wins.

The resolution happens once per concrete type and is cached. Subsequent calls with the same type use the cached implementation directly.

Registering with Explicit Types

Type annotations are optional. The register method accepts an explicit type:

python
@format_value.register(dict) def format_dict(value): return f"dict with {len(value)} keys"

Use this form when the function name matters for readability, when the annotation would be ambiguous, or when you want to register a type that isn't the first parameter's annotation. The two forms are interchangeable; the registry keys on the type, not on the function name.

Registering for Abstract Base Classes

singledispatch works with ABCs, which lets you handle a family of related types with one implementation:

python
from collections.abc import Mapping @format_value.register(Mapping) def _(value: Mapping): return f"mapping with {len(value)} keys"

Because dict is a virtual subclass of Mapping, and OrderedDict inherits from dict, both resolve to this implementation. singledispatch accounts for ABC-registered virtual subclasses, so the dispatch works even for types that don't inherit from the ABC directly.

A Practical Example: Recursive Serialization

Here's a realistic use case: a serializer that converts Python values to JSON-compatible structures.

python
from functools import singledispatch from datetime import datetime from pathlib import Path @singledispatch def to_json_value(value): raise TypeError(f"cannot serialize {type(value).__name__}") @to_json_value.register def _(value: int): return value @to_json_value.register def _(value: float): return value @to_json_value.register def _(value: str): return value @to_json_value.register def _(value: bool): return value @to_json_value.register def _(value: datetime): return value.isoformat() @to_json_value.register def _(value: Path): return str(value) @to_json_value.register def _(value: list): return [to_json_value(item) for item in value] @to_json_value.register def _(value: dict): return {key: to_json_value(item) for key, item in value.items()}

The base function raises TypeError for unsupported types, which is the right behavior for a serializer: fail loudly rather than silently producing wrong output. Nested structures work because the list and dict implementations call to_json_value recursively, and dispatch happens per element.

Performance and Dispatch Overhead

singledispatch caches the resolved implementation per concrete type. The first call for a given type performs the type-resolution lookup; subsequent calls use the cached result. The per-call overhead is a dictionary lookup plus a function call, which is comparable to calling the function through a dict of handlers.

For typical application code, this overhead is negligible. If you're dispatching millions of times per second in a hot loop, consider whether the dispatch can be hoisted out of the loop or replaced with a plain dictionary keyed by type. The tradeoff is that a manual dictionary loses the registered-base-class fallback behavior.

When Not to Use singledispatch

singledispatch only considers the first argument. If you need dispatch on multiple arguments, it won't help. For methods, functools.singledispatchmethod provides the same mechanism, but it dispatches on the first argument after self (or cls) and is still limited to one dispatch argument.

Dispatch resolution can also surprise you. If you register handlers for both Sequence and str, a str argument resolves to the str handler because the exact type is checked before registered base classes or ABCs. Understanding the resolution order is essential when registering for both concrete types and ABCs.

ApproachDispatch basisExtensibilityRuntime cost
isinstance chainManual checksEdit functionO(n) checks
singledispatchFirst argument typeRegister new handlerCached lookup
Method dispatchself typeSubclass the classDirect call

Compatibility and Union Types

singledispatch was added in Python 3.4. The explicit-type form of register works from 3.4 onward. The annotation-based form requires the annotation to be a concrete type at decoration time, which is what happens unless from __future__ import annotations is in effect.

Union types are not supported. @format_value.register with int | str will not dispatch correctly. Register each type separately, or register a common base class that both types share.

Debugging Dispatch Behavior

If a registered function never gets called, inspect format_value.registry — it's a plain dict mapping types to functions. Check whether the argument's type resolves to a different registered base class or ABC, and verify that the annotation on the first parameter is present and is a real type, not a string.

Try matching browser tools

All tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.