Skip to content

类型适配器

你可能需要验证非 BaseModel 类型的数据，或者想要验证 list[SomeModel] 并将其转储为 JSON。

API 文档

pydantic.type_adapter.TypeAdapter

对于此类用例，Pydantic 提供了 TypeAdapter，它可用于类型验证、序列化和 JSON 模式生成，而无需创建 BaseModel。

TypeAdapter 实例为没有此类方法的类型（例如数据类、原始类型等）公开了 BaseModel 实例方法中的部分功能：

from typing_extensions import TypedDict

from pydantic import TypeAdapter, ValidationError


class User(TypedDict):
    name: str
    id: int


user_list_adapter = TypeAdapter(list[User])
user_list = user_list_adapter.validate_python([{'name': 'Fred', 'id': '3'}])
print(repr(user_list))
#> [{'name': 'Fred', 'id': 3}]

try:
    user_list_adapter.validate_python(
        [{'name': 'Fred', 'id': 'wrong', 'other': 'no'}]
    )
except ValidationError as e:
    print(e)
    """
    1 validation error for list[User]
    0.id
      Input should be a valid integer, unable to parse string as an integer [type=int_parsing, input_value='wrong', input_type=str]
    """

print(repr(user_list_adapter.dump_json(user_list)))
#> b'[{"name":"Fred","id":3}]'

from typing import TypedDict

from pydantic import TypeAdapter, ValidationError


class User(TypedDict):
    name: str
    id: int


user_list_adapter = TypeAdapter(list[User])
user_list = user_list_adapter.validate_python([{'name': 'Fred', 'id': '3'}])
print(repr(user_list))
#> [{'name': 'Fred', 'id': 3}]

try:
    user_list_adapter.validate_python(
        [{'name': 'Fred', 'id': 'wrong', 'other': 'no'}]
    )
except ValidationError as e:
    print(e)
    """
    1 validation error for list[User]
    0.id
      Input should be a valid integer, unable to parse string as an integer [type=int_parsing, input_value='wrong', input_type=str]
    """

print(repr(user_list_adapter.dump_json(user_list)))
#> b'[{"name":"Fred","id":3}]'

dump_json 返回 bytes

TypeAdapter 的 dump_json 方法返回一个 bytes 对象，这与 BaseModel 的相应方法 model_dump_json（返回 str）不同。 这种差异的原因是，在 V1 版本中，模型转储返回 str 类型，因此在 V2 版本中保留了此行为以向后兼容。 对于 BaseModel 的情况，bytes 被强制转换为 str 类型，但 bytes 通常是所需的最终类型。 因此，对于 V2 版本中新的 TypeAdapter 类，返回类型仅为 bytes，如果需要，可以轻松地将其强制转换为 str 类型。

Note

尽管与 RootModel 在用例上有一些重叠，但 TypeAdapter 不应用作指定 BaseModel 等字段的类型注解。

将数据解析为指定类型

TypeAdapter 可用于应用解析逻辑，以更临时的方式填充 Pydantic 模型。此函数的行为类似于 BaseModel.model_validate，但适用于任意的 Pydantic 兼容类型。

当你想要将结果解析为非直接继承自 BaseModel 的类型时，这尤其有用。例如：

from pydantic import BaseModel, TypeAdapter


class Item(BaseModel):
    id: int
    name: str


# `item_data` 可能来自 API 调用，例如通过类似以下方式：
# item_data = requests.get('https://my-api.com/items').json()
item_data = [{'id': 1, 'name': 'My Item'}]

items = TypeAdapter(list[Item]).validate_python(item_data)
print(items)
#> [Item(id=1, name='My Item')]

TypeAdapter 能够将数据解析为 Pydantic 可以作为 BaseModel 字段处理的任何类型。

性能考虑

当创建 TypeAdapter 实例时，必须分析提供的类型并将其转换为 pydantic-core 模式。这会带来一些不小的开销，因此建议为给定类型仅创建一个 TypeAdapter，并在循环或其他性能关键代码中重复使用它。

重建 TypeAdapter 的模式

在 v2.10+ 版本中，TypeAdapter 支持延迟模式构建和手动重建。这对于以下情况很有帮助：

  • 具有前向引用的类型
  • 核心模式构建成本高的类型

当你使用类型初始化 TypeAdapter 时，Pydantic 会分析该类型并为其创建核心模式。 此核心模式包含验证和序列化该类型数据所需的信息。 有关核心模式的更多信息，请参阅 架构文档。

如果在初始化 TypeAdapter 时将 defer_build 设置为 True，Pydantic 将延迟构建核心模式，直到第一次需要它（用于验证或序列化）时。

为了手动触发核心模式的构建，你可以在 TypeAdapter 实例上调用 rebuild 方法：

from pydantic import ConfigDict, TypeAdapter

ta = TypeAdapter('MyInt', config=ConfigDict(defer_build=True))

# 一段时间后，前向引用被定义
MyInt = int

ta.rebuild()
assert ta.validate_python(1) == 1