功能性序列化器

此模块包含用于序列化的相关类和函数。

FieldPlainSerializer module-attribute

FieldPlainSerializer: TypeAlias = (
    "core_schema.SerializerFunction | _Partial"
)

plain 模式下的字段序列化器方法或函数。

FieldWrapSerializer module-attribute

FieldWrapSerializer: TypeAlias = (
    "core_schema.WrapSerializerFunction | _Partial"
)

wrap 模式下的字段序列化器方法或函数。

FieldSerializer module-attribute

FieldSerializer: TypeAlias = (
    "FieldPlainSerializer | FieldWrapSerializer"
)

字段序列化器方法或函数。

ModelPlainSerializerWithInfo module-attribute

ModelPlainSerializerWithInfo: TypeAlias = Callable[
    [Any, SerializationInfo], Any
]

在 plain 模式下，带有 info 参数的模型序列化器方法。

ModelPlainSerializerWithoutInfo module-attribute

ModelPlainSerializerWithoutInfo: TypeAlias = Callable[
    [Any], Any
]

在 plain 模式下，不带 info 参数的模型序列化器方法。

ModelPlainSerializer module-attribute

ModelPlainSerializer: TypeAlias = (
    "ModelPlainSerializerWithInfo | ModelPlainSerializerWithoutInfo"
)

plain 模式下的模型序列化器方法。

ModelWrapSerializerWithInfo module-attribute

ModelWrapSerializerWithInfo: TypeAlias = Callable[
    [Any, SerializerFunctionWrapHandler, SerializationInfo],
    Any,
]

在 wrap 模式下，带有 info 参数的模型序列化器方法。

ModelWrapSerializerWithoutInfo module-attribute

ModelWrapSerializerWithoutInfo: TypeAlias = Callable[
    [Any, SerializerFunctionWrapHandler], Any
]

在 wrap 模式下，不带 info 参数的模型序列化器方法。

ModelWrapSerializer module-attribute

ModelWrapSerializer: TypeAlias = (
    "ModelWrapSerializerWithInfo | ModelWrapSerializerWithoutInfo"
)

wrap 模式下的模型序列化器方法。

PlainSerializer dataclass

PlainSerializer(
    func: SerializerFunction,
    return_type: Any = PydanticUndefined,
    when_used: WhenUsed = "always",
)

Plain 序列化器使用函数来修改序列化的输出。

当您想要自定义注解类型的序列化时，这尤其有用。 考虑 list 的输入，它将被序列化为以空格分隔的字符串。

from typing import Annotated

from pydantic import BaseModel, PlainSerializer

CustomStr = Annotated[
    list, PlainSerializer(lambda x: ' '.join(x), return_type=str)
]

class StudentModel(BaseModel):
    courses: CustomStr

student = StudentModel(courses=['Math', 'Chemistry', 'English'])
print(student.model_dump())
#> {'courses': 'Math Chemistry English'}

属性

名称	类型	描述
func	SerializerFunction	序列化器函数。
return_type	Any	函数的返回类型。 如果省略，将从类型注解中推断出来。
when_used	WhenUsed	确定何时应使用此序列化器。 接受值为 'always'、'unless-none'、'json' 和 'json-unless-none' 的字符串。 默认为 'always'。

WrapSerializer dataclass

WrapSerializer(
    func: WrapSerializerFunction,
    return_type: Any = PydanticUndefined,
    when_used: WhenUsed = "always",
)

Wrap 序列化器接收原始输入以及处理函数，该处理函数应用标准序列化逻辑，并可以在将其作为序列化的最终输出返回之前修改结果值。

例如，这是一个 Wrap 序列化器将时区转换为 UTC **并** 利用现有 datetime 序列化逻辑的场景。

from datetime import datetime, timezone
from typing import Annotated, Any

from pydantic import BaseModel, WrapSerializer

class EventDatetime(BaseModel):
    start: datetime
    end: datetime

def convert_to_utc(value: Any, handler, info) -> dict[str, datetime]:
    # Note that `handler` can actually help serialize the `value` for
    # further custom serialization in case it's a subclass.
    partial_result = handler(value, info)
    if info.mode == 'json':
        return {
            k: datetime.fromisoformat(v).astimezone(timezone.utc)
            for k, v in partial_result.items()
        }
    return {k: v.astimezone(timezone.utc) for k, v in partial_result.items()}

UTCEventDatetime = Annotated[EventDatetime, WrapSerializer(convert_to_utc)]

class EventModel(BaseModel):
    event_datetime: UTCEventDatetime

dt = EventDatetime(
    start='2024-01-01T07:00:00-08:00', end='2024-01-03T20:00:00+06:00'
)
event = EventModel(event_datetime=dt)
print(event.model_dump())
'''
{
    'event_datetime': {
        'start': datetime.datetime(
            2024, 1, 1, 15, 0, tzinfo=datetime.timezone.utc
        ),
        'end': datetime.datetime(
            2024, 1, 3, 14, 0, tzinfo=datetime.timezone.utc
        ),
    }
}
'''

print(event.model_dump_json())
'''
{"event_datetime":{"start":"2024-01-01T15:00:00Z","end":"2024-01-03T14:00:00Z"}}
'''

属性

名称	类型	描述
func	WrapSerializerFunction	要包装的序列化器函数。
return_type	Any	函数的返回类型。 如果省略，将从类型注解中推断出来。
when_used	WhenUsed	确定何时应使用此序列化器。 接受值为 'always'、'unless-none'、'json' 和 'json-unless-none' 的字符串。 默认为 'always'。

field_serializer

field_serializer(
    field: str,
    /,
    *fields: str,
    mode: Literal["wrap"],
    return_type: Any = ...,
    when_used: WhenUsed = ...,
    check_fields: bool | None = ...,
) -> Callable[
    [_FieldWrapSerializerT], _FieldWrapSerializerT
]

field_serializer(
    field: str,
    /,
    *fields: str,
    mode: Literal["plain"] = ...,
    return_type: Any = ...,
    when_used: WhenUsed = ...,
    check_fields: bool | None = ...,
) -> Callable[
    [_FieldPlainSerializerT], _FieldPlainSerializerT
]

field_serializer(
    *fields: str,
    mode: Literal["plain", "wrap"] = "plain",
    return_type: Any = PydanticUndefined,
    when_used: WhenUsed = "always",
    check_fields: bool | None = None
) -> (
    Callable[[_FieldWrapSerializerT], _FieldWrapSerializerT]
    | Callable[
        [_FieldPlainSerializerT], _FieldPlainSerializerT
    ]
)

启用自定义字段序列化的装饰器。

在下面的示例中，使用 set 类型的字段来减轻重复。 field_serializer 用于将数据序列化为排序列表。

from typing import Set

from pydantic import BaseModel, field_serializer

class StudentModel(BaseModel):
    name: str = 'Jane'
    courses: Set[str]

    @field_serializer('courses', when_used='json')
    def serialize_courses_in_order(self, courses: Set[str]):
        return sorted(courses)

student = StudentModel(courses={'Math', 'Chemistry', 'English'})
print(student.model_dump_json())
#> {"name":"Jane","courses":["Chemistry","English","Math"]}

有关更多信息，请参阅 自定义序列化器。

支持四种签名

• (self, value: Any, info: FieldSerializationInfo)
• (self, value: Any, nxt: SerializerFunctionWrapHandler, info: FieldSerializationInfo)
• (value: Any, info: SerializationInfo)
• (value: Any, nxt: SerializerFunctionWrapHandler, info: SerializationInfo)

参数

名称	类型	描述	默认值
fields	str	应在其上调用方法的字段。	()
mode	Literal['plain', 'wrap']	序列化模式。 plain 表示将调用该函数来代替默认的序列化逻辑， wrap 表示将在调用该函数时传递一个参数，以选择性地调用默认的序列化逻辑。	'plain'
return_type	Any	函数的可选返回类型，如果省略，将从类型注解中推断出来。	PydanticUndefined
when_used	WhenUsed	确定将用于序列化的序列化器。	'always'
check_fields	bool | None	是否检查字段是否实际存在于模型上。	None

返回

类型	描述
Callable[[_FieldWrapSerializerT], _FieldWrapSerializerT] | Callable[[_FieldPlainSerializerT], _FieldPlainSerializerT]	装饰器函数。

源代码位于 pydantic/functional_serializers.py 中

def field_serializer(
    *fields: str,
    mode: Literal['plain', 'wrap'] = 'plain',
    return_type: Any = PydanticUndefined,
    when_used: WhenUsed = 'always',
    check_fields: bool | None = None,
) -> (
    Callable[[_FieldWrapSerializerT], _FieldWrapSerializerT]
    | Callable[[_FieldPlainSerializerT], _FieldPlainSerializerT]
):
    """Decorator that enables custom field serialization.

    In the below example, a field of type `set` is used to mitigate duplication. A `field_serializer` is used to serialize the data as a sorted list.

    ```python
    from typing import Set

    from pydantic import BaseModel, field_serializer

    class StudentModel(BaseModel):
        name: str = 'Jane'
        courses: Set[str]

        @field_serializer('courses', when_used='json')
        def serialize_courses_in_order(self, courses: Set[str]):
            return sorted(courses)

    student = StudentModel(courses={'Math', 'Chemistry', 'English'})
    print(student.model_dump_json())
    #> {"name":"Jane","courses":["Chemistry","English","Math"]}
    ```

    See [Custom serializers](../concepts/serialization.md#custom-serializers) for more information.

    Four signatures are supported:

    - `(self, value: Any, info: FieldSerializationInfo)`
    - `(self, value: Any, nxt: SerializerFunctionWrapHandler, info: FieldSerializationInfo)`
    - `(value: Any, info: SerializationInfo)`
    - `(value: Any, nxt: SerializerFunctionWrapHandler, info: SerializationInfo)`

    Args:
        fields: Which field(s) the method should be called on.
        mode: The serialization mode.

            - `plain` means the function will be called instead of the default serialization logic,
            - `wrap` means the function will be called with an argument to optionally call the
               default serialization logic.
        return_type: Optional return type for the function, if omitted it will be inferred from the type annotation.
        when_used: Determines the serializer will be used for serialization.
        check_fields: Whether to check that the fields actually exist on the model.

    Returns:
        The decorator function.
    """

    def dec(f: FieldSerializer) -> _decorators.PydanticDescriptorProxy[Any]:
        dec_info = _decorators.FieldSerializerDecoratorInfo(
            fields=fields,
            mode=mode,
            return_type=return_type,
            when_used=when_used,
            check_fields=check_fields,
        )
        return _decorators.PydanticDescriptorProxy(f, dec_info)  # pyright: ignore[reportArgumentType]

    return dec  # pyright: ignore[reportReturnType]

model_serializer

model_serializer(
    f: _ModelPlainSerializerT,
) -> _ModelPlainSerializerT

model_serializer(
    *,
    mode: Literal["wrap"],
    when_used: WhenUsed = "always",
    return_type: Any = ...
) -> Callable[
    [_ModelWrapSerializerT], _ModelWrapSerializerT
]

model_serializer(
    *,
    mode: Literal["plain"] = ...,
    when_used: WhenUsed = "always",
    return_type: Any = ...
) -> Callable[
    [_ModelPlainSerializerT], _ModelPlainSerializerT
]

model_serializer(
    f: (
        _ModelPlainSerializerT
        | _ModelWrapSerializerT
        | None
    ) = None,
    /,
    *,
    mode: Literal["plain", "wrap"] = "plain",
    when_used: WhenUsed = "always",
    return_type: Any = PydanticUndefined,
) -> (
    _ModelPlainSerializerT
    | Callable[
        [_ModelWrapSerializerT], _ModelWrapSerializerT
    ]
    | Callable[
        [_ModelPlainSerializerT], _ModelPlainSerializerT
    ]
)

启用自定义模型序列化的装饰器。

当模型需要以自定义方式序列化时，这非常有用，从而可以实现超出特定字段的灵活性。

一个示例是将温度序列化为相同的温度标度，例如摄氏度。

from typing import Literal

from pydantic import BaseModel, model_serializer

class TemperatureModel(BaseModel):
    unit: Literal['C', 'F']
    value: int

    @model_serializer()
    def serialize_model(self):
        if self.unit == 'F':
            return {'unit': 'C', 'value': int((self.value - 32) / 1.8)}
        return {'unit': self.unit, 'value': self.value}

temperature = TemperatureModel(unit='F', value=212)
print(temperature.model_dump())
#> {'unit': 'C', 'value': 100}

mode='plain' 支持两种签名，这是默认设置

• (self)
• (self, info: SerializationInfo)

mode='wrap' 支持另外两种签名

• (self, nxt: SerializerFunctionWrapHandler)

• (self, nxt: SerializerFunctionWrapHandler, info: SerializationInfo)

  有关更多信息，请参阅 自定义序列化器。

参数

名称	类型	描述	默认值
f	_ModelPlainSerializerT | _ModelWrapSerializerT | None	要装饰的函数。	None
mode	Literal['plain', 'wrap']	序列化模式。 'plain' 表示将调用该函数来代替默认的序列化逻辑 'wrap' 表示将在调用该函数时传递一个参数，以选择性地调用默认的序列化逻辑。	'plain'
when_used	WhenUsed	确定何时应使用此序列化器。	'always'
return_type	Any	函数的返回类型。 如果省略，将从类型注解中推断出来。	PydanticUndefined

返回

类型	描述
_ModelPlainSerializerT | Callable[[_ModelWrapSerializerT], _ModelWrapSerializerT] | Callable[[_ModelPlainSerializerT], _ModelPlainSerializerT]	装饰器函数。

源代码位于 pydantic/functional_serializers.py 中

def model_serializer(
    f: _ModelPlainSerializerT | _ModelWrapSerializerT | None = None,
    /,
    *,
    mode: Literal['plain', 'wrap'] = 'plain',
    when_used: WhenUsed = 'always',
    return_type: Any = PydanticUndefined,
) -> (
    _ModelPlainSerializerT
    | Callable[[_ModelWrapSerializerT], _ModelWrapSerializerT]
    | Callable[[_ModelPlainSerializerT], _ModelPlainSerializerT]
):
    """Decorator that enables custom model serialization.

    This is useful when a model need to be serialized in a customized manner, allowing for flexibility beyond just specific fields.

    An example would be to serialize temperature to the same temperature scale, such as degrees Celsius.

    ```python
    from typing import Literal

    from pydantic import BaseModel, model_serializer

    class TemperatureModel(BaseModel):
        unit: Literal['C', 'F']
        value: int

        @model_serializer()
        def serialize_model(self):
            if self.unit == 'F':
                return {'unit': 'C', 'value': int((self.value - 32) / 1.8)}
            return {'unit': self.unit, 'value': self.value}

    temperature = TemperatureModel(unit='F', value=212)
    print(temperature.model_dump())
    #> {'unit': 'C', 'value': 100}
    ```

    Two signatures are supported for `mode='plain'`, which is the default:

    - `(self)`
    - `(self, info: SerializationInfo)`

    And two other signatures for `mode='wrap'`:

    - `(self, nxt: SerializerFunctionWrapHandler)`
    - `(self, nxt: SerializerFunctionWrapHandler, info: SerializationInfo)`

        See [Custom serializers](../concepts/serialization.md#custom-serializers) for more information.

    Args:
        f: The function to be decorated.
        mode: The serialization mode.

            - `'plain'` means the function will be called instead of the default serialization logic
            - `'wrap'` means the function will be called with an argument to optionally call the default
                serialization logic.
        when_used: Determines when this serializer should be used.
        return_type: The return type for the function. If omitted it will be inferred from the type annotation.

    Returns:
        The decorator function.
    """

    def dec(f: ModelSerializer) -> _decorators.PydanticDescriptorProxy[Any]:
        dec_info = _decorators.ModelSerializerDecoratorInfo(mode=mode, return_type=return_type, when_used=when_used)
        return _decorators.PydanticDescriptorProxy(f, dec_info)

    if f is None:
        return dec  # pyright: ignore[reportReturnType]
    else:
        return dec(f)  # pyright: ignore[reportReturnType]