Functional Validators

This module contains related classes and functions for validation.

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

The validator function.

Type: core_schema.NoInfoValidatorFunction | core_schema.WithInfoValidatorFunction

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

The validator function.

Type: core_schema.NoInfoValidatorFunction | core_schema.WithInfoValidatorFunction

The input type used to generate the appropriate JSON Schema (in validation mode). The actual input type is Any.

Type: Any

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

The validator function.

Type: core_schema.NoInfoValidatorFunction | core_schema.WithInfoValidatorFunction

The input type used to generate the appropriate JSON Schema (in validation mode). The actual input type is Any.

Type: Any

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

The validator function.

Type: core_schema.NoInfoWrapValidatorFunction | core_schema.WithInfoWrapValidatorFunction

The input type used to generate the appropriate JSON Schema (in validation mode). The actual input type is Any.

Type: Any

from datetime import datetime
from typing 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

Bases: ValidatorFunctionWrapHandler, Protocol[_ModelTypeCo]

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

Bases: Protocol[_ModelType]

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

Bases: Protocol[_ModelType]

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

Bases: Protocol

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

Bases: Protocol

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

Bases: Protocol

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

Bases: Protocol

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

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

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.

A helper class to validate a custom type from a type that is natively supported by Pydantic.

from_type : type[_FromTypeT]

The type natively supported by Pydantic to use to perform validation.

instantiation_hook : Callable[[_FromTypeT], Any]

A callable taking the validated type as an argument, and returning the populated custom type.

def field_validator(
    field: str,
    /,
    *fields: str,
    mode: Literal['wrap'],
    check_fields: bool | None = ...,
    json_schema_input_type: Any = ...,
) -> Callable[[_V2WrapValidatorType], _V2WrapValidatorType]
def field_validator(
    field: str,
    /,
    *fields: str,
    mode: Literal['before', 'plain'],
    check_fields: bool | None = ...,
    json_schema_input_type: Any = ...,
) -> Callable[[_V2BeforeAfterOrPlainValidatorType], _V2BeforeAfterOrPlainValidatorType]
def field_validator(
    field: str,
    /,
    *fields: str,
    mode: Literal['after'] = ...,
    check_fields: bool | None = ...,
) -> Callable[[_V2BeforeAfterOrPlainValidatorType], _V2BeforeAfterOrPlainValidatorType]

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

Example usage:

from typing import Any

from pydantic import (
    BaseModel,
    ValidationError,
    field_validator,
)

class Model(BaseModel):
    a: str

    @field_validator('a')
    @classmethod
    def ensure_foobar(cls, v: Any):
        if 'foobar' not in v:
            raise ValueError('"foobar" not found in a')
        return v

print(repr(Model(a='this is foobar good')))
#> Model(a='this is foobar good')

try:
    Model(a='snap')
except ValidationError as exc_info:
    print(exc_info)
    '''
    1 validation error for Model
    a
      Value error, "foobar" not found in a [type=value_error, input_value='snap', input_type=str]
    '''

For more in depth examples, see Field Validators.

Errors raised in a field validator become part of the model’s ValidationError. In a running application, Logfire can record the input each failed validation rejected — see Troubleshooting validation errors.

Callable[[Any], Any]

*fields : str Default: ()

The field names the validator should apply to.

mode : FieldValidatorModes Default: 'after'

Specifies whether to validate the fields before or after validation.

check_fields : bool | None Default: None

Whether to check that the fields actually exist on the model.

json_schema_input_type : Any Default: PydanticUndefined

The input type of the function. This is only used to generate the appropriate JSON Schema (in validation mode) and can only specified when mode is either 'before', 'plain' or 'wrap'.

• PydanticUserError —
• If the decorator is used without any arguments (at least one field name must be provided).
• If the provided field names are not strings.
• If json_schema_input_type is provided with an unsupported mode.
• If the decorator is applied to an instance method.

def model_validator(
    *,
    mode: Literal['wrap'],
) -> Callable[[_AnyModelWrapValidator[_ModelType]], _decorators.PydanticDescriptorProxy[_decorators.ModelValidatorDecoratorInfo]]
def model_validator(
    *,
    mode: Literal['before'],
) -> Callable[[_AnyModelBeforeValidator], _decorators.PydanticDescriptorProxy[_decorators.ModelValidatorDecoratorInfo]]
def model_validator(
    *,
    mode: Literal['after'],
) -> Callable[[_AnyModelAfterValidator[_ModelType]], _decorators.PydanticDescriptorProxy[_decorators.ModelValidatorDecoratorInfo]]

Decorate model methods for validation purposes.

Example usage:

from typing_extensions import Self

from pydantic import BaseModel, ValidationError, model_validator

class Square(BaseModel):
    width: float
    height: float

    @model_validator(mode='after')
    def verify_square(self) -> Self:
        if self.width != self.height:
            raise ValueError('width and height do not match')
        return self

s = Square(width=1, height=1)
print(repr(s))
#> Square(width=1.0, height=1.0)

try:
    Square(width=1, height=2)
except ValidationError as e:
    print(e)
    '''
    1 validation error for Square
      Value error, width and height do not match [type=value_error, input_value={'width': 1, 'height': 2}, input_type=dict]
    '''

For more in depth examples, see Model Validators.

Cross-field rules like the one above tend to fail on combinations of values you didn’t anticipate. To see the combination that failed in a running application, record validations with Logfire (see Troubleshooting validation errors).

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

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’.

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

Default: Callable[[_ModelType], _ModelType]

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

Default: Callable[[_ModelType, core_schema.ValidationInfo[Any]], _ModelType]

Was this page helpful?