严格模式

API 文档

pydantic.types.Strict

默认情况下，Pydantic 将尝试在可能的情况下将值强制转换为所需的类型。例如，您可以将字符串 "123" 作为输入传递给 int 字段，它将被转换为 123 。这种强制转换行为在许多场景中很有用——想想：UUID、URL 参数、HTTP 标头、环境变量、用户输入等。

然而，也有一些情况不希望这样做，而是希望 Pydantic 报错而不是强制数据。

为了更好地支持这种用例，Pydantic 提供了一种“严格模式”，可以在每个模型、每个字段甚至每个验证调用的基础上启用。启用严格模式后，Pydantic 在强制数据时将不那么宽容，而是如果数据类型不正确，将报错。

以下是一个简短的示例，展示了严格模式和默认/"宽松"模式下验证行为的区别：

from pydantic import BaseModel, ValidationError


class MyModel(BaseModel):
    x: int


print(MyModel.model_validate({'x': '123'}))  # lax mode
#> x=123

try:
    MyModel.model_validate({'x': '123'}, strict=True)  # strict mode
except ValidationError as exc:
    print(exc)
    """
    1 validation error for MyModel
    x
      Input should be a valid integer [type=int_type, input_value='123', input_type=str]
    """

有多种方法可以在使用 Pydantic 时获得严格模式验证，下面将更详细地讨论这些方法：

将 strict=True 传递给验证方法，例如 BaseModel.model_validate 、 TypeAdapter.validate_python 等，适用于 JSON
使用 Field(strict=True) 与 BaseModel 、 dataclass 或 TypedDict 的字段
使用 pydantic.types.Strict 作为字段的类型注释
- Pydantic 提供了一些已经用 Strict 注释的类型别名，例如 pydantic.types.StrictInt
Using ConfigDict(strict=True)

严格模式下的类型强制转换¶

对于大多数类型，在严格模式下从 Python 验证数据时，仅接受确切类型的实例。例如，在验证 int 字段时，仅接受 int 的实例；传递 float 或 str 的实例将导致引发 ValidationError 。

请注意，在严格模式下验证来自 JSON 的数据时，我们会更宽松。例如，在验证 UUID 字段时，从 JSON 验证时将接受 str 的实例，但从 Python 验证时则不会：

import json
from uuid import UUID

from pydantic import BaseModel, ValidationError


class MyModel(BaseModel):
    guid: UUID


data = {'guid': '12345678-1234-1234-1234-123456789012'}

print(MyModel.model_validate(data))  # OK: lax
#> guid=UUID('12345678-1234-1234-1234-123456789012')

print(
    MyModel.model_validate_json(json.dumps(data), strict=True)
)  # OK: strict, but from json
#> guid=UUID('12345678-1234-1234-1234-123456789012')

try:
    MyModel.model_validate(data, strict=True)  # Not OK: strict, from python
except ValidationError as exc:
    print(exc.errors(include_url=False))
    """
    [
        {
            'type': 'is_instance_of',
            'loc': ('guid',),
            'msg': 'Input should be an instance of UUID',
            'input': '12345678-1234-1234-1234-123456789012',
            'ctx': {'class': 'UUID'},
        }
    ]
    """

对于严格模式下允许作为输入的类型的更多详细信息，您可以查看转换表。

严格模式在方法调用中¶

所有到目前为止包含的示例都通过使用 strict=True 作为验证方法的关键字参数来获得严格模式验证。虽然我们已经为 BaseModel.model_validate 展示了这一点，但通过使用 TypeAdapter ，这也适用于任意类型：

from pydantic import TypeAdapter, ValidationError

print(TypeAdapter(bool).validate_python('yes'))  # OK: lax
#> True

try:
    TypeAdapter(bool).validate_python('yes', strict=True)  # Not OK: strict
except ValidationError as exc:
    print(exc)
    """
    1 validation error for bool
      Input should be a valid boolean [type=bool_type, input_value='yes', input_type=str]
    """

请注意，即使在 TypeAdapter 中使用更“复杂”的类型时，此方法也适用：

from dataclasses import dataclass

from pydantic import TypeAdapter, ValidationError


@dataclass
class MyDataclass:
    x: int


try:
    TypeAdapter(MyDataclass).validate_python({'x': '123'}, strict=True)
except ValidationError as exc:
    print(exc)
    """
    1 validation error for MyDataclass
      Input should be an instance of MyDataclass [type=dataclass_exact_type, input_value={'x': '123'}, input_type=dict]
    """

这也适用于 TypeAdapter.validate_json 和 BaseModel.model_validate_json 方法：

import json
from typing import List
from uuid import UUID

from pydantic import BaseModel, TypeAdapter, ValidationError

try:
    TypeAdapter(List[int]).validate_json('["1", 2, "3"]', strict=True)
except ValidationError as exc:
    print(exc)
    """
    2 validation errors for list[int]
    0
      Input should be a valid integer [type=int_type, input_value='1', input_type=str]
    2
      Input should be a valid integer [type=int_type, input_value='3', input_type=str]
    """


class Model(BaseModel):
    x: int
    y: UUID


data = {'x': '1', 'y': '12345678-1234-1234-1234-123456789012'}
try:
    Model.model_validate(data, strict=True)
except ValidationError as exc:
    # Neither x nor y are valid in strict mode from python:
    print(exc)
    """
    2 validation errors for Model
    x
      Input should be a valid integer [type=int_type, input_value='1', input_type=str]
    y
      Input should be an instance of UUID [type=is_instance_of, input_value='12345678-1234-1234-1234-123456789012', input_type=str]
    """

json_data = json.dumps(data)
try:
    Model.model_validate_json(json_data, strict=True)
except ValidationError as exc:
    # From JSON, x is still not valid in strict mode, but y is:
    print(exc)
    """
    1 validation error for Model
    x
      Input should be a valid integer [type=int_type, input_value='1', input_type=str]
    """

严格模式与 `Field`¶

对于模型上的各个字段，可以在该字段上设置 strict=True 。这将导致即使在不使用 strict=True 调用验证方法时，也会对该字段使用严格模式验证。

仅受 strict=True 设置影响的字段将受到影响：

from pydantic import BaseModel, Field, ValidationError


class User(BaseModel):
    name: str
    age: int
    n_pets: int


user = User(name='John', age='42', n_pets='1')
print(user)
#> name='John' age=42 n_pets=1


class AnotherUser(BaseModel):
    name: str
    age: int = Field(strict=True)
    n_pets: int


try:
    anotheruser = AnotherUser(name='John', age='42', n_pets='1')
except ValidationError as e:
    print(e)
    """
    1 validation error for AnotherUser
    age
      Input should be a valid integer [type=int_type, input_value='42', input_type=str]
    """

请注意，将字段设置为严格也会影响实例化模型类时执行的验证：

from pydantic import BaseModel, Field, ValidationError


class Model(BaseModel):
    x: int = Field(strict=True)
    y: int = Field(strict=False)


try:
    Model(x='1', y='2')
except ValidationError as exc:
    print(exc)
    """
    1 validation error for Model
    x
      Input should be a valid integer [type=int_type, input_value='1', input_type=str]
    """

使用 `Field` 作为注释¶

请注意，如果需要， Field(strict=True) （或其他任何关键字参数）可以用作注释，例如在使用 TypedDict 时：

from typing_extensions import Annotated, TypedDict

from pydantic import Field, TypeAdapter, ValidationError


class MyDict(TypedDict):
    x: Annotated[int, Field(strict=True)]


try:
    TypeAdapter(MyDict).validate_python({'x': '1'})
except ValidationError as exc:
    print(exc)
    """
    1 validation error for typed-dict
    x
      Input should be a valid integer [type=int_type, input_value='1', input_type=str]
    """

Strict mode with `Annotated[..., Strict()]`¶

严格模式与 `Annotated[..., Strict()]`¶

API 文档

pydantic.types.Strict

Pydantic 还提供了 Strict 类，该类旨在与 [ typing.Annotated ][] 类一起用作元数据；此注释表明应在严格模式下验证已注释的字段：

from typing_extensions import Annotated

from pydantic import BaseModel, Strict, ValidationError


class User(BaseModel):
    name: str
    age: int
    is_active: Annotated[bool, Strict()]


User(name='David', age=33, is_active=True)
try:
    User(name='David', age=33, is_active='True')
except ValidationError as exc:
    print(exc)
    """
    1 validation error for User
    is_active
      Input should be a valid boolean [type=bool_type, input_value='True', input_type=str]
    """

这实际上是实现 Pydantic 提供的一些严格开箱即用类型的方法，例如 StrictInt 。

严格模式与 `ConfigDict`¶

`BaseModel`¶

如果要为复杂输入类型的所有字段启用严格模式，可以在 model_config 中使用 ConfigDict(strict=True) ：

from pydantic import BaseModel, ConfigDict, ValidationError


class User(BaseModel):
    model_config = ConfigDict(strict=True)

    name: str
    age: int
    is_active: bool


try:
    User(name='David', age='33', is_active='yes')
except ValidationError as exc:
    print(exc)
    """
    2 validation errors for User
    age
      Input should be a valid integer [type=int_type, input_value='33', input_type=str]
    is_active
      Input should be a valid boolean [type=bool_type, input_value='yes', input_type=str]
    """

注意，当通过模型的 model_config 使用 strict=True 时，你仍然可以通过在各个字段上设置 strict=False 来覆盖各个字段的严格性：

```py
from pydantic import BaseModel, ConfigDict, Field


class User(BaseModel):
    model_config = ConfigDict(strict=True)

    name: str
    age: int = Field(strict=False)
```

请注意，严格模式不会递归应用于嵌套的模型字段：

from pydantic import BaseModel, ConfigDict, ValidationError


class Inner(BaseModel):
    y: int


class Outer(BaseModel):
    model_config = ConfigDict(strict=True)

    x: int
    inner: Inner


print(Outer(x=1, inner=Inner(y='2')))
#> x=1 inner=Inner(y=2)

try:
    Outer(x='1', inner=Inner(y='2'))
except ValidationError as exc:
    print(exc)
    """
    1 validation error for Outer
    x
      Input should be a valid integer [type=int_type, input_value='1', input_type=str]
    """

（这对于 dataclasses 和 TypedDict 也是如此。）

如果这是不希望的，你应该确保所有涉及的类型都启用了严格模式。例如，可以通过使用带有 model_config = ConfigDict(strict=True) 的共享基类来为模型类执行此操作：

from pydantic import BaseModel, ConfigDict, ValidationError


class MyBaseModel(BaseModel):
    model_config = ConfigDict(strict=True)


class Inner(MyBaseModel):
    y: int


class Outer(MyBaseModel):
    x: int
    inner: Inner


try:
    Outer.model_validate({'x': 1, 'inner': {'y': '2'}})
except ValidationError as exc:
    print(exc)
    """
    1 validation error for Outer
    inner.y
      Input should be a valid integer [type=int_type, input_value='2', input_type=str]
    """

数据类和 `TypedDict`¶

Pydantic 数据类的行为类似于上面示例中的 BaseModel ，只是您应该使用 config 关键字参数而不是 model_config 来修饰 @pydantic.dataclasses.dataclass 。

当可能时，你可以通过使用 pydantic.types.Strict 注解标注字段来为原始数据类或 TypedDict 子类实现嵌套严格模式。

然而，如果这是不可能的（例如，在与第三方类型一起工作时），你可以通过在类型上设置 __pydantic_config__ 属性来设置 Pydantic 应该用于该类型的配置：

from typing_extensions import TypedDict

from pydantic import ConfigDict, TypeAdapter, ValidationError


class Inner(TypedDict):
    y: int


Inner.__pydantic_config__ = ConfigDict(strict=True)


class Outer(TypedDict):
    x: int
    inner: Inner


adapter = TypeAdapter(Outer)
print(adapter.validate_python({'x': '1', 'inner': {'y': 2}}))
#> {'x': 1, 'inner': {'y': 2}}


try:
    adapter.validate_python({'x': '1', 'inner': {'y': '2'}})
except ValidationError as exc:
    print(exc)
    """
    1 validation error for typed-dict
    inner.y
      Input should be a valid integer [type=int_type, input_value='2', input_type=str]
    """

`TypeAdapter`¶

你还可以通过在 TypeAdapter 类的 config 关键字参数中使用严格模式来获得严格模式：

from pydantic import ConfigDict, TypeAdapter, ValidationError

adapter = TypeAdapter(bool, config=ConfigDict(strict=True))

try:
    adapter.validate_python('yes')
except ValidationError as exc:
    print(exc)
    """
    1 validation error for bool
      Input should be a valid boolean [type=bool_type, input_value='yes', input_type=str]
    """

`@validate_call`¶

严格模式也可以与 @validate_call 装饰器一起使用，通过传递 config 关键字参数：

from pydantic import ConfigDict, ValidationError, validate_call


@validate_call(config=ConfigDict(strict=True))
def foo(x: int) -> int:
    return x


try:
    foo('1')
except ValidationError as exc:
    print(exc)
    """
    1 validation error for foo
    0
      Input should be a valid integer [type=int_type, input_value='1', input_type=str]
    """

本文总阅读量次

严格模式

严格模式下的类型强制转换¶

严格模式在方法调用中¶

严格模式与 Field¶

使用 Field 作为注释¶

Strict mode with Annotated[..., Strict()]¶

严格模式与 Annotated[..., Strict()]¶

严格模式与 ConfigDict¶

BaseModel¶

数据类和 TypedDict¶

TypeAdapter¶

@validate_call¶