Fallback Serialization Function

Purpose

When serializing Python objects to JSON, some data types may not have a direct JSON representation or built-in serialization support. The **Fallback Serialization Function** addresses this challenge by allowing users to define a custom handler that converts unsupported Python objects into JSON-serializable forms. This mechanism ensures that complex or user-defined types do not cause serialization failures, enabling graceful handling or transformation of these objects during the serialization process.

Functionality

This feature works by accepting a user-provided fallback function (commonly named `default`) that is invoked whenever the serializer encounters an object it cannot serialize natively. The fallback function receives the unsupported object and is expected to return a JSON-serializable representation or raise an exception if it cannot handle the type.

Key behaviors include:

• Invocation on Unsupported Types: During serialization, if an object’s type is unknown or lacks a native serializer, the fallback function is called.

• Return Value Handling: The function returns a JSON-serializable object (e.g., a string, number, dictionary) that replaces the original unsupported object in the output JSON.

• Error Propagation: If the fallback function returns an unsupported type or raises an error, serialization fails with a descriptive exception.

• Integration with Serialization Options: The fallback function works alongside serialization options like OPT_SERIALIZE_NUMPY to handle complex types such as numpy arrays.

A typical usage pattern from the benchmark script demonstrates this:

from orjson import dumps, OPT_SERIALIZE_NUMPY

class Custom:
    pass

def default(_):
    return None  # Provide a fallback JSON-compatible value

obj = [[Custom()] * 1000] * 10
result = dumps(obj, default, OPT_SERIALIZE_NUMPY)

In this example, instances of `Custom` are not natively serializable, so the `default` function returns `None` as their JSON representation.

Integration

The fallback serialization function is an extension point within the broader **Custom Serialization Support** topic. It complements other subtopics such as **Numpy Serialization** by providing a generic mechanism to handle any unsupported Python object types, not just numpy arrays.

Within the serialization workflow:

• The core serializer attempts to serialize each object.

• Upon encountering an unsupported object, it delegates to the fallback function.

• The fallback function’s output is recursively serialized if necessary.

• This mechanism ensures seamless integration with other serialization features and options, allowing developers to customize serialization behavior flexibly.

This fallback approach enhances robustness and user control, enabling serialization of complex, nested, or application-specific data structures without modifying the core library.

Process Flow Diagram

flowchart TD
    A[Start Serialization] --> B{Is Object Supported?}
    B -- Yes --> C[Serialize Object]
    B -- No --> D[Call Fallback Function]
    D --> E{Fallback Returns Serializable?}
    E -- Yes --> F[Serialize Fallback Result]
    E -- No --> G[Raise Serialization Error]
    C --> H[Continue Serialization]
    F --> H
    G --> I[Serialization Fails]
    H --> J[End Serialization]

This flowchart illustrates the decision process during serialization when an unsupported object type is encountered and how the fallback function is invoked to provide a serializable representation.