Functional Serializers

このモジュールには、シリアル化のための関連クラスと関数が含まれています。

PlainSerializer `dataclass` ¶

PlainSerializer(
    func: SerializerFunction,
    return_type: Any = PydanticUndefined,
    when_used: Literal[
        "always", "unless-none", "json", "json-unless-none"
    ] = "always",
)

普通のシリアライザは、シリアライゼーションの出力を変更するために関数を使用します。

これは特に、アノテーション付き型のシリアライゼーションをカスタマイズしたい場合に役立ちます。スペースで区切られた文字列にシリアライズされるlistの入力を考えてみましょう。

from typing import List

from typing_extensions 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'}

Attributes:

Name	Type	Description
`func`	`SerializerFunction`	シリアライザ関数。
`return_type`	`Any`	関数の戻り型。省略した場合は、型注釈から推測されます。
`when_used`	`Literal['always', 'unless-none', 'json', 'json-unless-none']`	このシリアライザをいつ使用すべきかを決定します。"always"、"unless-none"、"json"、"json-unless-none"の値を持つ文字列を受け入れます。デフォルトは"always"です。

WrapSerializer `dataclass` ¶

WrapSerializer(
    func: WrapSerializerFunction,
    return_type: Any = PydanticUndefined,
    when_used: Literal[
        "always", "unless-none", "json", "json-unless-none"
    ] = "always",
)

ラップシリアライザは、標準のシリアライゼーションロジックを適用するハンドラ関数とともに生の入力を受け取り、シリアライゼーションの最終出力として返す前に、結果の値を変更できます。

例えば、ラップシリアライザがタイムゾーンをUTCに変換し、が既存のdatetimeシリアライゼーションロジックを利用するシナリオを考えてみましょう。

from datetime import datetime, timezone
from typing import Any, Dict

from typing_extensions import Annotated

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 `helper` 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"}}
'''

Attributes:

Name	Type	Description
`func`	`WrapSerializerFunction`	ラップされるシリアライザ関数。
`return_type`	`Any`	関数の戻り型。省略した場合は、型注釈から推測されます。
`when_used`	`Literal['always', 'unless-none', 'json', 'json-unless-none']`	このシリアライザをいつ使用すべきかを決定します。"always"、"unless-none"、"json"、"json-unless-none"の値を持つ文字列を受け入れます。デフォルトは"always"です。

field_serializer ¶

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

カスタムフィールドのシリアル化を可能にするデコレータ。

以下の例では、重複を避けるために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"]}

詳細については、Custom serializerを参照してください。

4つのシグネチャがサポートされています。

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

Parameters:

Name	Type	Description	Default
`fields`	`str`	メソッドが呼び出されるフィールド。	`()`
`mode`	`Literal['plain', 'wrap']`	シリアライゼーションモード。 - `plain`は、デフォルトのシリアライゼーションロジックの代わりに関数が呼び出されることを意味します。 - `wrap`は、オプションでデフォルトのシリアライゼーションロジックを呼び出すための引数とともに関数が呼び出されることを意味します。	`'plain'`
`return_type`	`Any`	関数のオプションの戻り型です。省略した場合は、型アノテーションから推測されます。	`PydanticUndefined`
`when_used`	`Literal['always', 'unless-none', 'json', 'json-unless-none']`	シリアライズに使用するシリアライザを指定します。	`'always'`
`check_fields`	`bool \| None`	フィールドがモデル上に実際に存在するかどうかをチェックするかどうか。	`None`

Returns:

Type	Description
`Callable[[Any], Any]`	デコレータ関数。

Source code in pydantic/functional_serializers.py

def field_serializer(
    *fields: str,
    mode: Literal['plain', 'wrap'] = 'plain',
    return_type: Any = PydanticUndefined,
    when_used: Literal['always', 'unless-none', 'json', 'json-unless-none'] = 'always',
    check_fields: bool | None = None,
) -> Callable[[Any], Any]:
    """カスタムフィールドのシリアル化を可能にするデコレータ。

    以下の例では、重複を避けるために`set`型のフィールドが使用されています。`field_serializer`はソートされたリストとしてデータをシリアライズするために使用されています。

    ```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"]}
    ```

    詳細については、[Custom serializer](https://yodai-yodai.github.io/translated/pydantic-docs-ja/concepts/serialization.md#custom-serializer)を参照してください。

    4つのシグネチャがサポートされています。

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

    Args:
        fields: メソッドが呼び出されるフィールド。
        mode: シリアライゼーションモード。
            - `plain`は、デフォルトのシリアライゼーションロジックの代わりに関数が呼び出されることを意味します。
            - `wrap`は、オプションでデフォルトのシリアライゼーションロジックを呼び出すための引数とともに関数が呼び出されることを意味します。
        return_type: 関数のオプションの戻り型です。省略した場合は、型アノテーションから推測されます。
        when_used: シリアライズに使用するシリアライザを指定します。
        check_fields: フィールドがモデル上に実際に存在するかどうかをチェックするかどうか。

    Returns:
        デコレータ関数。
    """

    def dec(
        f: Callable[..., Any] | staticmethod[Any, Any] | classmethod[Any, Any, Any],
    ) -> _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)

    return dec

model_serializer ¶

model_serializer(
    f: Callable[..., Any] | None = None,
    /,
    *,
    mode: Literal["plain", "wrap"] = "plain",
    when_used: Literal[
        "always", "unless-none", "json", "json-unless-none"
    ] = "always",
    return_type: Any = PydanticUndefined,
) -> Callable[[Any], Any]

カスタムモデルのシリアライゼーションを可能にするデコレータ。

これは、モデルをカスタマイズされた方法でシリアライズする必要がある場合に便利で、特定のフィールド以外にも柔軟性を持たせることができます。

たとえば、温度を摂氏などの同じ温度スケールに直列化することができます。

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}