pydantic.functional_validators

This module contains related classes and functions for validation.

ModelAfterValidator module-attribute

ModelAfterValidator = Callable[
    [_ModelType, _core_schema.ValidationInfo], _ModelType
]

A @model_validator decorated function signature. This is used when mode='after'.

ModelAfterValidatorWithoutInfo module-attribute

ModelAfterValidatorWithoutInfo = Callable[
    [_ModelType], _ModelType
]

A @model_validator decorated function signature. This is used when mode='after' and the function does not have info argument.

AfterValidator dataclass

Usage Documentation

Annotated Validators

A metadata class that indicates that a validation should be applied after the inner validation logic.

Attributes:

Name	Type	Description
func	core_schema.NoInfoValidatorFunction | core_schema.GeneralValidatorFunction	The validator function.

Example

from typing import Annotated

from pydantic import BaseModel, AfterValidator, ValidationError


MyInt = Annotated[int, AfterValidator(lambda v: v + 1)]

class Model(BaseModel):
    a: MyInt

print(Model(a=1).a)
# > 2

try:
    Model(a='a')
except ValidationError as e:
    print(e.json(indent=2))
"""
[
    {
        "type": "int_parsing",
        "loc": [
            "a"
        ],
        "msg": "Input should be a valid integer, unable to parse string as an integer",
        "input": "a",
        "url": "https://errors.pydantic.dev/0.38.0/v/int_parsing"
    }
]
"""

BeforeValidator dataclass

Usage Documentation

Annotated Validators

A metadata class that indicates that a validation should be applied before the inner validation logic.

Attributes:

Name	Type	Description
func	core_schema.NoInfoValidatorFunction | core_schema.GeneralValidatorFunction	The validator function.

Example

from typing_extensions import Annotated

from pydantic import BaseModel, BeforeValidator

MyInt = Annotated[int, BeforeValidator(lambda v: v + 1)]

class Model(BaseModel):
    a: MyInt

print(Model(a=1).a)
#> 2

try:
    Model(a='a')
except TypeError as e:
    print(e)
    #> can only concatenate str (not "int") to str

InstanceOf dataclass

Generic type for annotating a type that is an instance of a given class.

Example

from pydantic import BaseModel, InstanceOf

class Foo:
    ...

class Bar(BaseModel):
    foo: InstanceOf[Foo]

Bar(foo=Foo())
try:
    Bar(foo=42)
except ValidationError as e:
    print(e)
    """
    [
    │   {
    │   │   'type': 'is_instance_of',
    │   │   'loc': ('foo',),
    │   │   'msg': 'Input should be an instance of Foo',
    │   │   'input': 42,
    │   │   'ctx': {'class': 'Foo'},
    │   │   'url': 'https://errors.pydantic.dev/0.38.0/v/is_instance_of'
    │   }
    ]
    """

ModelBeforeValidator

Bases: Protocol

A @model_validator decorated function signature. This is used when mode='before'.

ModelBeforeValidatorWithoutInfo

Bases: Protocol

A @model_validator decorated function signature. This is used when mode='before' and the function does not have info argument.

ModelWrapValidator

Bases: Protocol

A @model_validator decorated function signature. This is used when mode='wrap'.

ModelWrapValidatorHandler

Bases: _core_schema.ValidatorFunctionWrapHandler, Protocol[_ModelTypeCo]

@model_validator decorated function handler argument type. This is used when mode='wrap'.

ModelWrapValidatorWithoutInfo

Bases: Protocol

A @model_validator decorated function signature. This is used when mode='wrap' and the function does not have info argument.

PlainValidator dataclass

Usage Documentation

Annotated Validators

A metadata class that indicates that a validation should be applied instead of the inner validation logic.

Attributes:

Name	Type	Description
func	core_schema.NoInfoValidatorFunction | core_schema.GeneralValidatorFunction	The validator function.

Example

from typing_extensions import Annotated

from pydantic import BaseModel, PlainValidator

MyInt = Annotated[int, PlainValidator(lambda v: int(v) + 1)]

class Model(BaseModel):
    a: MyInt

print(Model(a='1').a)
#> 2

SkipValidation dataclass

If this is applied as an annotation (e.g., via x: Annotated[int, SkipValidation]), validation will be skipped. You can also use SkipValidation[int] as a shorthand for Annotated[int, SkipValidation].

This can be useful if you want to use a type annotation for documentation/IDE/type-checking purposes, and know that it is safe to skip validation for one or more of the fields.

Because this converts the validation schema to any_schema, subsequent annotation-applied transformations may not have the expected effects. Therefore, when used, this annotation should generally be the final annotation applied to a type.

WrapValidator dataclass

Usage Documentation

Annotated Validators

A metadata class that indicates that a validation should be applied around the inner validation logic.

Attributes:

Name	Type	Description
func	core_schema.GeneralWrapValidatorFunction | core_schema.FieldWrapValidatorFunction	The validator function.

from datetime import datetime

from typing_extensions import Annotated

from pydantic import BaseModel, ValidationError, WrapValidator

def validate_timestamp(v, handler):
    if v == 'now':
        # we don't want to bother with further validation, just return the new value
        return datetime.now()
    try:
        return handler(v)
    except ValidationError:
        # validation failed, in this case we want to return a default value
        return datetime(2000, 1, 1)

MyTimestamp = Annotated[datetime, WrapValidator(validate_timestamp)]

class Model(BaseModel):
    a: MyTimestamp

print(Model(a='now').a)
#> 2032-01-02 03:04:05.000006
print(Model(a='invalid').a)
#> 2000-01-01 00:00:00

field_validator

field_validator(
    __field, *fields, mode="after", check_fields=None
)

Usage Documentation

Field validators

Decorate methods on the class indicating that they should be used to validate fields.

Parameters:

Name	Type	Description	Default
__field	str	The first field the field_validator should be called on; this is separate from fields to ensure an error is raised if you don't pass at least one.	required
*fields	str	Additional field(s) the field_validator should be called on.	()
mode	FieldValidatorModes	Specifies whether to validate the fields before or after validation.	'after'
check_fields	bool | None	Whether to check that the fields actually exist on the model.	None

Returns:

Type	Description
Callable[[Any], Any]	A decorator that can be used to decorate a function to be used as a field_validator.

Raises:

Type	Description
PydanticUserError	If @field_validator is used bare (with no fields). If the args passed to @field_validator as fields are not strings. If @field_validator applied to instance methods.

Source code in pydantic/functional_validators.py

def field_validator(
    __field: str,
    *fields: str,
    mode: FieldValidatorModes = 'after',
    check_fields: bool | None = None,
) -> Callable[[Any], Any]:
    """Usage docs: https://docs.pydantic.dev/dev-v2/usage/validators/#field-validators

    Decorate methods on the class indicating that they should be used to validate fields.

    Args:
        __field: The first field the `field_validator` should be called on; this is separate
            from `fields` to ensure an error is raised if you don't pass at least one.
        *fields: Additional field(s) the `field_validator` should be called on.
        mode: Specifies whether to validate the fields before or after validation.
        check_fields: Whether to check that the fields actually exist on the model.

    Returns:
        A decorator that can be used to decorate a function to be used as a field_validator.

    Raises:
        PydanticUserError:
            - If `@field_validator` is used bare (with no fields).
            - If the args passed to `@field_validator` as fields are not strings.
            - If `@field_validator` applied to instance methods.
    """
    if isinstance(__field, FunctionType):
        raise PydanticUserError(
            '`@field_validator` should be used with fields and keyword arguments, not bare. '
            "E.g. usage should be `@validator('<field_name>', ...)`",
            code='validator-no-fields',
        )
    fields = __field, *fields
    if not all(isinstance(field, str) for field in fields):  # type: ignore
        raise PydanticUserError(
            '`@field_validator` fields should be passed as separate string args. '
            "E.g. usage should be `@validator('<field_name_1>', '<field_name_2>', ...)`",
            code='validator-invalid-fields',
        )

    def dec(
        f: Callable[..., Any] | staticmethod[Any, Any] | classmethod[Any, Any, Any]
    ) -> _decorators.PydanticDescriptorProxy[Any]:
        if _decorators.is_instance_method_from_sig(f):
            raise PydanticUserError(
                '`@field_validator` cannot be applied to instance methods', code='validator-instance-method'
            )

        # auto apply the @classmethod decorator
        f = _decorators.ensure_classmethod_based_on_signature(f)

        dec_info = _decorators.FieldValidatorDecoratorInfo(fields=fields, mode=mode, check_fields=check_fields)
        return _decorators.PydanticDescriptorProxy(f, dec_info)

    return dec

model_validator

model_validator(*, mode)

Decorate model methods for validation purposes.

Parameters:

Name	Type	Description	Default
mode	Literal['wrap', 'before', 'after']	A required string literal that specifies the validation mode. It can be one of the following: 'wrap', 'before', or 'after'.	required

Returns:

Type	Description
Any	A decorator that can be used to decorate a function to be used as a model validator.

Source code in pydantic/functional_validators.py

def model_validator(
    *,
    mode: Literal['wrap', 'before', 'after'],
) -> Any:
    """Decorate model methods for validation purposes.

    Args:
        mode: A required string literal that specifies the validation mode.
            It can be one of the following: 'wrap', 'before', or 'after'.

    Returns:
        A decorator that can be used to decorate a function to be used as a model validator.
    """

    def dec(f: Any) -> _decorators.PydanticDescriptorProxy[Any]:
        # auto apply the @classmethod decorator
        f = _decorators.ensure_classmethod_based_on_signature(f)
        dec_info = _decorators.ModelValidatorDecoratorInfo(mode=mode)
        return _decorators.PydanticDescriptorProxy(f, dec_info)

    return dec