标准库类型

本节列举了支持的内置类型和标准库类型：允许的值、可能的约束以及是否可以配置严格性。

另请参阅转换表，了解每种类型允许值的摘要。

注意

除非另有说明，否则在 Python 和 JSON 模式下，值均按原样序列化。

布尔值¶

内置类型：bool

验证

有效的bool实例，即True或False。
整数0或1。
字符串，当转换为小写后是'0'、'off'、'f'、'false'、'n'、'no'、'1'、'on' 't'、'true'、'y'、'yes'之一。
根据上述规则解码为字符串后有效的bytes对象。

严格性

在严格模式下，只有布尔值有效。Pydantic 提供了StrictBool类型作为使用Strict()元数据类的便捷方式。

示例

from pydantic import BaseModel, ValidationError


class BooleanModel(BaseModel):
    bool_value: bool


print(BooleanModel(bool_value=False))
#> bool_value=False
print(BooleanModel(bool_value='False'))
#> bool_value=False
print(BooleanModel(bool_value=1))
#> bool_value=True
try:
    BooleanModel(bool_value=[])
except ValidationError as e:
    print(str(e))
    """
    1 validation error for BooleanModel
    bool_value
      Input should be a valid boolean [type=bool_type, input_value=[], input_type=list]
    """

字符串¶

内置类型：str

验证

字符串按原样接受。
bytes和bytearray被解码为 UTF-8 字符串。
枚举使用value属性，通过对其调用str()进行转换。
如果设置了coerce_numbers_to_str，任何数字类型（int、float和Decimal）将被强制转换为字符串并按原样接受。

约束

字符串支持以下约束

约束	描述	JSON Schema
`pattern`	字符串必须匹配的正则表达式模式	`pattern`关键字（参见下面的注释）。
`min_length`	字符串的最小长度	`minLength`关键字
`max_length`	字符串的最大长度	`maxLength`关键字
`strip_whitespace`	是否移除前导和尾随空格	不适用
`to_upper`	是否将字符串转换为大写	不适用
`to_lower`	是否将字符串转换为小写	不适用

这些约束可以使用StringConstraints元数据类型或Field()函数提供（to_upper和to_lower除外）。也可以使用来自annotated-types库的MinLen、MaxLen、Len、LowerCase、UpperCase元数据类型。

pattern约束

默认情况下，Pydantic 将使用 regex Rust crate 来强制执行 `pattern` 约束。正则表达式引擎可以通过 `regex_engine` 配置值进行控制。如果使用已编译的正则表达式对象作为 `pattern`，将自动使用 Python 引擎。

尽管 JSON Schema 规范建议使用符合 ECMA-262 中描述的方言的有效模式，但 Pydantic **不会**强制执行此规定。

严格性

在严格模式下，只有字符串值有效。Pydantic 提供了StrictStr类型，作为使用Strict()元数据类的便捷方式。

示例

from typing import Annotated

from pydantic import BaseModel, StringConstraints


class StringModel(BaseModel):
    str_value: str = ""
    constrained_str_value: Annotated[str, StringConstraints(to_lower=True)] = ""


print(StringModel(str_value="test").str_value)
#> test
print(StringModel(constrained_str_value='TEST').constrained_str_value)
#> test

字节¶

内置类型：bytes。

另请参阅：ByteSize。

验证

bytes实例按原样验证。
字符串和bytearray实例根据val_json_bytes配置值（尽管其名称，它适用于 Python 和 JSON 模式）转换为字节。

约束

字符串支持以下约束

约束	描述	JSON Schema
`min_length`	字节的最小长度	`minLength`关键字
`max_length`	字节的最大长度	`maxLength`关键字

也可以使用来自annotated-types库的MinLen和MaxLen元数据类型。

严格性

在严格模式下，只有bytes实例有效。Pydantic 提供了StrictBytes类型，作为使用Strict()元数据类的便捷方式。

在 JSON 模式下，严格模式没有效果。

数字¶

Pydantic 支持 Python 标准库中的以下数字类型

整数¶

内置类型：int。

验证

整数按原样验证。
尝试将字符串和字节转换为整数并按原样验证（有关详细信息，请参阅jiter 实现）。
浮点数被验证为整数，前提是浮点数输入不是无限或 NaN（非数字），并且小数部分为 0。
Decimal实例，前提它们是有限的并且分母为 1。
Fraction实例，前提它们是整数。
枚举使用value属性进行转换。

约束

整数支持以下约束（数字必须可强制转换为整数）

约束	描述	JSON Schema
`le`	该值必须小于或等于此数字	`maximum` 关键字
`ge`	该值必须大于或等于此数字	`minimum` 关键字
`lt`	该值必须严格小于此数字	`exclusiveMaximum` 关键字
`gt`	该值必须严格大于此数字	`exclusiveMinimum` 关键字
`multiple_of`	该值必须是此数字的倍数	`multipleOf` 关键字

这些约束可以使用 Field() 函数提供。也可以使用来自 annotated-types 库的 Le、Ge、Lt、Gt 和 MultipleOf 元数据类型。

Pydantic 还提供了以下类型以进一步约束允许的整数值

PositiveInt：要求输入大于零。
NegativeInt：要求输入小于零。
NonPositiveInt：要求输入小于或等于零。
NonNegativeInt：要求输入大于或等于零。

严格性

在严格模式下，只有整数值有效。Pydantic 提供了StrictInt类型，作为使用Strict()元数据类的便捷方式。

浮点数¶

内置类型：float。

验证

浮点数按原样验证。
尝试将字符串和字节转换为浮点数并按原样验证。（有关详细信息，请参阅Rust 实现）。
如果输入具有__float__()方法，则将调用它以将输入转换为浮点数。如果未定义__float__()，则回退到__index__()。这包括（但不限于）Decimal和Fraction类型。

约束

浮点数支持以下约束

约束	描述	JSON Schema
`le`	该值必须小于或等于此数字	`maximum` 关键字
`ge`	该值必须大于或等于此数字	`minimum` 关键字
`lt`	该值必须严格小于此数字	`exclusiveMaximum` 关键字
`gt`	该值必须严格大于此数字	`exclusiveMinimum` 关键字
`multiple_of`	该值必须是此数字的倍数	`multipleOf` 关键字
`allow_inf_nan`	是否允许 NaN（非数字）和无穷大值	不适用

这些约束可以使用Field()函数提供。也可以使用来自annotated-types库的Le、Ge、Lt、Gt和MultipleOf元数据类型以及AllowInfNan类型。

Pydantic 还提供以下类型作为方便的别名

PositiveFloat：要求输入大于零。
NegativeFloat：要求输入小于零。
NonPositiveFloat：要求输入小于或等于零。
NonNegativeFloat：要求输入大于或等于零。
FiniteFloat：防止 NaN（非数字）和无穷大值。

严格性

在严格模式下，只有浮点值以及具有__float__()或__index__()方法的输入有效。Pydantic 提供了StrictFloat类型作为使用Strict()元数据类的便捷方式。

整数枚举¶

标准库类型：enum.IntEnum。

验证

如果直接使用enum.IntEnum类型，则任何enum.IntEnum实例都按原样验证
如果将enum.IntEnum子类用作类型，则任何枚举成员或对应于枚举成员值的任何值都按原样验证。

有关更多详细信息，请参阅枚举。

小数¶

标准库类型：decimal.Decimal。

验证

Decimal实例按原样验证。
Decimal构造函数接受的任何值（除了三元组输入）都将通过验证。

约束

小数支持以下约束（数字必须可强制转换为小数）

约束	描述	JSON Schema
`le`	该值必须小于或等于此数字	`maximum` 关键字
`ge`	该值必须大于或等于此数字	`minimum` 关键字
`lt`	该值必须严格小于此数字	`exclusiveMaximum` 关键字
`gt`	该值必须严格大于此数字	`exclusiveMinimum` 关键字
`multiple_of`	该值必须是此数字的倍数	`multipleOf` 关键字
`allow_inf_nan`	是否允许 NaN（非数字）和无穷大值	不适用
`max_digits`	允许的最大小数位数。小数点前的零和尾随零不计算在内。	`pattern` 关键字，用于描述字符串模式
`decimal_places`	允许的最大小数位。尾随零不计算在内。	`pattern` 关键字，用于描述字符串模式

请注意，JSON Schema 的 `pattern` 关键字将始终在 JSON Schema 中指定，以描述字符串模式（并且如果指定了 `max_digits` 和/或 `decimal_places`，则可能会有所不同）。

这些约束可以使用Field()函数提供。也可以使用来自annotated-types库的Le、Ge、Lt、Gt和MultipleOf元数据类型以及AllowInfNan类型。

严格性

在严格模式下，只接受decimal.Decimal实例。在 JSON 模式下，严格模式没有效果。

序列化

在Python 模式下，Decimal实例按原样序列化。

在JSON 模式下，它们被序列化为字符串。可以使用序列化器来覆盖此行为

from decimal import Decimal
from typing import Annotated

from pydantic import BaseModel, PlainSerializer


class Model(BaseModel):
    f: Annotated[Decimal, PlainSerializer(float, when_used='json')]


my_model = Model(f=Decimal('2.1'))

print(my_model.model_dump())  # (1)!
#> {'f': Decimal('2.1')}
print(my_model.model_dump_json())  # (2)!
#> {"f":2.1}

在 Python 模式下，f仍是Decimal实例。
在 JSON 模式下，f被序列化为浮点数。

复数¶

内置类型：complex。

验证

complex实例按原样验证。
字符串使用complex()构造函数进行验证。
数字（整数和浮点数）用作实部。
定义__complex__()、__float__()或__index__()的对象目前**不**被接受。

严格性

在严格模式下，只接受complex实例。在 JSON 模式下，只允许complex()构造函数接受的字符串。

序列化

在Python 模式下，complex实例按原样序列化。

在JSON 模式下，它们被序列化为字符串。

分数¶

标准库类型：fractions.Fraction。

验证

Fraction实例按原样验证。
浮点数、字符串和decimal.Decimal实例使用Fraction()构造函数进行验证。

严格性

在严格模式下，只接受Fraction实例。在 JSON 模式下，严格模式没有效果。

序列化

分数在Python和JSON模式下都序列化为字符串。

日期和时间类型¶

Pydantic 支持datetime标准库中的以下日期和时间类型

日期时间¶

标准库类型：datetime.datetime。

验证

datetime实例按原样验证。
字符串和字节以两种方式进行验证
- 符合RFC 3339格式的字符串（日期时间和日期）。有关详细信息，请参阅speedate文档。
- Unix 时间戳，以秒或毫秒为单位，自纪元开始。有关详细信息，请参阅val_temporal_unit配置值。
整数和浮点数（或可强制转换为整数或浮点数的类型）被验证为 Unix 时间戳，遵循与字符串相同的语义。
接受datetime.date实例，并通过将hour、minute、second和microsecond属性设置为0，并将tzinfo属性设置为None，将其转换为datetime实例。

注意

命名时区支持（如RFC 9557中指定）可在此问题中跟踪。

序列化

在Python 模式下，datetime实例按原样序列化。

在JSON 模式下，它们被序列化为字符串。

约束

日期时间支持以下约束（约束值必须可强制转换为datetime实例）

约束	描述	JSON Schema
`le`	该值必须小于或等于此日期时间	不适用
`ge`	该值必须大于或等于此日期时间	不适用
`lt`	该值必须严格小于此日期时间	不适用
`gt`	该值必须严格大于此日期时间	不适用

这些约束可以使用 Field() 函数提供。也可以使用来自 annotated-types 库的 Le、Ge、Lt 和 Gt 元数据类型。

Pydantic 还提供了以下类型以进一步约束允许的日期时间值

AwareDatetime：要求输入具有时区。
NaiveDatetime：要求输入**不**具有时区。
PastDatetime：要求输入在验证时是过去的。
FutureDatetime：要求输入在验证时是未来的。

严格性

在严格模式下，只接受datetime实例。在 JSON 模式下，只接受符合RFC 3339格式的字符串（**仅**日期时间）或 Unix 时间戳。

示例

from datetime import datetime
from typing import Annotated

from pydantic import AwareDatetime, BaseModel, Field


class Event(BaseModel):
    dt: Annotated[AwareDatetime, Field(gt=datetime(2000, 1, 1))]


event = Event(dt='2032-04-23T10:20:30.400+02:30')

print(event.model_dump())
"""
{'dt': datetime.datetime(2032, 4, 23, 10, 20, 30, 400000, tzinfo=TzInfo(9000))}
"""
print(event.model_dump_json())
#> {"dt":"2032-04-23T10:20:30.400000+02:30"}

日期¶

标准库类型：datetime.date。

验证

date实例按原样验证。
字符串和字节以两种方式进行验证
- 符合RFC 3339日期格式的字符串。有关更多详细信息，请参阅speedate文档。
- Unix 时间戳，以秒或毫秒为单位，自纪元开始。有关详细信息，请参阅val_temporal_unit配置值。
如果验证失败，输入可以作为日期时间进行验证（包括作为数字），前提是时间组件为 0 且它是朴素的。

序列化

在Python 模式下，date实例按原样序列化。

在JSON 模式下，它们被序列化为字符串。

约束

日期支持以下约束（约束值必须可强制转换为date实例）

约束	描述	JSON Schema
`le`	该值必须小于或等于此日期	不适用
`ge`	该值必须大于或等于此日期	不适用
`lt`	该值必须严格小于此日期	不适用
`gt`	该值必须严格大于此日期	不适用

这些约束可以使用 Field() 函数提供。也可以使用来自 annotated-types 库的 Le、Ge、Lt 和 Gt 元数据类型。

Pydantic 还提供了以下类型以进一步约束允许的日期值

PastDate：要求输入在验证时是过去的。
FutureDate：要求输入在验证时是未来的。

严格性

在严格模式下，只接受date实例。在 JSON 模式下，只接受符合RFC 3339格式的字符串（**仅**日期）或 Unix 时间戳。

示例

from datetime import date

from pydantic import BaseModel


class Birthday(BaseModel):
    d: date


my_birthday = Birthday(d=1679616000.0)

print(my_birthday.model_dump())
#> {'d': datetime.date(2023, 3, 24)}
print(my_birthday.model_dump_json())
#> {"d":"2023-03-24"}

时间¶

标准库类型：datetime.time。

验证

time实例按原样验证。
字符串和字节根据RFC 3339时间格式进行验证。
整数和浮点数（或可强制转换为此类数字的值）被验证为秒。该值不应超过 86 399。

序列化

在Python 模式下，time实例按原样序列化。

在JSON 模式下，它们被序列化为字符串。

注意

来自 IANA 时区数据库的命名时区（参见 `zoneinfo` 模块）**不**与时间对象一起序列化。这与 `time.isoformat()` 方法一致。

约束

时间支持以下约束（约束值必须可强制转换为time实例）

约束	描述	JSON Schema
`le`	该值必须小于或等于此时间	不适用
`ge`	该值必须大于或等于此时间	不适用
`lt`	该值必须严格小于此时间	不适用
`gt`	该值必须严格大于此时间	不适用

这些约束可以使用 Field() 函数提供。也可以使用来自 annotated-types 库的 Le、Ge、Lt 和 Gt 元数据类型。

严格性

在严格模式下，只接受time实例。在 JSON 模式下，只接受符合RFC 3339格式的字符串。

示例

from datetime import time

from pydantic import BaseModel


class Meeting(BaseModel):
    t: time


m = Meeting(t=time(4, 8, 16))

print(m.model_dump())
#> {'t': datetime.time(4, 8, 16)}
print(m.model_dump_json())
#> {"t":"04:08:16"}

时间差¶

标准库类型：datetime.timedelta。

验证

timedelta实例按原样验证。
字符串和字节根据RFC 3339时间格式进行验证。
整数和浮点数（或可强制转换为此类数字的值）被验证为秒。

约束

时间差支持以下约束（约束值必须可强制转换为timedelta实例）

约束	描述	JSON Schema
`le`	该值必须小于或等于此时间差	不适用
`ge`	该值必须大于或等于此时间差	不适用
`lt`	该值必须严格小于此时间差	不适用
`gt`	该值必须严格大于此时间差	不适用

这些约束可以使用 Field() 函数提供。也可以使用来自 annotated-types 库的 Le、Ge、Lt 和 Gt 元数据类型。

序列化

在Python 模式下，timedelta实例按原样序列化。

在JSON 模式下，它们被序列化为字符串。

严格性

在严格模式下，只接受timedelta实例。在 JSON 模式下，只接受符合RFC 3339格式的字符串。

示例

from datetime import timedelta

from pydantic import BaseModel


class Model(BaseModel):
    td: timedelta


m = Model(td='P3DT12H30M5S')

print(m.model_dump())
#> {'td': datetime.timedelta(days=3, seconds=45005)}
print(m.model_dump_json())
#> {"td":"P3DT12H30M5S"}

枚举¶

标准库类型：enum.Enum。

验证

如果直接使用enum.Enum类型，则任何enum.Enum实例都按原样验证。
如果将enum.Enum子类用作类型，则任何枚举成员或对应于枚举成员值的值都按原样验证。

序列化

在Python 模式下，枚举实例按原样序列化。可以设置use_enum_values配置值以在验证期间使用枚举值（以便在序列化期间也使用它）。

在JSON 模式下，枚举实例使用其值进行序列化。

示例

from enum import Enum, IntEnum

from pydantic import BaseModel, ValidationError


class FruitEnum(str, Enum):
    PEAR = 'pear'
    BANANA = 'banana'


class ToolEnum(IntEnum):
    SPANNER = 1
    WRENCH = 2


class CookingModel(BaseModel):
    fruit: FruitEnum = FruitEnum.PEAR
    tool: ToolEnum = ToolEnum.SPANNER


print(CookingModel())
#> fruit=<FruitEnum.PEAR: 'pear'> tool=<ToolEnum.SPANNER: 1>
print(CookingModel(tool=2, fruit='banana'))
#> fruit=<FruitEnum.BANANA: 'banana'> tool=<ToolEnum.WRENCH: 2>
try:
    CookingModel(fruit='other')
except ValidationError as e:
    print(e)
    """
    1 validation error for CookingModel
    fruit
      Input should be 'pear' or 'banana' [type=enum, input_value='other', input_type=str]
    """

None 类型¶

支持的类型：None、NoneType或Literal[None]（它们等价）。

只允许None作为值。

泛型集合类型¶

Pydantic 支持各种泛型集合类型，包括内置类型（如list）和来自collections.abc模块的抽象基类（如Sequence）。

在大多数情况下，建议使用内置类型而不是抽象类型。由于数据转换，使用list或tuple将允许大多数其他可迭代对象作为输入，并且具有更好的性能。

集合类型的严格性

当对集合类型应用严格模式时，严格性**不**适用于内部类型。这在未来可能会改变，请参阅此问题。

列表¶

内置类型：list（已弃用别名：typing.List）。

验证

允许list、tuple、set和frozenset实例，或任何**不是**字符串、字节、字节数组、字典或映射的可迭代对象。生成list实例。
如果提供了泛型参数，则对列表的所有项应用适当的验证。

约束

列表支持以下约束

约束	描述	JSON Schema
`min_length`	列表必须至少包含此数量的项	`minItems` 关键字
`max_length`	列表必须最多包含此数量的项	`maxItems` 关键字

这些约束可以使用 Field() 函数提供。也可以使用来自 annotated-types 库的 MinLen 和 MaxLen 元数据类型。

严格性

在严格模式下，只有list实例有效。严格模式**不**适用于列表的项。必须将严格约束应用于参数类型才能使其工作。

示例

Python 3.9 及以上版本Python 3.10 及以上版本

from typing import Optional

from pydantic import BaseModel, Field


class Model(BaseModel):
    simple_list: Optional[list[object]] = None
    list_of_ints: Optional[list[int]] = Field(default=None, strict=True)


print(Model(simple_list=('1', '2', '3')).simple_list)
#> ['1', '2', '3']
print(Model(list_of_ints=['1', 2, 3]).list_of_ints)
#> [1, 2, 3]

from pydantic import BaseModel, Field


class Model(BaseModel):
    simple_list: list[object] | None = None
    list_of_ints: list[int] | None = Field(default=None, strict=True)


print(Model(simple_list=('1', '2', '3')).simple_list)
#> ['1', '2', '3']
print(Model(list_of_ints=['1', 2, 3]).list_of_ints)
#> [1, 2, 3]

元组¶

内置类型：tuple（已弃用别名：typing.Tuple）。

注意

解包元组类型（如 PEP 646 中指定）尚未支持，可在此问题中跟踪。

验证

允许tuple、list、set和frozenset实例，或任何**不是**字符串、字节、字节数组、字典或映射的可迭代对象。生成tuple实例。
如果指定了元素类型，则对元组的项应用适当的验证。

约束

列表支持以下约束

约束	描述	JSON Schema
`min_length`	元组必须至少包含此数量的项	`minItems` 关键字
`max_length`	元组必须最多包含此数量的项	`maxItems` 关键字

这些约束可以使用 Field() 函数提供。也可以使用来自 annotated-types 库的 MinLen 和 MaxLen 元数据类型。

此外，根据元组的形状，可以使用 `prefixItems` JSON Schema 关键字。

严格性

在严格模式下，只有tuple实例有效。严格模式**不**适用于元组的项。必须将严格约束应用于参数类型才能使其工作。

示例

Python 3.9 及以上版本Python 3.10 及以上版本

from typing import Optional

from pydantic import BaseModel


class Model(BaseModel):
    simple_tuple: Optional[tuple] = None
    tuple_of_different_types: Optional[tuple[int, float, bool]] = None


print(Model(simple_tuple=[1, 2, 3, 4]).simple_tuple)
#> (1, 2, 3, 4)
print(Model(tuple_of_different_types=[3, 2, 1]).tuple_of_different_types)
#> (3, 2.0, True)

from pydantic import BaseModel


class Model(BaseModel):
    simple_tuple: tuple | None = None
    tuple_of_different_types: tuple[int, float, bool] | None = None


print(Model(simple_tuple=[1, 2, 3, 4]).simple_tuple)
#> (1, 2, 3, 4)
print(Model(tuple_of_different_types=[3, 2, 1]).tuple_of_different_types)
#> (3, 2.0, True)

命名元组¶

标准库类型：typing.NamedTuple（以及由collections.namedtuple()工厂函数创建的类型——每个字段都将隐式具有Any类型）。

验证

允许tuple和list实例。根据字段定义验证每个项。
允许dict实例。键必须与命名元组字段名称匹配，值根据字段定义进行验证。

序列化

在Python 模式下，命名元组序列化为元组。在JSON 模式下，它们序列化为数组。

示例

from typing import NamedTuple

from pydantic import BaseModel


class Point(NamedTuple):
    x: int
    y: int


class Model(BaseModel):
    p: Point


model = Model(p=('1', 2))

print(model.model_dump())
#> {'p': (1, 2)}

集合¶

类型：set（或collections.abc.MutableSet）和frozenset（或collections.abc.Set）（已弃用别名：typing.Set和typing.FrozenSet）。

验证

允许 `set`、`frozenset`、`tuple` 和 `list` 实例，或任何**不是** 字符串、字节、字节数组、字典或映射的可迭代对象。生成 `set` 或 `frozenset` 实例。
如果提供了泛型参数，则对集合/不可变集合的所有项应用适当的验证。

约束

集合支持以下约束

约束	描述	JSON Schema
`min_length`	集合必须至少包含此数量的项	`minItems` 关键字
`max_length`	集合必须最多包含此数量的项	`maxItems` 关键字

这些约束可以使用 Field() 函数提供。也可以使用来自 annotated-types 库的 MinLen 和 MaxLen 元数据类型。

严格性

在严格模式下，只有set/frozenset实例有效。严格模式**不**适用于集合的项。必须将严格约束应用于参数类型才能使其工作。

序列化

在Python 模式下，集合按原样序列化。在JSON 模式下，它们序列化为数组。

示例

Python 3.9 及以上版本Python 3.10 及以上版本

from typing import Optional

from pydantic import BaseModel


class Model(BaseModel):
    simple_set: Optional[set] = None
    set_of_ints: Optional[frozenset[int]] = None


print(Model(simple_set=['1', '2', '3']).simple_set)
#> {'1', '2', '3'}
print(Model(set_of_ints=['1', '2', '3']).set_of_ints)
#> frozenset({1, 2, 3})

from pydantic import BaseModel


class Model(BaseModel):
    simple_set: set | None = None
    set_of_ints: frozenset[int] | None = None


print(Model(simple_set=['1', '2', '3']).simple_set)
#> {'1', '2', '3'}
print(Model(set_of_ints=['1', '2', '3']).set_of_ints)
#> frozenset({1, 2, 3})

双端队列¶

标准库类型：collections.deque（已弃用别名：typing.Deque）。

验证

值首先作为列表进行验证，然后传递给deque构造函数。

约束

双端队列支持以下约束

约束	描述	JSON Schema
`min_length`	双端队列必须至少包含此数量的项	`minItems` 关键字
`max_length`	双端队列必须最多包含此数量的项	`maxItems` 关键字

这些约束可以使用 Field() 函数提供。也可以使用来自 annotated-types 库的 MinLen 和 MaxLen 元数据类型。

严格性

在严格模式下，只有deque实例有效。严格模式**不**适用于双端队列的项。必须将严格约束应用于参数类型才能使其工作。

序列化

在Python 模式下，双端队列按原样序列化。在JSON 模式下，它们序列化为数组。

示例

from collections import deque

from pydantic import BaseModel


class Model(BaseModel):
    deque: deque[int]


print(Model(deque=[1, 2, 3]).deque)
#> deque([1, 2, 3])

序列¶

标准库类型：collections.abc.Sequence（已弃用别名：typing.Sequence）。

在大多数情况下，您会希望使用内置类型（例如列表或元组），因为会应用类型强制转换。当您希望在序列化期间保留输入类型时，可以使用Sequence类型。

验证

任何collections.abc.Sequence实例（期望字符串和字节）都被接受。它使用list()构造函数转换为列表，然后转换回原始输入类型。

字符串不被视为序列

虽然字符串在技术上是有效的序列实例，但这通常不是预期用途，并且是常见的错误源。

因此，Pydantic **不**接受Sequence类型的字符串和字节（参见下面的示例）。

约束

序列支持以下约束

约束	描述	JSON Schema
`min_length`	序列必须至少包含此数量的项	`minItems` 关键字
`max_length`	序列必须最多包含此数量的项	`maxItems` 关键字

这些约束可以使用 Field() 函数提供。也可以使用来自 annotated-types 库的 MinLen 和 MaxLen 元数据类型。

序列化

在Python 模式下，序列按原样序列化。在JSON 模式下，它们序列化为数组。

示例

from collections.abc import Sequence

from pydantic import BaseModel, ValidationError


class Model(BaseModel):
    sequence_of_strs: Sequence[str]


print(Model(sequence_of_strs=['a', 'bc']).sequence_of_strs)
#> ['a', 'bc']
print(Model(sequence_of_strs=('a', 'bc')).sequence_of_strs)
#> ('a', 'bc')

try:
    Model(sequence_of_strs='abc')
except ValidationError as e:
    print(e)
    """
    1 validation error for Model
    sequence_of_strs
      'str' instances are not allowed as a Sequence value [type=sequence_str, input_value='abc', input_type=str]
    """

字典¶

内置类型：dict。

验证

dict实例按原样接受。
映射实例被接受并强制转换为dict。
如果提供了键和值的泛型参数，则应用适当的验证。

约束

字典支持以下约束

约束	描述	JSON Schema
`min_length`	字典必须至少包含此数量的项	`minItems` 关键字
`max_length`	字典必须最多包含此数量的项	`maxItems` 关键字

这些约束可以使用 Field() 函数提供。也可以使用来自 annotated-types 库的 MinLen 和 MaxLen 元数据类型。

严格性

在严格模式下，只有dict实例有效。严格模式**不**适用于字典的键和值。必须将严格约束应用于参数类型才能使其工作。

示例

from pydantic import BaseModel, ValidationError


class Model(BaseModel):
    x: dict[str, int]


m = Model(x={'foo': 1})
print(m.model_dump())
#> {'x': {'foo': 1}}

try:
    Model(x='test')
except ValidationError as e:
    print(e)
    """
    1 validation error for Model
    x
      Input should be a valid dictionary [type=dict_type, input_value='test', input_type=str]
    """

类型化字典¶

标准库类型：typing.TypedDict（另请参阅：类型化规范）。

注意

由于运行时限制，Pydantic 在使用 Python 3.12 及更低版本时将需要使用来自 `typing_extensions` 的 `TypedDict` 类型。

TypedDict声明了一个字典类型，它期望所有实例都具有一组特定的键，其中每个键都与一个一致类型的值相关联。

此类型支持配置。

严格性

在严格模式下，只有dict实例有效（与宽松模式下的映射不同）。严格模式**不**适用于类型化字典的值。必须将严格约束应用于值类型才能使其工作。

示例

Python 3.9 及以上版本Python 3.13 及以上版本

from typing_extensions import TypedDict

from pydantic import TypeAdapter, ValidationError


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


ta = TypeAdapter(User)

print(ta.validate_python({'name': 'foo', 'id': 1}))
#> {'name': 'foo', 'id': 1}

try:
    ta.validate_python({'name': 'foo'})
except ValidationError as e:
    print(e)
    """
    1 validation error for User
    id
      Field required [type=missing, input_value={'name': 'foo'}, input_type=dict]
    """

from typing import TypedDict

from pydantic import TypeAdapter, ValidationError


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


ta = TypeAdapter(User)

print(ta.validate_python({'name': 'foo', 'id': 1}))
#> {'name': 'foo', 'id': 1}

try:
    ta.validate_python({'name': 'foo'})
except ValidationError as e:
    print(e)
    """
    1 validation error for User
    id
      Field required [type=missing, input_value={'name': 'foo'}, input_type=dict]
    """

可迭代对象¶

标准库类型：collections.abc.Iterable（已弃用别名：typing.Iterable）。

验证

可迭代对象是惰性验证的，并封装在一个内部数据结构中，可以对其进行迭代（并在此过程中验证项类型）。这意味着即使您提供了一个具体的容器（例如列表），验证的类型也**不**是list类型。但是，Pydantic 将通过从输入值获取迭代器（通过对值调用iter()）来确保输入值是可迭代的。

建议使用具体的集合类型（例如列表），除非您使用的是无限迭代器（在这种情况下，急切地验证输入会导致无限循环）。

示例

from collections.abc import Iterable

from pydantic import BaseModel, ValidationError


class Model(BaseModel):
    f: Iterable[str]


m = Model(f=[1, 2])  # Validates fine

try:
    next(m.f)
except ValidationError as e:
    print(e)
    """
    1 validation error for ValidatorIterator
    0
      Input should be a valid string [type=string_type, input_value=1, input_type=int]
    """

可调用对象¶

标准库类型：collections.abc.Callable（已弃用别名：typing.Callable）。

验证

Pydantic 只验证输入是否为可调用对象（使用callable()函数）。它**不**验证参数的数量或其类型，也不验证返回值的类型。

Python 3.9 及以上版本Python 3.10 及以上版本

from typing import Callable

from pydantic import BaseModel


class Foo(BaseModel):
    callback: Callable[[int], int]


m = Foo(callback=lambda x: x)
print(m)
#> callback=<function <lambda> at 0x0123456789ab>

from collections.abc import Callable

from pydantic import BaseModel


class Foo(BaseModel):
    callback: Callable[[int], int]


m = Foo(callback=lambda x: x)
print(m)
#> callback=<function <lambda> at 0x0123456789ab>

序列化

可调用对象按原样序列化。可调用对象不能在JSON 模式下序列化（会引发PydanticSerializationError）。

IP 地址¶

标准库类型

另请参阅：IPvAnyAddress、IPvAnyInterface和IPvAnyNetwork Pydantic 类型。

验证

实例按原样验证。
其他输入值传递给相关地址类型的构造函数。

严格性

在严格模式下，只接受地址类型。在 JSON 模式下，严格模式没有效果。

序列化

在Python 模式下，IP 地址按原样序列化。在JSON 模式下，它们序列化为字符串。

UUID¶

标准库类型：uuid.UUID。

验证

UUID实例按原样验证。
字符串和字节被验证为 UUID，并转换为UUID实例。

约束

UUID类型支持version约束。可以使用UuidVersion元数据类型。

Pydantic 还提供以下类型作为方便的别名：UUID1、UUID3、UUID4、UUID5、UUID6、UUID7、UUID8。

严格性

在严格模式下，只接受UUID实例。在 JSON 模式下，严格模式没有效果。

序列化

在Python 模式下，UUID 按原样序列化。在JSON 模式下，它们序列化为字符串。

示例

from typing import Annotated
from uuid import UUID

from pydantic import BaseModel
from pydantic.types import UUID7, UuidVersion


class Model(BaseModel):
    u1: UUID7
    u2: Annotated[UUID, UuidVersion(4)]


print(
    Model(
        u1='01999b2c-8353-749b-8dac-859307fae22b',
        u2=UUID('125725f3-e1b4-44e3-90c3-1a20eab12da5'),
    )
)
"""
u1=UUID('01999b2c-8353-749b-8dac-859307fae22b') u2=UUID('125725f3-e1b4-44e3-90c3-1a20eab12da5')
"""

类型¶

内置类型：type（已弃用别名：typing.Type）。

验证

允许作为类型参数的子类的任何类型。例如，对于type[str]，允许str类或任何str子类作为输入。如果没有提供类型参数（即使用type作为注释），则允许任何类。

序列化

类型按原样序列化。类型不能在JSON 模式下序列化（会引发PydanticSerializationError）。

from pydantic import BaseModel, ValidationError


class Foo:
    pass


class Bar(Foo):
    pass


class Other:
    pass


class SimpleModel(BaseModel):
    just_subclasses: type[Foo]


SimpleModel(just_subclasses=Foo)
SimpleModel(just_subclasses=Bar)
try:
    SimpleModel(just_subclasses=Other)
except ValidationError as e:
    print(e)
    """
    1 validation error for SimpleModel
    just_subclasses
      Input should be a subclass of Foo [type=is_subclass_of, input_value=<class '__main__.Other'>, input_type=type]
    """

字面量¶

类型构造：typing.Literal（另请参阅：类型化规范）。

字面量可用于只允许特定的字面值。

请注意，Pydantic 在验证字面值时会应用严格模式行为（请参阅此问题）。

示例

from typing import Literal

from pydantic import BaseModel, ValidationError


class Pie(BaseModel):
    flavor: Literal['apple', 'pumpkin']
    quantity: Literal[1, 2] = 1


Pie(flavor='apple')
Pie(flavor='pumpkin')
try:
    Pie(flavor='cherry')
except ValidationError as e:
    print(str(e))
    """
    1 validation error for Pie
    flavor
      Input should be 'apple' or 'pumpkin' [type=literal_error, input_value='cherry', input_type=str]
    """

try:
    Pie(flavor='apple', quantity='1')
except ValidationError as e:
    print(str(e))
    """
    1 validation error for Pie
    quantity
      Input should be 1 or 2 [type=literal_error, input_value='1', input_type=str]
    """

任意类型¶

类型：typing.Any或object。

允许任何值，包括None。

可哈希对象¶

标准库类型：collections.abc.Hashable（已弃用别名：typing.Hashable）。

验证

任何可哈希的值（使用isinstance(value, Hashable)）。

正则表达式模式¶

标准库类型：re.Pattern（已弃用别名：typing.Pattern）。

验证

对于Pattern实例，检查pattern属性是否为正确类型（str或bytes，取决于Pattern类型参数）。
如果类型参数是str或bytes，则尝试使用re.compile()编译类型为str（或bytes）的输入值。

序列化

在Python 模式下，Pattern实例按原样序列化。

在JSON 模式下，它们被序列化为字符串。

路径¶

标准库类型

pathlib.Path.
pathlib.PurePath.
pathlib.PosixPath.
pathlib.PurePosixPath.
pathlib.PureWindowsPath.
os.PathLike（必须用str、bytes或Any参数化）。

验证

路径实例按原样验证。
字符串被接受并传递给类型构造函数。如果使用os.PathLike，则如果用bytes类型参数化，则接受字节。

严格性

在严格模式下，只接受路径实例。在 JSON 模式下，严格模式没有效果。

序列化

在Python 模式下，路径实例按原样序列化。

在JSON 模式下，它们被序列化为字符串。