serialization

26 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

model_dump() converts models to dictionaries in Python mode

The model_dump() method serializes Pydantic models and model-like types (such as dataclasses) by recursively converting them to dictionaries. This is the Python mode for serialization. When called without arguments, it returns a dictionary representation of the model.

model_dump(mode='json') ensures JSON-compatible types

When model_dump() is called with mode='json', non-JSON types like tuples are converted to JSON-compatible equivalents (e.g., tuple becomes list). This mode does not produce a JSON string but a dictionary with JSON-safe values.

model iteration yields (field_name, field_value) pairs without converting sub-models

Pydantic models can be iterated over, yielding tuples of (field_name, field_value). Field values are left as-is during iteration, so sub-models are not converted to dictionaries. This means calling dict() on a model will preserve sub-model instances as model objects, not dictionaries.

Plain serializers are called unconditionally and bypass Pydantic's type logic

Plain field serializers are called unconditionally to serialize a field. The default serialization logic for types supported by Pydantic will not be called. They can be defined using the annotated pattern with PlainSerializer() or the @field_serializer decorator with mode='plain'.

Wrap serializers provide flexibility to run code before or after Pydantic serialization

Wrap field serializers accept a mandatory handler parameter (a callable) that delegates to Pydantic's serialization logic. This allows running custom code before or after Pydantic's default serialization. The handler is free to call or not call the default serialization. They can be defined using the annotated pattern with WrapSerializer() or the @field_serializer decorator with mode='wrap'.

Only one serializer can be defined per field/model

It is not possible to combine multiple serializers together on a single field or model, including mixing plain and wrap serializers. Only one serializer definition is allowed per field or per model.

Plain model serializers are called unconditionally

Plain model serializers defined with @model_serializer(mode='plain') are called unconditionally to serialize the entire model. They can return any value, not just a dictionary. The 'plain' mode is the default and can be omitted.

Wrap model serializers have a mandatory handler parameter

Wrap model serializers defined with @model_serializer(mode='wrap') accept a mandatory handler parameter that is a callable taking the model instance as an argument. The handler delegates serialization to Pydantic. You are free to call the handler or not.

Serializers can access serialization info including context and mode

Both field and model serializers can optionally accept an info parameter providing useful metadata such as user-defined context, the current serialization mode ('python' or 'json'), serialization method parameters (exclude_unset, serialize_as_any, etc.), and for field serializers, the current field name.

Serialization context can be passed to model_dump() and accessed in serializers

When calling serialization methods like model_dump(), a context object can be passed using the context parameter. This context is accessible inside serializer functions via info.context property, allowing serializers to customize behavior based on provided context.

Subclasses of supported types are serialized according to their superclass

When a field is annotated with a superclass type (e.g., date), and a subclass instance is provided (e.g., MyDate subclass), Pydantic serializes it according to the superclass schema, not the subclass schema.

Subclass fields are not included by default in model serialization (V2 behavior)

When using model-like classes (Pydantic models, dataclasses, etc.) as field annotations, the default behavior in Pydantic V2 is to serialize only the fields declared on the type annotation, not fields from subclass instances. This differs from V1 where subclass fields were always included. This behavior ensures predictability and security.

polymorphic_serialization configuration enables serializing actual subclass fields

Polymorphic serialization, added in V2.13, can be enabled via the polymorphic_serialization configuration setting on a model/dataclass or as a runtime argument to serialization methods. When enabled, a model instance will be serialized according to its actual runtime type schema rather than the declared annotation type, exposing all subclass fields.

polymorphic_serialization only supported for Pydantic models and Pydantic dataclasses

Polymorphic serialization is only supported for Pydantic models and Pydantic dataclasses. When using standard library dataclasses, polymorphic serialization is not supported, even if the dataclass is a subclass of a Pydantic dataclass.

SerializeAsAny annotation enables field-level duck typing serialization

The SerializeAsAny[<type>] annotation allows duck typing serialization behavior for a specific field. Validation behaves as if annotated with <type>, and static type checkers treat it as <type>, but during serialization the field is serialized as though annotated with Any, exposing all actual runtime type fields.

serialize_as_any runtime parameter serializes all values by actual runtime type

The serialize_as_any runtime parameter can be passed to serialization methods like model_dump() and model_dump_json(). When set to True, all values in the model are serialized according to their actual runtime type rather than their annotated type, bypassing type annotations for serialization purposes.

Field-level exclude parameter prevents field from being serialized

At the field level, the exclude parameter can be set on the Field() function to permanently exclude that field from serialization. For example, Field(exclude=True) on a field will exclude it from all model_dump() calls.

Field-level exclude_if parameter conditionally excludes fields

The exclude_if parameter on Field() accepts a callable that returns a boolean. If the callable returns True, the field is excluded from serialization. This allows conditional exclusion based on the field's value.

exclude parameter in model_dump() excludes specific fields from serialization

The exclude parameter in model_dump() can be used to specify which fields should be excluded from the serialized output. It can be a set of field names or a nested dictionary specifying nested exclusions. Nested fields can be excluded using dictionary notation like exclude={'user': {'username'}}.

include parameter in model_dump() includes only specific fields in serialization

The include parameter in model_dump() specifies which fields should be included in the serialized output. All other fields are excluded. It can be a set of field names or a nested dictionary specifying nested inclusions.

exclude_defaults parameter excludes fields with default values

The exclude_defaults parameter in model_dump() excludes all fields whose value compares equal to the field's default value using the equality (==) comparison operator.

exclude_none parameter excludes None-valued fields

The exclude_none parameter in model_dump() excludes all fields whose value is None from the serialized output.

exclude_unset parameter excludes fields not explicitly set during instantiation

The exclude_unset parameter in model_dump() excludes any field that was not explicitly provided during model instantiation. Pydantic tracks which fields were explicitly set via the model_fields_set property. Note that modifying a field after instantiation removes it from the unset fields.

Exclude/include patterns can target specific sequence and dictionary items

When excluding or including fields, nested patterns can target specific items in sequences and dictionaries. For example, exclude={'hobbies': {-1: {'info'}}} excludes the 'info' field from the last item in the hobbies list. The special key '__all__' applies a pattern to all members.

Field-level exclude takes priority over include parameter in serialization

When serializing, if a field has exclude=True set at the field level via Field(), this takes priority and the field will be excluded even if the include parameter in model_dump() would otherwise include it.

Polymorphic serialization for subclass fields

For polymorphic serialization of fields defined with a base class type containing runtime subclass values, use polymorphic serialization (Pydantic >= 2.13) or serialize as any (Pydantic < 2.13) as a last resort.

Give your agent this brain