PEP 837 proposes extensible JSON serialization for Python

PEP 837 proposes a three-part extension mechanism for Python's `json` encoder: a `__json__()` and `__raw_json__()` protocol for library-level customization, a global registry via `copyreg.json()` for application-level control, and a per-encoder dispatch table. This system allows for hierarchical customization, with more specific levels taking precedence.

Several standard library container types, including `collections.deque`, `types.MappingProxyType`, `collections.ChainMap`, `collections.UserDict`, `collections.UserList`, and `collections.UserString`, will gain a `__json__` method, enabling them to serialize out-of-the-box.

A helper class `copyreg.RawJSON` is introduced to wrap already-encoded JSON strings. This allows these strings to be emitted verbatim, facilitating representations not otherwise expressible, such as serializing `decimal.Decimal` with full precision as a JSON number.

The proposed mechanism aims to overcome limitations of the current `default=` function and `JSONEncoder` subclassing. It addresses issues with non-composable defaults, lack of opt-in for third-party types, and the impossibility of certain representations like pre-encoded JSON fragments or precise decimal numbers.

The PEP acknowledges ambiguity in representing types like `Decimal`, `namedtuple`, `array.array`, and `datetime` in JSON. The proposed system allows applications to declare their specific serialization policies, providing a standardized way to handle these cases.

This PEP formalizes the `__json__` protocol, which has seen piecemeal adoption in various libraries and frameworks. By defining it in the standard library, it provides a consistent and reliable mechanism for third-party libraries to rely on for JSON serialization.