@@ -26,12 +26,23 @@ and efficiency.
2626Serialization is a surprisingly hard job. Python out of the box only has support for serialization of primitives,
2727like ``str `` and ``int `` and it loops over iterables. When things become more complex, custom serialization is required.
2828
29- Airflow out of the box supports three ways of custom serialization. Primitives are returned as is, without
30- additional encoding, e.g. a ``str `` remains a ``str ``. When it is not a primitive (or iterable thereof) Airflow
31- looks for a registered serializer and deserializer in the namespace of ``airflow.sdk.serde.serializers ``.
32- If not found it will look in the class for a ``serialize() `` method or in case of deserialization a
33- ``deserialize(data, version: int) `` method. Finally, if the class is either decorated with ``@dataclass ``
34- or ``@attr.define `` it will use the public methods for those decorators.
29+ Serialization resolution order
30+ ------------------------------
31+
32+ Airflow resolves custom serialization in the following order:
33+
34+ 1. Primitive values (such as ``str `` or ``int ``) and iterables of primitives
35+ are returned as-is, without additional encoding.
36+
37+ 2. If the object is not a primitive, Airflow looks for a registered serializer
38+ and deserializer in the ``airflow.sdk.serde.serializers `` namespace.
39+
40+ 3. If no registered serializer is found, Airflow checks whether the object
41+ defines a ``serialize() `` method (and, for deserialization, a corresponding
42+ ``deserialize(data, version: int) `` method).
43+
44+ 4. Finally, if the object is decorated with ``@dataclass `` or ``@attr.define ``,
45+ Airflow serializes the object using the public fields provided by those decorators.
3546
3647If you are looking to extend Airflow with a new serializer, it is good to know when to choose what way of serialization.
3748Objects that are under the control of Airflow, i.e. residing under the namespace of ``airflow.* `` like
0 commit comments