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

Pydantic Plugins

SchemaTypePath ¶

PydanticPluginProtocol ¶

new_schema_validator ¶

BaseValidateHandlerProtocol ¶

on_enter instance-attribute ¶

on_success ¶

on_error ¶

on_exception ¶

ValidatePythonHandlerProtocol ¶

on_enter ¶

ValidateJsonHandlerProtocol ¶

on_enter ¶

ValidateStringsHandlerProtocol ¶

on_enter ¶

on_enter `instance-attribute` ¶