Single Dispatch Generic Functions

Welcome back to the second lesson in the Functional Patterns & Pattern Matching in Python course! In the previous lesson, we mastered production-grade decorators by building a configurable retry mechanism with exponential backoff and jitter. We learned how decorators can wrap functions to add reusable behavior while preserving metadata and type safety.

Today, we're exploring another powerful functional pattern: single dispatch generic functions. While decorators modify function behavior, generic functions adapt their implementation based on the type of their arguments. This pattern is essential when you need different behavior for different data types without cluttering your code with long chains of isinstance checks. We'll build a JSON serializer that handles datetime objects, Decimal numbers, custom data classes, and nested containers, all using Python's functools.singledispatch decorator. By the end of this lesson, you'll be able to create extensible, type-aware functions that are easy to maintain and extend.

A generic function is a function that performs conceptually the same operation but implements it differently depending on the input type. For example, serializing an object to JSON requires different strategies: a string stays as is, a datetime needs ISO format conversion, and a custom object might need dictionary transformation.

The traditional approach uses conditional logic:

def serialize_old(obj):
    if isinstance(obj, str):
        return obj
    elif isinstance(obj, datetime):
        return obj.isoformat()
    elif isinstance(obj, Decimal):
        return str(obj)
    # ... many more conditions

This approach has several problems. Adding support for new types requires modifying the function, violating the open/closed principle. The logic becomes harder to read as more types are added. Most importantly, third-party code can't extend the function without modifying your source.

Generic functions solve these issues by separating the concept (serialize this object) from the implementation (how to serialize each specific type). This separation makes the code more modular, testable, and extensible.

Python's functools.singledispatch decorator implements the single dispatch pattern, which selects an implementation based on the type of a single argument (typically the first). The pattern works through registration: you define a base function that handles the default case, then register specialized implementations for specific types.

Here's the basic structure:

from functools import singledispatch

@singledispatch
def to_json_serializable(obj):
    # Default implementation
    raise TypeError(f"Unsupported type: {type(obj).__name__}")

@to_json_serializable.register
def _(obj: Decimal):
    # Handle Decimal specifically
    return str(obj)

The base function decorated with @singledispatch establishes the generic function. The .register decorator adds type-specific implementations. Notice the implementation function is named _: since we access the function through the generic name to_json_serializable, the individual implementation names don't matter. This convention signals that these are internal implementation details.