Skip to content

Commit 406d616

Browse files
authored
Docs: clarify serialization resolution order (#59750)
1 parent c3824f2 commit 406d616

File tree

1 file changed

+17
-6
lines changed

1 file changed

+17
-6
lines changed

airflow-core/docs/authoring-and-scheduling/serializers.rst

Lines changed: 17 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -26,12 +26,23 @@ and efficiency.
2626
Serialization is a surprisingly hard job. Python out of the box only has support for serialization of primitives,
2727
like ``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

3647
If you are looking to extend Airflow with a new serializer, it is good to know when to choose what way of serialization.
3748
Objects that are under the control of Airflow, i.e. residing under the namespace of ``airflow.*`` like

0 commit comments

Comments
 (0)