from typing import Annotated
from pydantic import AfterValidator, BaseModel, ValidationError
def is_even(value: int) -> int:
    if value % 2 == 1:
        raise ValueError(f'{value} is not an even number')
    return value  # (1)!
class Model(BaseModel):
    number: Annotated[int, AfterValidator(is_even)]
try:
    Model(number=1)
except ValidationError as err:
    print(err)
    1 validation error for Model
    number
      Value error, 1 is not an even number [type=value_error, input_value=1, input_type=int]
请注意，返回已验证的值很重要。
这是一个执行验证检查并返回未更改值的验证器示例，这次使用field_validator()装饰器。
from pydantic import BaseModel, ValidationError, field_validator
class Model(BaseModel):
    number: int
    @field_validator('number', mode='after')  # (1)!
    @classmethod
    def is_even(cls, value: int) -> int:
        if value % 2 == 1:
            raise ValueError(f'{value} is not an even number')
        return value  # (2)!
try:
    Model(number=1)
except ValidationError as err:
    print(err)
    1 validation error for Model
    number
      Value error, 1 is not an even number [type=value_error, input_value=1, input_type=int]
'after'是装饰器的默认模式，可以省略。
请注意，返回已验证的值很重要。
class Model(BaseModel):
    number: Annotated[int, AfterValidator(double_number)]
print(Model(number=2))
#> number=4
from pydantic import BaseModel, field_validator
class Model(BaseModel):
    number: int
    @field_validator('number', mode='after')  # (1)!
    @classmethod
    def double_number(cls, value: int) -> int:
        return value * 2
print(Model(number=2))
#> number=4
'after'是装饰器的默认模式，可以省略。
**_前_验证器**：在 Pydantic 的内部解析和验证（例如将 str 强制转换为 int）之前运行。它们比_后_验证器更灵活，但它们也必须处理原始输入，理论上它可以是任何任意对象。如果您在验证器函数中稍后引发验证错误，则还应避免直接改变值，因为如果使用联合类型，改变后的值可能会传递给其他验证器。
此可调用对象返回的值将由 Pydantic 根据提供的类型注解进行验证。
注解模式装饰器
from typing import Annotated, Any
from pydantic import BaseModel, BeforeValidator, ValidationError
def ensure_list(value: Any) -> Any:  # (1)!
    if not isinstance(value, list):  # (2)!
        return [value]
    else:
        return value
class Model(BaseModel):
    numbers: Annotated[list[int], BeforeValidator(ensure_list)]
print(Model(numbers=2))
#> numbers=[2]
try:
    Model(numbers='str')
except ValidationError as err:
    print(err)  # (3)!
    1 validation error for Model
    numbers.0
      Input should be a valid integer, unable to parse string as an integer [type=int_parsing, input_value='str', input_type=str]
请注意将Any用作value的类型提示。_前_验证器接受原始输入，它可以是任何类型。
请注意，您可能希望检查其他序列类型（例如元组），这些类型通常会成功验证为list类型。_前_验证器为您提供了更大的灵活性，但您必须考虑所有可能的情况。
Pydantic 仍然对 int 类型执行验证，无论我们的 ensure_list 验证器是否对原始输入类型进行了操作。
from typing import Any
from pydantic import BaseModel, ValidationError, field_validator
class Model(BaseModel):
    numbers: list[int]
    @field_validator('numbers', mode='before')
    @classmethod
    def ensure_list(cls, value: Any) -> Any:  # (1)!
        if not isinstance(value, list):  # (2)!
            return [value]
        else:
            return value
print(Model(numbers=2))
#> numbers=[2]
try:
    Model(numbers='str')
except ValidationError as err:
    print(err)  # (3)!
    1 validation error for Model
    numbers.0
      Input should be a valid integer, unable to parse string as an integer [type=int_parsing, input_value='str', input_type=str]
请注意将Any用作value的类型提示。_前_验证器接受原始输入，它可以是任何类型。
请注意，您可能希望检查其他序列类型（例如元组），这些类型通常会成功验证为list类型。_前_验证器为您提供了更大的灵活性，但您必须考虑所有可能的情况。
Pydantic 仍然对 int 类型执行验证，无论我们的 ensure_list 验证器是否对原始输入类型进行了操作。
**_简单_验证器**：与_前_验证器类似，但它们在返回后会**立即终止验证**，因此不会调用其他验证器，并且 Pydantic 不会对其内部验证进行任何字段类型验证。
注解模式装饰器
from typing import Annotated, Any
from pydantic import BaseModel, PlainValidator
def val_number(value: Any) -> Any:
    if isinstance(value, int):
        return value * 2
    else:
        return value
class 




    
Model(BaseModel):
    number: Annotated[int, PlainValidator(val_number)]
print(Model(number=4))
#> number=8
print(Model(number='invalid'))  # (1)!
#> number='invalid'
尽管 'invalid' 不应针对 int 类型进行验证，但 Pydantic 接受该输入。
from typing import Any
from pydantic import BaseModel, field_validator
class Model(BaseModel):
    number: int
    @field_validator('number', mode='plain')
    @classmethod
    def val_number(cls, value: Any) -> Any:
        if isinstance(value, int):
            return value * 2
        else:
            return value
print(Model(number=4))
#> number=8
print(Model(number='invalid'))  # (1)!
#> number='invalid'
尽管 'invalid' 不应针对 int 类型进行验证，但 Pydantic 接受该输入。
**_包装_验证器**：是最灵活的。您可以在 Pydantic 和其他验证器处理输入之前或之后运行代码，或者您可以立即终止验证，无论是通过提前返回值还是通过引发错误。
此类验证器必须定义一个**强制性**的额外_处理程序_参数：一个可调用对象，它将要验证的值作为参数。在内部，此处理程序将验证值委托给 Pydantic。您可以随意将对处理程序的调用包装在try..except块中，或者根本不调用它。
注解模式装饰器
from typing import Any
from typing import Annotated
from pydantic import BaseModel, Field, ValidationError, ValidatorFunctionWrapHandler, WrapValidator
def truncate(value: Any, handler: ValidatorFunctionWrapHandler) -> str:
    try:
        return handler(value)
    except ValidationError as err:
        if err.errors()[0]['type'] == 'string_too_long':
            return handler(value[:5])
        else:
            raise
class Model(BaseModel):
    my_string: Annotated[str, Field(max_length=5), WrapValidator(truncate)]
print(Model(my_string='abcde'))
#> my_string='abcde'
print(Model(my_string='abcdef'))
#> my_string='abcde'
from typing import Any
from typing import Annotated
from pydantic import BaseModel, Field, ValidationError, ValidatorFunctionWrapHandler, field_validator
class Model(BaseModel):
    my_string: Annotated[str, Field(max_length=5)]
    @field_validator('my_string', mode='wrap')
    @classmethod
    def truncate(cls, value: Any, handler: ValidatorFunctionWrapHandler) -> str:
        try:
            return handler(value)
        except ValidationError as err:
            if err.errors()[0]['type'] == 'string_too_long':
                return handler(value[:5])
            else:
                raise
print(Model(my_string='abcde'))
#> my_string='abcde'
print(Model(my_string='abcdef'))
#> my_string='abcde'
def is_even(value: int) -> int:
    if value % 2 == 1:
        raise ValueError(f'{value} is not an even number')
    return value
EvenNumber = Annotated[int, AfterValidator(is_even)]
class Model1(BaseModel):
    my_number: EvenNumber
class Model2(BaseModel):
    other_number: Annotated[EvenNumber, AfterValidator(lambda v: v + 2)]
class Model3(BaseModel):
    list_of_even_numbers: list[EvenNumber]  # (1)!
如注解模式文档中所述，我们还可以利用注解的特定部分的验证器（在这种情况下，验证应用于列表项，而不是整个列表）。
通过查看字段注解，也可以更容易地理解哪些验证器应用于某个类型。
使用装饰器模式¶
使用field_validator()装饰器的主要好处之一是将函数应用于多个字段
from pydantic import BaseModel, field_validator
class Model(BaseModel):
    f1: str
    f2: str
    @field_validator('f1', 'f2', mode='before')
    @classmethod
    def capitalize(cls, value: str) -> str:
        return value.capitalize()
以下是关于装饰器用法的几个额外说明
如果您希望验证器应用于所有字段（包括子类中定义的字段），您可以传递'*'作为字段名称参数。
默认情况下，装饰器将确保提供的字段名在模型上已定义。如果您想在类创建期间禁用此检查，可以通过将False传递给check_fields参数来完成。当字段验证器定义在基类上，并且预期字段存在于子类中时，这很有用。
模型验证器¶
API 文档
pydantic.functional_validators.model_validator

还可以使用model_validator()装饰器对整个模型的数据执行验证。
可以使用**三种**不同类型的模型验证器
**_后_验证器**：在整个模型验证之后运行。因此，它们被定义为_实例_方法，可以看作是初始化后的钩子。重要提示：应返回已验证的实例。
from typing_extensions import Self
from pydantic import BaseModel, model_validator
class UserModel(BaseModel):
    username: str
    password: str
    password_repeat: str
    @model_validator(mode='after')
    def check_passwords_match(self) -> Self:
        if self.password != self.password_repeat:
            raise ValueError('Passwords do not match')
        return self
**_前_验证器**：在模型实例化之前运行。它们比_后_验证器更灵活，但它们也必须处理原始输入，理论上它可以是任何任意对象。如果您在验证器函数中稍后引发验证错误，则还应避免直接改变值，因为如果使用联合类型，改变后的值可能会传递给其他验证器。
from typing import Any
from pydantic import BaseModel, model_validator
class UserModel(BaseModel):
    username




    
: str
    @model_validator(mode='before')
    @classmethod
    def check_card_number_not_present(cls, data: Any) -> Any:  # (1)!
        if isinstance(data, dict):  # (2)!
            if 'card_number' in data:
                raise ValueError("'card_number' should not be included")
        return data
请注意将Any用作data的类型提示。_前_验证器接受原始输入，它可以是任何类型。
大多数情况下，输入数据将是一个字典（例如，当调用UserModel(username='...')时）。但是，并非总是如此。例如，如果设置了from_attributes配置值，您可能会收到一个任意的类实例作为data参数。
**_包装_验证器**：是最灵活的。您可以在 Pydantic 和其他验证器处理输入数据之前或之后运行代码，或者您可以立即终止验证，无论是通过提前返回数据还是通过引发错误。
import logging
from typing import Any
from typing_extensions import Self
from pydantic import BaseModel, ModelWrapValidatorHandler, ValidationError, model_validator
class UserModel(BaseModel):
    username: str
    @model_validator(mode='wrap')
    @classmethod
    def log_failed_validation(cls, data: Any, handler: ModelWrapValidatorHandler[Self]) -> Self:
        try:
            return handler(data)
        except ValidationError:
            logging.error('Model %s failed to validate with data %s', cls, data)
            raise
ValueError：这是验证器中最常引发的异常。
AssertionError：使用assert语句也有效，但请注意，当 Python 使用-O优化标志运行时，这些语句会被跳过。
PydanticCustomError：稍微冗长，但提供了额外的灵活性
from pydantic_core import PydanticCustomError
from pydantic import BaseModel, ValidationError, field_validator
class Model(BaseModel):
    x: int
    @field_validator('x', mode='after')
    @classmethod
    def validate_x(cls, v: int) -> int:
        if v % 42 == 0:
            raise PydanticCustomError(
                'the_answer_error',
                '{number} is the answer!',
                {'number': v},
        return v
try:
    Model(x=42 * 2)
except ValidationError as e:
    print(e)
    1 validation error for Model
      84 is the answer! [type=the_answer_error, input_value=84, input_type=int]
验证信息¶
字段和模型验证器可调用对象（在所有模式下）都可以选择接受一个额外的ValidationInfo参数，提供有用的额外信息，例如
已验证数据
用户定义上下文
当前验证模式：'python'或'json'（参见mode属性）
当前字段名，如果使用字段验证器（参见field_name属性）。
验证数据¶
对于字段验证器，可以使用data属性访问已验证的数据。这里有一个示例，可以作为_后_模型验证器示例的替代方案
from pydantic import BaseModel, ValidationInfo, field_validator
class UserModel(BaseModel):
    password: str
    password_repeat: str
    username: str
    @field_validator('password_repeat', mode='after')
    @classmethod
    def check_passwords_match(cls, value: str, info: ValidationInfo) -> str:
        if value != info.data['password']:
            raise ValueError('Passwords do not match')
        return value
由于验证是按照字段定义的顺序执行的，您必须确保您没有访问尚未验证的字段。例如，在上面的代码中，username的验证值尚不可用，因为它是在password_repeat_之后_定义的。
data属性对于模型验证器为None。
验证上下文¶
您可以将上下文对象传递给验证方法，可以使用context属性在验证器函数内部访问该上下文对象。
from pydantic import BaseModel, ValidationInfo, field_validator
class Model(BaseModel):
    text: str
    @field_validator('text', mode='after')
    @classmethod
    def remove_stopwords(cls, v: str, info: ValidationInfo) -> str:
        if isinstance(info.context, dict):
            stopwords = info.context.get('stopwords', set())
            v = ' '.join(w for w in v.split() if w.lower() not in stopwords)
        return v
data = {'text': 'This is an example document'}
print(Model.model_validate(data))  # no context
#> text='This is an example document'
print(Model.model_validate(data, context={'stopwords': ['this', 'is', 'an']}))
#> text='example document'
同样，您可以将上下文用于序列化。
直接实例化模型时提供上下文
目前无法在直接实例化模型时（即调用Model(...)时）提供上下文。您可以通过使用ContextVar和自定义__init__方法来解决此问题。
from __future__ import annotations
from collections.abc import Generator
from contextlib import contextmanager
from contextvars import ContextVar
from typing import Any
from pydantic import BaseModel, ValidationInfo, field_validator
_init_context_var = ContextVar('_init_context_var', default=None)
@contextmanager
def init_context(value: dict[str, Any]) -> Generator[None]:
    token = _init_context_var.set(value)
    try:
        yield
    finally:
        _init_context_var.reset(token)
class Model(BaseModel):
    my_number: int




    

    def __init__(self, /, **data: Any) -> None:
        self.__pydantic_validator__.validate_python(
            data,
            self_instance=self,
            context=_init_context_var.get(),
    @field_validator('my_number')
    @classmethod
    def multiply_with_context(cls, value: int, info: ValidationInfo) -> int:
        if isinstance(info.context, dict):
            multiplier = info.context.get('multiplier', 1)
            value = value * multiplier
        return value
print(Model(my_number=2))
#> my_number=2
with init_context({'multiplier': 3}):
    print(Model(my_number=2))
    #> my_number=6
print(Model(my_number=2))
#> my_number=2
验证器的顺序¶
当使用注解模式时，验证器的应用顺序定义如下：_前_和_包装_验证器从右到左运行，然后_后_验证器从左到右运行
from pydantic import AfterValidator, BaseModel, BeforeValidator, WrapValidator
class Model(BaseModel):
    name: Annotated[
        str,
        AfterValidator(runs_3rd),
        AfterValidator(runs_4th),
        BeforeValidator(runs_2nd),
        WrapValidator(runs_1st),
在内部，使用装饰器定义的验证器会转换为其对应的注解形式，并作为字段现有元数据之后的最后一个添加。这意味着相同的排序逻辑适用。
特殊类型¶
Pydantic 提供了一些可用于自定义验证的特殊实用程序。
InstanceOf可用于验证值是否是给定类的实例。
from pydantic import BaseModel, InstanceOf, ValidationError
class Fruit:
    def __repr__(self):
        return self.__class__.__name__
class Banana(Fruit): ...
class Apple(Fruit): ...
class Basket(BaseModel):
    fruits: list[InstanceOf[Fruit]]
print(Basket(fruits=[Banana(), Apple()]))
#> fruits=[Banana, Apple]
try:
    Basket(fruits=[Banana(), 'Apple'])
except ValidationError as e:
    print(e)
    1 validation error for Basket
    fruits.1
      Input should be an instance of Fruit [type=is_instance_of, input_value='Apple', input_type=str]
SkipValidation可用于跳过字段上的验证。
from pydantic import BaseModel, SkipValidation
class Model(BaseModel):
    names: list[SkipValidation[str]]
m = Model(names=['foo', 'bar'])
print(m)
#> names=['foo', 'bar']
m = Model(names=['foo', 123])  # (1)!
print(m)
#> names=['foo', 123]
请注意，跳过了第二个项目的验证。如果它的类型不正确，则在序列化期间会发出警告。
ValidateAs可用于从 Pydantic 原生支持的类型中验证自定义类型。当使用具有多个字段的自定义类型时，这特别有用。
from typing import Annotated
from pydantic import BaseModel, TypeAdapter, ValidateAs
class MyCls:
    def __init__(self, a: int) -> None:
        self.a = a
    def __repr__(self) -> str:
        return f"MyCls(a={self.a})"
class ValModel(BaseModel):
    a: int
ta = TypeAdapter(
    Annotated[MyCls, ValidateAs(ValModel, lambda v: MyCls(a=v.a))]
print(ta.validate_python({'a': 1}))
#> MyCls(a=1)
PydanticUseDefault可用于通知 Pydantic 应使用默认值。
from typing import Annotated, Any
from pydantic_core import PydanticUseDefault
from pydantic import BaseModel, BeforeValidator
def default_if_none(value: Any) -> Any:
    if value is None:
        raise PydanticUseDefault()
    return value
class Model(BaseModel):
    name: Annotated[str, BeforeValidator(default_if_none)] = 'default_name'
print(Model(name=None))
#> name='default_name'
JSON Schema 和字段验证器¶
当使用_前_、_简单_或_包装_字段验证器时，接受的输入类型可能与字段注解不同。
考虑以下示例
from typing import Any
from pydantic import BaseModel, field_validator
class Model(BaseModel):
    value: str
    @field_validator('value', mode='before')
    @classmethod
    def cast_ints(cls, value: Any) -> Any:
        if isinstance(value, int):
            return str(value)
        else:
            return value
print(Model(value='a'))
#> value='a'
print(Model(value=1))
#> value='1'
虽然value的类型提示是str，但cast_ints验证器也允许整数。要指定正确的输入类型，可以提供json_schema_input_type参数
from typing import Any, Union
from pydantic import BaseModel, field_validator
class Model(BaseModel):
    value: str
    @field_validator(
        'value', mode='before', json_schema_input_type=Union[int, str]
    @classmethod
    def cast_ints(cls, value: Any) -> Any:
        if isinstance(value, int):
            return str(value)
        else:
            return value
print(Model.model_json_schema()['properties']['value'])
#> {'anyOf': [{'type': 'integer'}, {'type': 'string'}], 'title': 'Value'}
为了方便起见，如果未提供参数，Pydantic 将使用字段类型（除非您使用_简单_验证器，在这种情况下，json_schema_input_type默认为Any，因为字段类型被完全丢弃）。