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

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

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

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

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

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

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

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