Skip to content

Pydantic Plugins

Experimental feature

Plugins support is experimental and is subject to change in minor releases. Developing plugins is not recommended until the feature becomes stable.

Usage Documentation

Build a plugin

Plugin interface for Pydantic plugins, and related types.

SchemaTypePath

Bases: NamedTuple

Path defining where schema_type was defined, or where TypeAdapter was called.

PydanticPluginProtocol

Bases: Protocol

Protocol defining the interface for Pydantic plugins.

new_schema_validator

new_schema_validator(
    schema: CoreSchema,
    schema_type: Any,
    schema_type_path: SchemaTypePath,
    schema_kind: SchemaKind,
    config: CoreConfig | None,
    plugin_settings: dict[str, object],
) -> tuple[
    ValidatePythonHandlerProtocol | None,
    ValidateJsonHandlerProtocol | None,
    ValidateStringsHandlerProtocol | None,
]

This method is called for each plugin every time a new SchemaValidator is created.

It should return an event handler for each of the three validation methods, or None if the plugin does not implement that method.

Parameters:

Name Type Description Default
schema CoreSchema

The schema to validate against.

required
schema_type Any

The original type which the schema was created from, e.g. the model class.

required
schema_type_path SchemaTypePath

Path defining where schema_type was defined, or where TypeAdapter was called.

required
schema_kind SchemaKind

The kind of schema to validate against.

required
config CoreConfig | None

The config to use for validation.

required
plugin_settings dict[str, object]

Any plugin settings.

required

Returns:

Type Description
tuple[ValidatePythonHandlerProtocol | None, ValidateJsonHandlerProtocol | None, ValidateStringsHandlerProtocol | None]

A tuple of optional event handlers for each of the three validation methods - validate_python, validate_json, validate_strings.

Source code in pydantic/plugin/__init__.py
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
def new_schema_validator(
    self,
    schema: CoreSchema,
    schema_type: Any,
    schema_type_path: SchemaTypePath,
    schema_kind: SchemaKind,
    config: CoreConfig | None,
    plugin_settings: dict[str, object],
) -> tuple[
    ValidatePythonHandlerProtocol | None, ValidateJsonHandlerProtocol | None, ValidateStringsHandlerProtocol | None
]:
    """This method is called for each plugin every time a new [`SchemaValidator`][pydantic_core.SchemaValidator]
    is created.

    It should return an event handler for each of the three validation methods, or `None` if the plugin does not
    implement that method.

    Args:
        schema: The schema to validate against.
        schema_type: The original type which the schema was created from, e.g. the model class.
        schema_type_path: Path defining where `schema_type` was defined, or where `TypeAdapter` was called.
        schema_kind: The kind of schema to validate against.
        config: The config to use for validation.
        plugin_settings: Any plugin settings.

    Returns:
        A tuple of optional event handlers for each of the three validation methods -
            `validate_python`, `validate_json`, `validate_strings`.
    """
    raise NotImplementedError('Pydantic plugins should implement `new_schema_validator`.')

BaseValidateHandlerProtocol

Bases: Protocol

Base class for plugin callbacks protocols.

You shouldn't implement this protocol directly, instead use one of the subclasses with adds the correctly typed on_error method.

on_enter instance-attribute

on_enter: Callable[..., None]

on_enter is changed to be more specific on all subclasses

on_success

on_success(result: Any) -> None

Callback to be notified of successful validation.

Parameters:

Name Type Description Default
result Any

The result of the validation.

required
Source code in pydantic/plugin/__init__.py
82
83
84
85
86
87
88
def on_success(self, result: Any) -> None:
    """Callback to be notified of successful validation.

    Args:
        result: The result of the validation.
    """
    return

on_error

on_error(error: ValidationError) -> None

Callback to be notified of validation errors.

Parameters:

Name Type Description Default
error ValidationError

The validation error.

required
Source code in pydantic/plugin/__init__.py
90
91
92
93
94
95
96
def on_error(self, error: ValidationError) -> None:
    """Callback to be notified of validation errors.

    Args:
        error: The validation error.
    """
    return

on_exception

on_exception(exception: Exception) -> None

Callback to be notified of validation exceptions.

Parameters:

Name Type Description Default
exception Exception

The exception raised during validation.

required
Source code in pydantic/plugin/__init__.py
 98
 99
100
101
102
103
104
def on_exception(self, exception: Exception) -> None:
    """Callback to be notified of validation exceptions.

    Args:
        exception: The exception raised during validation.
    """
    return

ValidatePythonHandlerProtocol

Bases: BaseValidateHandlerProtocol, Protocol

Event handler for SchemaValidator.validate_python.

on_enter

on_enter(
    input: Any,
    *,
    strict: bool | None = None,
    from_attributes: bool | None = None,
    context: dict[str, Any] | None = None,
    self_instance: Any | None = None
) -> None

Callback to be notified of validation start, and create an instance of the event handler.

Parameters:

Name Type Description Default
input Any

The input to be validated.

required
strict bool | None

Whether to validate the object in strict mode.

None
from_attributes bool | None

Whether to validate objects as inputs by extracting attributes.

None
context dict[str, Any] | None

The context to use for validation, this is passed to functional validators.

None
self_instance Any | None

An instance of a model to set attributes on from validation, this is used when running validation from the __init__ method of a model.

None
Source code in pydantic/plugin/__init__.py
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
def on_enter(
    self,
    input: Any,
    *,
    strict: bool | None = None,
    from_attributes: bool | None = None,
    context: dict[str, Any] | None = None,
    self_instance: Any | None = None,
) -> None:
    """Callback to be notified of validation start, and create an instance of the event handler.

    Args:
        input: The input to be validated.
        strict: Whether to validate the object in strict mode.
        from_attributes: Whether to validate objects as inputs by extracting attributes.
        context: The context to use for validation, this is passed to functional validators.
        self_instance: An instance of a model to set attributes on from validation, this is used when running
            validation from the `__init__` method of a model.
    """
    pass

ValidateJsonHandlerProtocol

Bases: BaseValidateHandlerProtocol, Protocol

Event handler for SchemaValidator.validate_json.

on_enter

on_enter(
    input: str | bytes | bytearray,
    *,
    strict: bool | None = None,
    context: dict[str, Any] | None = None,
    self_instance: Any | None = None
) -> None

Callback to be notified of validation start, and create an instance of the event handler.

Parameters:

Name Type Description Default
input str | bytes | bytearray

The JSON data to be validated.

required
strict bool | None

Whether to validate the object in strict mode.

None
context dict[str, Any] | None

The context to use for validation, this is passed to functional validators.

None
self_instance Any | None

An instance of a model to set attributes on from validation, this is used when running validation from the __init__ method of a model.

None
Source code in pydantic/plugin/__init__.py
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
def on_enter(
    self,
    input: str | bytes | bytearray,
    *,
    strict: bool | None = None,
    context: dict[str, Any] | None = None,
    self_instance: Any | None = None,
) -> None:
    """Callback to be notified of validation start, and create an instance of the event handler.

    Args:
        input: The JSON data to be validated.
        strict: Whether to validate the object in strict mode.
        context: The context to use for validation, this is passed to functional validators.
        self_instance: An instance of a model to set attributes on from validation, this is used when running
            validation from the `__init__` method of a model.
    """
    pass

ValidateStringsHandlerProtocol

Bases: BaseValidateHandlerProtocol, Protocol

Event handler for SchemaValidator.validate_strings.

on_enter

on_enter(
    input: StringInput,
    *,
    strict: bool | None = None,
    context: dict[str, Any] | None = None
) -> None

Callback to be notified of validation start, and create an instance of the event handler.

Parameters:

Name Type Description Default
input StringInput

The string data to be validated.

required
strict bool | None

Whether to validate the object in strict mode.

None
context dict[str, Any] | None

The context to use for validation, this is passed to functional validators.

None
Source code in pydantic/plugin/__init__.py
161
162
163
164
165
166
167
168
169
170
171
def on_enter(
    self, input: StringInput, *, strict: bool | None = None, context: dict[str, Any] | None = None
) -> None:
    """Callback to be notified of validation start, and create an instance of the event handler.

    Args:
        input: The string data to be validated.
        strict: Whether to validate the object in strict mode.
        context: The context to use for validation, this is passed to functional validators.
    """
    pass