実験的な機能¶

このセクションには、Pydantic の新しい実験的な機能に関するドキュメントがあります。これらの機能は変更または削除される可能性があり、Pydantic の永続的な部分にする前にフィードバックや提案を求めています。

実験的機能の詳細については、バージョンポリシーを参照してください。

フィードバック¶

実験的な機能に関するフィードバックをお待ちしています。 Pydantic GitHub リポジトリで問題を開いて、ご意見、リクエスト、提案を共有してください。

また、既存のフィードバックに目を通し、既存の問題に意見を追加することをお勧めします。

インポートに関する警告¶

experimentalモジュールから実験的機能をインポートすると、その機能が実験的であるという警告メッセージが表示されます。この警告は次のように無効にできます。

import warnings

from pydantic import PydanticExperimentalWarning

warnings.filterwarnings('ignore', category=PydanticExperimentalWarning)

パイプラインAPI¶

Pydantic v2.8.0 では、既存の API よりもタイプセーフな方法で解析 (検証)、制約、変換を構成できる実験的な「パイプライン」API が導入されました。この API は変更または削除される可能性があります。Pydantic の永続的な一部とする前に、フィードバックや提案を求めています。

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

一般に、パイプライン API は、検証中に受信データに適用する一連のステップを定義するために使用されます。パイプライン API は、既存の Pydantic API よりもタイプセーフで構成しやすいように設計されています。

パイプラインの各ステップは次のとおりです。

提供された型に対して pydantic 検証を実行する検証ステップ
データを変更する変換ステップ
条件に対してデータをチェックする制約ステップ
データを条件と照合してチェックし、 False返された場合にエラーを発生させる述語ステップ

次の例は、複雑さを犠牲にして網羅的であるように努めていることに注意してください。型アノテーションでこれほど多くの変換を記述していることに気付いた場合は、 UserInおよびUserOutモデル (以下の例) または類似のモデルを使用して、idomatic 経由で変換を行うことを検討するとよいでしょう。プレーンな Python コード。これらの API は、コードが大幅に節約され、追加される複雑さが比較的小さい状況を対象としています。

from __future__ import annotations

from datetime import datetime

from typing_extensions import Annotated

from pydantic import BaseModel
from pydantic.experimental.pipeline import validate_as, validate_as_deferred


class User(BaseModel):
    name: Annotated[str, validate_as(str).str_lower()]  # (1)!
    age: Annotated[int, validate_as(int).gt(0)]  # (2)!
    username: Annotated[str, validate_as(str).str_pattern(r'[a-z]+')]  # (3)!
    password: Annotated[
        str,
        validate_as(str)
        .transform(str.lower)
        .predicate(lambda x: x != 'password'),  # (4)!
    ]
    favorite_number: Annotated[  # (5)!
        int,
        (validate_as(int) | validate_as(str).str_strip().validate_as(int)).gt(
            0
        ),
    ]
    friends: Annotated[list[User], validate_as(...).len(0, 100)]  # (6)!
    family: Annotated[  # (7)!
        list[User],
        validate_as_deferred(lambda: list[User]).transform(lambda x: x[1:]),
    ]
    bio: Annotated[
        datetime,
        validate_as(int)
        .transform(lambda x: x / 1_000_000)
        .validate_as(...),  # (8)!
    ]

文字列を小文字にします。
整数がゼロより大きくなるように制限します。
正規表現パターンに一致するように文字列を制約します。
下位レベルの変換、制約、述語メソッドを使用することもできます。
|使用します。 or &演算子を使用してステップを結合します (論理 OR や AND など)。
最初の位置引数としてEllipsis , ...を指定してvalidate_as(...)を呼び出すと、 validate_as(<field type>)が暗黙的に指定されます。任意の型を受け入れるには、 validate_as(Any)使用します。
再帰型の場合、 validate_as_deferred使用して、定義される前に型自体を参照できます。
他のステップの前後にvalidate_as()呼び出して、前処理または後処理を行うことができます。

`BeforeValidator` 、 `AfterValidator` 、および`WrapValidator`からのマッピング¶

validate_asメソッドは、 BeforeValidator 、 AfterValidator 、およびWrapValidator定義するための、よりタイプセーフな方法です。

from typing_extensions import Annotated

from pydantic.experimental.pipeline import transform, validate_as

# BeforeValidator
Annotated[int, validate_as(str).str_strip().validate_as(...)]  # (1)!
# AfterValidator
Annotated[int, transform(lambda x: x * 2)]  # (2)!
# WrapValidator
Annotated[
    int,
    validate_as(str)
    .str_strip()
    .validate_as(...)
    .transform(lambda x: x * 2),  # (3)!
]

文字列を整数として解析する前に、文字列から空白を削除します。
整数を解析した後、2 を掛けます。
文字列から空白を取り除き、整数として検証してから 2 を掛けます。

代替パターン¶

シナリオに応じて使用できる代替パターンが多数あります。ほんの一例として、上記のUserInとUserOutパターンを考えてみましょう。

from __future__ import annotations

from pydantic import BaseModel


class UserIn(BaseModel):
    favorite_number: int | str


class UserOut(BaseModel):
    favorite_number: int


def my_api(user: UserIn) -> UserOut:
    favorite_number = user.favorite_number
    if isinstance(favorite_number, str):
        favorite_number = int(user.favorite_number.strip())

    return UserOut(favorite_number=favorite_number)


assert my_api(UserIn(favorite_number=' 1 ')).favorite_number == 1

この例では、上記の例よりも理解しやすく、型チェックなどが容易な単純な慣用的な Python コードを使用しています。どのアプローチを選択するかは、実際のユースケースによって異なります。適切なパターンを選択するには、冗長性、パフォーマンス、意味のあるエラーをユーザーに返す容易さなどを比較する必要があります。できるからといって、パイプライン API のような高度なパターンを悪用しないように注意してください。

本文总阅读量次