How Python’s singledispatch Simplifies Custom JSON Serialization

Many Python standard‑library modules contain hidden gems, and one of the most useful is the type‑based function dispatch provided by functools.singledispatch. It is ideal for serializing arbitrary objects, such as when producing JSON for web APIs or structured logs.

Traditional JSON Serialization

The built‑in json module (inherited from simplejson) offers two ways to serialize objects: (1) implement a default() function that receives an object and returns something the JSONEncoder can understand; (2) subclass JSONEncoder and pass it via the cls argument to dump. Both approaches require you to know every custom type in advance, making the code brittle and hard to extend.

Because third‑party libraries often mimic the json API for compatibility, they inherit the same limitations.

Extensibility Issues

All of the above methods share a lack of extensibility: they do not provide support for new types without modifying a central default() function. Writing a monolithic function that handles every custom type quickly becomes painful.

Some projects, like Pyramid’s JSON renderer, use the adapter registry from zope.interface to achieve a more modular solution. Django supplies DjangoJSONEncoder, a subclass of json.JSONEncoder, which knows how to encode dates, times, UUIDs, etc., but beyond that you still need to implement your own logic.

Another approach, used by structlog, adds a __structlog__ method to classes, similar to __str__, but this requires modifying the classes themselves and is generally discouraged.

Enter PEP 443

Python 3.4 introduced a better solution via PEP 443: functools.singledispatch, with back‑ports available on PyPI for older versions.

With singledispatch, you define a generic function and then register type‑specific implementations. For example, you can register a handler for datetime objects that calls a to_serializable() method, and the dispatcher will automatically select the correct function.

This approach lets you place your serializer wherever you like—inside a class, in a dedicated module, or alongside other JSON‑related code—while keeping your classes clean and avoiding large if‑elif‑else blocks.

A Deeper Look

The @singledispatch decorator is more powerful than just JSON serialization; it provides a general mechanism for binding different behaviors to different types, a pattern that many developers overlook.

Footnotes:

UltraJSON does not support custom object serialization; python-rapidjson only supports a default() function.

Using the attrs library can simplify management of custom types.

Pyramid’s API, after being ported from zope.component, still lacks proper documentation.

The original motivation for adding singledispatch to the standard library was a more elegant implementation of pprint, though that never materialized.

Original article link: https://hynek.me/articles/serialization/