Pydanticプラグイン

!!!警告「実験的機能」プラグインのサポートは実験的であり、マイナーリリースで変更される可能性があります。機能が安定するまで、プラグインの開発は推奨されません。

Pydantic を使用すると、ユーザーはライブラリの機能を拡張するために使用できるプラグインを作成できます。

プラグインは Python エントリポイント経由でインストールされます。エントリポイントの詳細については、Python Packaging Authority のエントリポイント仕様を参照してください。

my-pydantic-pluginというプロジェクトがある場合は、以下をpyproject.tomlに追加してプラグインを作成できます。

[project.entry-points.pydantic]
my_plugin = "my_pydantic_plugin:plugin"

エントリポイントグループはpydantic 、 my_pluginプラグインの名前、 my_pydantic_pluginはプラグインオブジェクトのロード元のモジュール、 pluginロードするオブジェクトの名前です。

プラグインは見つかった順序でロードされますが、見つかった順序は保証されません。

ユーザーは、 plugin_settingsモデル構成引数またはクラスキーワード引数を使用して、 BaseModel内のプラグインの動作を変更できます。この引数は、すべてのプラグインにそのまま渡される設定の辞書を受け取ります。プラグインはこれらの設定を使用して動作を変更できます。プラグインでは、 plugin_settingsディクショナリ内のプラグイン固有のキーにある独自の専用キーに設定を分離することをお勧めします。

from pydantic import BaseModel


class Foo(BaseModel, plugin_settings={'my-plugin': {'observe': 'all'}}): ...

プラグインを構築する¶

??? API「APIドキュメント」 pydantic.plugin

Pydantic は、プラグインを作成するための API を提供します。 API はpydantic.pluginモジュールを介して公開されます。

プラグインでは、次のメソッド_をラップ_できます。

validate_python: Python オブジェクトからのデータを検証するために使用されます。
validate_json: JSON 文字列からのデータを検証するために使用されます。
validate_strings: 文字列からデータを検証するために使用されます。

メソッドごとに、次のコールバックを実装できます。

on_enter : フィールドの検証が開始される前に呼び出されます。
on_success : フィールドの検証が成功したときに呼び出されます。
on_error : フィールドの検証が失敗したときに呼び出されます。

SchemaValidator のvalidate_pythonメソッド_をラップする_プラグインの例を見てみましょう。

from typing import Any, Dict, Optional, Union

from pydantic_core import CoreConfig, CoreSchema, ValidationError

from pydantic.plugin import (
    NewSchemaReturns,
    PydanticPluginProtocol,
    SchemaKind,
    SchemaTypePath,
    ValidatePythonHandlerProtocol,
)


class OnValidatePython(ValidatePythonHandlerProtocol):
    def on_enter(
        self,
        input: Any,
        *,
        strict: Optional[bool] = None,
        from_attributes: Optional[bool] = None,
        context: Optional[Dict[str, Any]] = None,
        self_instance: Optional[Any] = None,
    ) -> None:
        print(input)

    def on_success(self, result: Any) -> None:
        print(result)

    def on_error(self, error: ValidationError) -> None:
        print(error.json())


class Plugin(PydanticPluginProtocol):
    def new_schema_validator(
        self,
        schema: CoreSchema,
        schema_type: Any,
        schema_type_path: SchemaTypePath,
        schema_kind: SchemaKind,
        config: Union[CoreConfig, None],
        plugin_settings: Dict[str, object],
    ) -> NewSchemaReturns:
        return OnValidatePython(), None, None


plugin = Plugin()

プラグイン設定の使用¶

「observer」という設定というプラグインがあるとします。次のように使用できます。

from pydantic import BaseModel


class Foo(BaseModel, plugin_settings={'observer': 'all'}): ...

各検証呼び出しで、 plugin_settingsイベントに登録された呼び出し可能オブジェクトに渡されます。

プラグインの無効化¶

環境変数PYDANTIC_DISABLE_PLUGINSを使用して、すべてまたは特定のプラグインを無効にすることができます。

環境変数	許可される値	説明
`PYDANTIC_DISABLE_PLUGINS`	`__all__` 、 `1` 、 `true`	すべてのプラグインを無効にします
	カンマ区切りの文字列 (例: `my-plugin-1,my-plugin2` )	指定されたプラグインを無効にします

本文总阅读量次