配置

Pydantic 的行为可以通过各种配置值来控制，这些值记录在 ConfigDict 类中。本页描述了如何为 Pydantic 支持的类型指定配置。

在 Pydantic 模型上配置¶

在 Pydantic 模型上，可以通过两种方式指定配置：

使用 model_config 类属性

from pydantic import BaseModel, ConfigDict, ValidationError


class Model(BaseModel):
    model_config = ConfigDict(str_max_length=5)  # (1)!

    v: str


try:
    m = Model(v='abcdef')
except ValidationError as e:
    print(e)
    """
    1 validation error for Model
    v
      String should have at most 5 characters [type=string_too_long, input_value='abcdef', input_type=str]
    """

也可以使用普通字典（例如 {'str_max_length': 5}）。

注意

在 Pydantic V1 中，使用的是 Config 类。这仍然受支持，但已弃用。

使用类参数

from pydantic import BaseModel


class Model(BaseModel, frozen=True):
    a: str

与 model_config 类属性不同，静态类型检查器会识别类参数。对于 frozen，任何实例的修改都将被标记为类型检查错误。

在 Pydantic 数据类上配置¶

Pydantic 数据类也支持配置（详情请阅读专门章节）。

from pydantic import ConfigDict, ValidationError
from pydantic.dataclasses import dataclass


@dataclass(config=ConfigDict(str_max_length=10, validate_assignment=True))
class User:
    name: str


user = User(name='John Doe')
try:
    user.name = 'x' * 20
except ValidationError as e:
    print(e)
    """
    1 validation error for User
    name
      String should have at most 10 characters [type=string_too_long, input_value='xxxxxxxxxxxxxxxxxxxx', input_type=str]
    """

在 `TypeAdapter` 上配置¶

类型适配器（使用 TypeAdapter 类）通过提供 config 参数来支持配置。

from pydantic import ConfigDict, TypeAdapter

ta = TypeAdapter(list[str], config=ConfigDict(coerce_numbers_to_str=True))

print(ta.validate_python([1, 2]))
#> ['1', '2']

如果类型适配器直接包装一个支持配置的类型，则无法提供配置，并且在这种情况下会引发使用错误。配置传播规则也同样适用。

在其他支持的类型上配置¶

如果您正在使用标准库数据类或 TypedDict 类，可以通过两种方式设置配置：

使用 __pydantic_config__ 类属性

from dataclasses import dataclass

from pydantic import ConfigDict


@dataclass
class User:
    __pydantic_config__ = ConfigDict(strict=True)

    id: int
    name: str = 'John Doe'

使用 @with_config 装饰器（这可以避免 TypedDict 的静态类型检查错误）

from typing_extensions import TypedDict

from pydantic import ConfigDict, with_config


@with_config(ConfigDict(str_to_lower=True))
class Model(TypedDict):
    x: str

在 `@validate_call` 装饰器上配置¶

@validate_call 也支持设置自定义配置。更多详情请参见专门章节。

全局更改行为¶

如果您希望全局更改 Pydantic 的行为，您可以创建一个具有自定义配置的自定义父类，因为配置是可继承的：

from pydantic import BaseModel, ConfigDict


class Parent(BaseModel):
    model_config = ConfigDict(extra='allow')


class Model(Parent):
    x: str


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

如果您为子类提供配置，它将与父配置进行合并：

from pydantic import BaseModel, ConfigDict


class Parent(BaseModel):
    model_config = ConfigDict(extra='allow', str_to_lower=False)


class Model(Parent):
    model_config = ConfigDict(str_to_lower=True)

    x: str


m = Model(x='FOO', y='bar')
print(m.model_dump())
#> {'x': 'foo', 'y': 'bar'}
print(Model.model_config)
#> {'extra': 'allow', 'str_to_lower': True}

警告

如果您的模型继承自多个基类，Pydantic 目前不遵循方法解析顺序（MRO）。更多详情，请参阅此问题。

配置传播¶

当使用支持配置的类型作为字段注解时，配置可能不会传播：

对于 Pydantic 模型和数据类，配置将不会传播，每个模型都有其自己的“配置边界”

from pydantic import BaseModel, ConfigDict


class User(BaseModel):
    name: str


class Parent(BaseModel):
    user: User

    model_config = ConfigDict(str_to_lower=True)


print(Parent(user={'name': 'JOHN'}))
#> user=User(name='JOHN')

对于标准库类型（数据类和类型化字典），配置将会传播，除非该类型设置了自己的配置

from dataclasses import dataclass

from pydantic import BaseModel, ConfigDict, with_config


@dataclass
class UserWithoutConfig:
    name: str


@dataclass
@with_config(str_to_lower=False)
class UserWithConfig:
    name: str


class Parent(BaseModel):
    user_1: UserWithoutConfig
    user_2: UserWithConfig

    model_config = ConfigDict(str_to_lower=True)


print(Parent(user_1={'name': 'JOHN'}, user_2={'name': 'JOHN'}))
#> user_1=UserWithoutConfig(name='john') user_2=UserWithConfig(name='JOHN')

配置