TypeAdapter

Bases: Generic[T]

Usage Documentation

Type Adapter

タイプアダプタは、Pythonタイプに基づいて検証とシリアライゼーションを実行する柔軟な方法を提供します。

TypeAdapterインスタンスは、そのようなメソッドを持たない型(データクラス、プリミティブ型など)に対して、BaseModelインスタンスメソッドの機能の一部を公開します。

Note: TypeAdapterインスタンスは型ではなく、フィールドの型注釈として使用することはできません。

Note: デフォルトでは、TypeAdapterはmodel_configまたはTypeAdapterコンストラクタconfigのdefer_build=True設定を考慮しません。また、モデルバリデータとシリアライザの構築を延期するには、設定のexperimental_defer_build_mode=('model','type_adapter')を明示的に設定する必要があります。したがって、この機能は下位互換性を保証するためにオプトインされています。

Attributes:

Name	Type	Description
core_schema	CoreSchema	型のコア・スキーマ。
validator(SchemaValidator)	CoreSchema	型のスキーマ・バリデーター。
serializer	SchemaSerializer	型のスキーマ・シリアライザ。

Parameters:

Name	Type	Description	Default
type	Any	TypeAdapterに関連付けられた型。	required
config	ConfigDict | None	TypeAdapterの設定は、ConfigDictに準拠した辞書でなければなりません。	None
_parent_depth	int	ローカルネームスペースを構築するために親ネームスペースを検索するデプス。	2
module	str | None	プラグインに渡されるモジュール(指定されている場合)。	None

Note

使用している型が上書きできない独自の設定を持っている場合(例:BaseModel、TypedDict、dataclass)、TypeAdapterをインスタンス化するときにconfig引数を使用することはできません。この場合、type-adapter-config-unusedエラーが発生します。

Note

_parent_depth引数の名前にはアンダースコアが付いています。これは、引数がプライベートであることを示し、使用しないようにするためです。 マイナーバージョンでは非推奨になる可能性があるため、動作/サポートの潜在的な変更に満足している場合にのみ使用することをお勧めします。

Compatibility with mypy

使用されているタイプによっては、mypyがTypeAdapterをインスタンス化するときにエラーが発生することがあります。回避策として、変数に明示的に注釈を付けることができます。

from typing import Union

from pydantic import TypeAdapter

ta: TypeAdapter[Union[str, int]] = TypeAdapter(Union[str, int])  # type: ignore[arg-type]

Returns:

Type	Description
None	指定されたtype用に設定されたタイプアダプタ。

Source code in pydantic/type_adapter.py

def __init__(
    self,
    type: Any,
    *,
    config: ConfigDict | None = None,
    _parent_depth: int = 2,
    module: str | None = None,
) -> None:
    """TypeAdapterオブジェクトを初期化します。

    Args:
        type: `TypeAdapter`に関連付けられた型。
        config: `TypeAdapter`の設定は、[`ConfigDict`][pydantic.config.ConfigDict]に準拠した辞書でなければなりません。
        _parent_depth: ローカルネームスペースを構築するために親ネームスペースを検索するデプス。
        module: プラグインに渡されるモジュール(指定されている場合)。

    !!! note
        使用している型が上書きできない独自の設定を持っている場合(例:`BaseModel`、`TypedDict`、`dataclass`)、`TypeAdapter`をインスタンス化するときに`config`引数を使用することはできません。この場合、[`type-adapter-config-unused`](../errors/usage_errors.md#type-adapter-config-unused)エラーが発生します。

    !!! note
        `_parent_depth`引数の名前にはアンダースコアが付いています。これは、引数がプライベートであることを示し、使用しないようにするためです。
        マイナーバージョンでは非推奨になる可能性があるため、動作/サポートの潜在的な変更に満足している場合にのみ使用することをお勧めします。

    ??? tip "Compatibility with `mypy`"
        使用されているタイプによっては、`mypy`が`TypeAdapter`をインスタンス化するときにエラーが発生することがあります。回避策として、変数に明示的に注釈を付けることができます。

        ```py
        from typing import Union

        from pydantic import TypeAdapter

        ta: TypeAdapter[Union[str, int]] = TypeAdapter(Union[str, int])  # type: ignore[arg-type]
        ```

    Returns:
        指定された`type`用に設定されたタイプアダプタ。
    """
    if _type_has_config(type) and config is not None:
        raise PydanticUserError(
            'Cannot use `config` when the type is a BaseModel, dataclass or TypedDict.'
            ' These types can have their own config and setting the config via the `config`'
            ' parameter to TypeAdapter will not override it, thus the `config` you passed to'
            ' TypeAdapter becomes meaningless, which is probably not what you want.',
            code='type-adapter-config-unused',
        )

    self._type = type
    self._config = config
    self._parent_depth = _parent_depth
    if module is None:
        f = sys._getframe(1)
        self._module_name = cast(str, f.f_globals.get('__name__', ''))
    else:
        self._module_name = module

    self._core_schema: CoreSchema | None = None
    self._validator: SchemaValidator | PluggableSchemaValidator | None = None
    self._serializer: SchemaSerializer | None = None

    if not self._defer_build():
        # Immediately initialize the core schema, validator and serializer
        with self._with_frame_depth(1):  # +1 frame depth for this __init__
            # Model itself may be using deferred building. For backward compatibility we don't rebuild model mocks
            # here as part of __init__ even though TypeAdapter itself is not using deferred building.
            self._init_core_attrs(rebuild_mocks=False)

core_schema cached property

core_schema: CoreSchema

SchemaValidatorとSchemaSerializerを構築するために使用されるpydantic-coreスキーマ。

validator cached property

validator: SchemaValidator | PluggableSchemaValidator

モデルのインスタンスを検証するために使用されるpydantic-core SchemaValidator。

serializer cached property

serializer: SchemaSerializer

モデルのインスタンスをダンプするために使用されるpydantic-core SchemaSerializer。

validate_python

validate_python(
    object: Any,
    /,
    *,
    strict: bool | None = None,
    from_attributes: bool | None = None,
    context: dict[str, Any] | None = None,
) -> T

モデルに対してPythonオブジェクトを検証します。

Parameters:

Name	Type	Description	Default
object	Any	モデルに対して検証するPythonオブジェクト。	required
strict	bool | None	型を厳密にチェックするかどうか。	None
from_attributes	bool | None	オブジェクト属性からデータを抽出するかどうか。	None
context	dict[str, Any] | None	バリデータに渡す追加のコンテキスト。	None

Note

PydanticのdataclassでTypeAdapterを使用する場合、from_attributes引数の使用はサポートされません。

Returns:

Type	Description
T	検証されたオブジェクトです。

Source code in pydantic/type_adapter.py

@_frame_depth(1)
def validate_python(
    self,
    object: Any,
    /,
    *,
    strict: bool | None = None,
    from_attributes: bool | None = None,
    context: dict[str, Any] | None = None,
) -> T:
    """モデルに対してPythonオブジェクトを検証します。

    Args:
        object: モデルに対して検証するPythonオブジェクト。
        strict: 型を厳密にチェックするかどうか。
        from_attributes: オブジェクト属性からデータを抽出するかどうか。
        context: バリデータに渡す追加のコンテキスト。

    !!! note
        Pydanticの`dataclass`で`TypeAdapter`を使用する場合、`from_attributes`引数の使用はサポートされません。

    Returns:
        検証されたオブジェクトです。
    """
    return self.validator.validate_python(object, strict=strict, from_attributes=from_attributes, context=context)

validate_json

validate_json(
    data: str | bytes,
    /,
    *,
    strict: bool | None = None,
    context: dict[str, Any] | None = None,
) -> T

Usage Documentation

Json Parsing

JSON文字列またはバイトをモデルに対して検証します。

Parameters:

Name	Type	Description	Default
data	str | bytes	モデルに対して検証するJSONデータ。	required
strict	bool | None	型を厳密にチェックするかどうか。	None
context	dict[str, Any] | None	検証中に使用する追加のコンテキスト。	None

Returns:

Type	Description
T	検証されたオブジェクトです。

Source code in pydantic/type_adapter.py

@_frame_depth(1)
def validate_json(
    self, data: str | bytes, /, *, strict: bool | None = None, context: dict[str, Any] | None = None
) -> T:
    """Usage docs: https://yodai-yodai.github.io/translated/pydantic-docs-ja/concepts/json/#json-parsing

    JSON文字列またはバイトをモデルに対して検証します。

    Args:
        data: モデルに対して検証するJSONデータ。
        strict: 型を厳密にチェックするかどうか。
        context: 検証中に使用する追加のコンテキスト。

    Returns:
        検証されたオブジェクトです。
    """
    return self.validator.validate_json(data, strict=strict, context=context)

validate_strings

validate_strings(
    obj: Any,
    /,
    *,
    strict: bool | None = None,
    context: dict[str, Any] | None = None,
) -> T

検証オブジェクトには、モデルに対する文字列データが含まれています。

Parameters:

Name	Type	Description	Default
obj	Any	検証する文字列データがオブジェクトに含まれています。	required
strict	bool | None	型を厳密にチェックするかどうか。	None
context	dict[str, Any] | None	検証中に使用する追加のコンテキスト。	None

Returns:

Type	Description
T	検証されたオブジェクトです。

Source code in pydantic/type_adapter.py

@_frame_depth(1)
def validate_strings(self, obj: Any, /, *, strict: bool | None = None, context: dict[str, Any] | None = None) -> T:
    """検証オブジェクトには、モデルに対する文字列データが含まれています。

    Args:
        obj: 検証する文字列データがオブジェクトに含まれています。
        strict: 型を厳密にチェックするかどうか。
        context: 検証中に使用する追加のコンテキスト。

    Returns:
        検証されたオブジェクトです。
    """
    return self.validator.validate_strings(obj, strict=strict, context=context)

get_default_value

get_default_value(
    *,
    strict: bool | None = None,
    context: dict[str, Any] | None = None
) -> Some[T] | None

ラップされたタイプのデフォルト値を取得します。

Parameters:

Name	Type	Description	Default
strict	bool | None	型を厳密にチェックするかどうか。	None
context	dict[str, Any] | None	バリデータに渡す追加のコンテキスト。	None

Returns:

Type	Description
Some[T] | None	存在する場合はSomeでラップされたデフォルト値、存在しない場合はNoneでラップされたデフォルト値。

Source code in pydantic/type_adapter.py

@_frame_depth(1)
def get_default_value(self, *, strict: bool | None = None, context: dict[str, Any] | None = None) -> Some[T] | None:
    """ラップされたタイプのデフォルト値を取得します。

    Args:
        strict: 型を厳密にチェックするかどうか。
        context: バリデータに渡す追加のコンテキスト。

    Returns:
        存在する場合は`Some`でラップされたデフォルト値、存在しない場合はNoneでラップされたデフォルト値。
    """
    return self.validator.get_default_value(strict=strict, context=context)

dump_python

dump_python(
    instance: T,
    /,
    *,
    mode: Literal["json", "python"] = "python",
    include: IncEx | None = None,
    exclude: IncEx | None = None,
    by_alias: bool = False,
    exclude_unset: bool = False,
    exclude_defaults: bool = False,
    exclude_none: bool = False,
    round_trip: bool = False,
    warnings: (
        bool | Literal["none", "warn", "error"]
    ) = True,
    serialize_as_any: bool = False,
    context: dict[str, Any] | None = None,
) -> Any

適合した型のインスタンスをPythonオブジェクトにダンプします。

Parameters:

Name	Type	Description	Default
instance	T	シリアライズするPythonオブジェクト。	required
mode	Literal['json', 'python']	出力フォーマット。	'python'
include	IncEx | None	出力に含めるフィールド。	None
exclude	IncEx | None	出力から除外するフィールド。	None
by_alias	bool	フィールド名にエイリアス名を使用するかどうか。	False
exclude_unset	bool	設定されていないフィールドを除外するかどうか。	False
exclude_defaults	bool	デフォルト値を持つフィールドを除外するかどうか。	False
exclude_none	bool	None値を持つフィールドを除外するかどうか。	False
round_trip	bool	デシリアライズと互換性のある方法でシリアライズされたデータを出力するかどうか。	False
warnings	bool | Literal['none', 'warn', 'error']	シリアライゼーションエラーの処理方法。False/"none"はエラーを無視します。True/"warn"はエラーをログに記録します。"error"はPydanticSerializationErrorを発生させます。	True
serialize_as_any	bool	ダック型のシリアライズ動作でフィールドをシリアライズするかどうか。	False
context	dict[str, Any] | None	シリアライザに渡す追加のコンテキスト。	None

Returns:

Type	Description
Any	シリアライズされたオブジェクト。

Source code in pydantic/type_adapter.py

@_frame_depth(1)
def dump_python(
    self,
    instance: T,
    /,
    *,
    mode: Literal['json', 'python'] = 'python',
    include: IncEx | None = None,
    exclude: IncEx | None = None,
    by_alias: bool = False,
    exclude_unset: bool = False,
    exclude_defaults: bool = False,
    exclude_none: bool = False,
    round_trip: bool = False,
    warnings: bool | Literal['none', 'warn', 'error'] = True,
    serialize_as_any: bool = False,
    context: dict[str, Any] | None = None,
) -> Any:
    """適合した型のインスタンスをPythonオブジェクトにダンプします。

    Args:
        instance: シリアライズするPythonオブジェクト。
        mode: 出力フォーマット。
        include: 出力に含めるフィールド。
        exclude: 出力から除外するフィールド。
        by_alias: フィールド名にエイリアス名を使用するかどうか。
        exclude_unset: 設定されていないフィールドを除外するかどうか。
        exclude_defaults: デフォルト値を持つフィールドを除外するかどうか。
        exclude_none: None値を持つフィールドを除外するかどうか。
        round_trip: デシリアライズと互換性のある方法でシリアライズされたデータを出力するかどうか。
        warnings: シリアライゼーションエラーの処理方法。False/"none"はエラーを無視します。True/"warn"はエラーをログに記録します。"error"は[`PydanticSerializationError`][pydantic_core.PydanticSerializationError]を発生させます。
        serialize_as_any: ダック型のシリアライズ動作でフィールドをシリアライズするかどうか。
        context: シリアライザに渡す追加のコンテキスト。

    Returns:
        シリアライズされたオブジェクト。
    """
    return self.serializer.to_python(
        instance,
        mode=mode,
        by_alias=by_alias,
        include=include,
        exclude=exclude,
        exclude_unset=exclude_unset,
        exclude_defaults=exclude_defaults,
        exclude_none=exclude_none,
        round_trip=round_trip,
        warnings=warnings,
        serialize_as_any=serialize_as_any,
        context=context,
    )

dump_json

dump_json(
    instance: T,
    /,
    *,
    indent: int | None = None,
    include: IncEx | None = None,
    exclude: IncEx | None = None,
    by_alias: bool = False,
    exclude_unset: bool = False,
    exclude_defaults: bool = False,
    exclude_none: bool = False,
    round_trip: bool = False,
    warnings: (
        bool | Literal["none", "warn", "error"]
    ) = True,
    serialize_as_any: bool = False,
    context: dict[str, Any] | None = None,
) -> bytes

Usage Documentation

JSON Serialization

適応型のインスタンスをJSONにシリアライズします。

Parameters:

Name	Type	Description	Default
instance	T	シリアライズされるインスタンス。	required
indent	int | None	JSONインデントのスペースの数。	None
include	IncEx | None	含めるフィールド。	None
exclude	IncEx | None	除外するフィールド。	None
by_alias	bool	フィールド名にエイリアス名を使用するかどうか。	False
exclude_unset	bool	設定されていないフィールドを除外するかどうか。	False
exclude_defaults	bool	デフォルト値を持つフィールドを除外するかどうか。	False
exclude_none	bool	Noneの値を持つフィールドを除外するかどうか。	False
round_trip	bool	ラウンドトリップを確実にするために、インスタンスをシリアライズしてデシリアライズするかどうか。	False
warnings	bool | Literal['none', 'warn', 'error']	シリアライゼーションエラーの処理方法。False/"none"はエラーを無視します。True/"warn"はエラーをログに記録します。"error"はPydanticSerializationErrorを発生させます。	True
serialize_as_any	bool	ダック型のシリアライズ動作でフィールドをシリアライズするかどうか。	False
context	dict[str, Any] | None	シリアライザに渡す追加のコンテキスト。	None

Returns:

Type	Description
bytes	指定されたインスタンスのJSON表現(バイト単位)。

Source code in pydantic/type_adapter.py

@_frame_depth(1)
def dump_json(
    self,
    instance: T,
    /,
    *,
    indent: int | None = None,
    include: IncEx | None = None,
    exclude: IncEx | None = None,
    by_alias: bool = False,
    exclude_unset: bool = False,
    exclude_defaults: bool = False,
    exclude_none: bool = False,
    round_trip: bool = False,
    warnings: bool | Literal['none', 'warn', 'error'] = True,
    serialize_as_any: bool = False,
    context: dict[str, Any] | None = None,
) -> bytes:
    """Usage docs: https://yodai-yodai.github.io/translated/pydantic-docs-ja/concepts/json/#json-serialization

    適応型のインスタンスをJSONにシリアライズします。

    Args:
        instance: シリアライズされるインスタンス。
        indent: JSONインデントのスペースの数。
        include: 含めるフィールド。
        exclude: 除外するフィールド。
        by_alias: フィールド名にエイリアス名を使用するかどうか。
        exclude_unset: 設定されていないフィールドを除外するかどうか。
        exclude_defaults: デフォルト値を持つフィールドを除外するかどうか。
        exclude_none: `None`の値を持つフィールドを除外するかどうか。
        round_trip: ラウンドトリップを確実にするために、インスタンスをシリアライズしてデシリアライズするかどうか。
        warnings: シリアライゼーションエラーの処理方法。False/"none"はエラーを無視します。True/"warn"はエラーをログに記録します。"error"は[`PydanticSerializationError`][pydantic_core.PydanticSerializationError]を発生させます。
        serialize_as_any: ダック型のシリアライズ動作でフィールドをシリアライズするかどうか。
        context: シリアライザに渡す追加のコンテキスト。

    Returns:
        指定されたインスタンスのJSON表現(バイト単位)。
    """
    return self.serializer.to_json(
        instance,
        indent=indent,
        include=include,
        exclude=exclude,
        by_alias=by_alias,
        exclude_unset=exclude_unset,
        exclude_defaults=exclude_defaults,
        exclude_none=exclude_none,
        round_trip=round_trip,
        warnings=warnings,
        serialize_as_any=serialize_as_any,
        context=context,
    )

json_schema

json_schema(
    *,
    by_alias: bool = True,
    ref_template: str = DEFAULT_REF_TEMPLATE,
    schema_generator: type[
        GenerateJsonSchema
    ] = GenerateJsonSchema,
    mode: JsonSchemaMode = "validation"
) -> dict[str, Any]

適用された型のJSONスキーマを生成します。

Parameters:

Name	Type	Description	Default
by_alias	bool	フィールド名にエイリアス名を使用するかどうか。	True
ref_template	str	$ref文字列の生成に使用される書式文字列。	DEFAULT_REF_TEMPLATE
schema_generator	type[GenerateJsonSchema]	スキーマの作成に使用するジェネレーター・クラス。	GenerateJsonSchema
mode	JsonSchemaMode	スキーマの生成に使用するモード。	'validation'

Returns:

Type	Description
dict[str, Any]	ディクショナリとしてのモデルのJSONスキーマ。

Source code in pydantic/type_adapter.py

@_frame_depth(1)
def json_schema(
    self,
    *,
    by_alias: bool = True,
    ref_template: str = DEFAULT_REF_TEMPLATE,
    schema_generator: type[GenerateJsonSchema] = GenerateJsonSchema,
    mode: JsonSchemaMode = 'validation',
) -> dict[str, Any]:
    """適用された型のJSONスキーマを生成します。

    Args:
        by_alias: フィールド名にエイリアス名を使用するかどうか。
        ref_template: $ref文字列の生成に使用される書式文字列。
        schema_generator: スキーマの作成に使用するジェネレーター・クラス。
        mode: スキーマの生成に使用するモード。

    Returns:
        ディクショナリとしてのモデルのJSONスキーマ。
    """
    schema_generator_instance = schema_generator(by_alias=by_alias, ref_template=ref_template)
    return schema_generator_instance.generate(self.core_schema, mode=mode)

json_schemas staticmethod

json_schemas(
    inputs: Iterable[
        tuple[
            JsonSchemaKeyT, JsonSchemaMode, TypeAdapter[Any]
        ]
    ],
    /,
    *,
    by_alias: bool = True,
    title: str | None = None,
    description: str | None = None,
    ref_template: str = DEFAULT_REF_TEMPLATE,
    schema_generator: type[
        GenerateJsonSchema
    ] = GenerateJsonSchema,
) -> tuple[
    dict[
        tuple[JsonSchemaKeyT, JsonSchemaMode],
        JsonSchemaValue,
    ],
    JsonSchemaValue,
]

複数のタイプアダプタからの定義を含むJSONスキーマを生成します。

Parameters:

Name	Type	Description	Default
inputs	Iterable[tuple[JsonSchemaKeyT, JsonSchemaMode, TypeAdapter[Any]]]	スキーマ生成への入力です。最初の2つの項目は、(最初の)出力マッピングのキーを形成します。	required
by_alias	bool	エイリアス名を使用するかどうか。	True
title	str | None	スキーマのタイトル。	None
description	str | None	スキーマの説明。	None
ref_template	str	$ref文字列の生成に使用される書式文字列。	DEFAULT_REF_TEMPLATE
schema_generator	type[GenerateJsonSchema]	スキーマの作成に使用するジェネレーター・クラス。	GenerateJsonSchema

Returns:

Name	Type	Description
次の条件を満たすタプル	tuple[dict[tuple[JsonSchemaKeyT, JsonSchemaMode], JsonSchemaValue], JsonSchemaValue]	最初の要素は、JSONスキーマ・キー・タイプとJSONモードのタプルをキーとし、その入力ペアに対応するJSONスキーマを値とする辞書です(これらのスキーマは、2番目に返された要素で定義されている定義へのJsonRef参照を持つ場合があります)。 2番目の要素は、最初に返された要素で参照されるすべての定義と、オプションのtitleおよびdescriptionキーを含むJSONスキーマです。

Source code in pydantic/type_adapter.py

@staticmethod
def json_schemas(
    inputs: Iterable[tuple[JsonSchemaKeyT, JsonSchemaMode, TypeAdapter[Any]]],
    /,
    *,
    by_alias: bool = True,
    title: str | None = None,
    description: str | None = None,
    ref_template: str = DEFAULT_REF_TEMPLATE,
    schema_generator: type[GenerateJsonSchema] = GenerateJsonSchema,
) -> tuple[dict[tuple[JsonSchemaKeyT, JsonSchemaMode], JsonSchemaValue], JsonSchemaValue]:
    """複数のタイプアダプタからの定義を含むJSONスキーマを生成します。

    Args:
        inputs: スキーマ生成への入力です。最初の2つの項目は、(最初の)出力マッピングのキーを形成します。
        by_alias: エイリアス名を使用するかどうか。
        title: スキーマのタイトル。
        description: スキーマの説明。
        ref_template: $ref文字列の生成に使用される書式文字列。
        schema_generator: スキーマの作成に使用するジェネレーター・クラス。

    Returns:
        次の条件を満たすタプル:

            - 最初の要素は、JSONスキーマ・キー・タイプとJSONモードのタプルをキーとし、その入力ペアに対応するJSONスキーマを値とする辞書です(これらのスキーマは、2番目に返された要素で定義されている定義へのJsonRef参照を持つ場合があります)。
            - 2番目の要素は、最初に返された要素で参照されるすべての定義と、オプションのtitleおよびdescriptionキーを含むJSONスキーマです。
    """
    schema_generator_instance = schema_generator(by_alias=by_alias, ref_template=ref_template)

    inputs_ = []
    for key, mode, adapter in inputs:
        with adapter._with_frame_depth(1):  # +1 for json_schemas staticmethod
            inputs_.append((key, mode, adapter.core_schema))

    json_schemas_map, definitions = schema_generator_instance.generate_definitions(inputs_)

    json_schema: dict[str, Any] = {}
    if definitions:
        json_schema['$defs'] = definitions
    if title:
        json_schema['title'] = title
    if description:
        json_schema['description'] = description

    return json_schemas_map, json_schema