FastAPI Pydantic モデル

Pydantic は FastAPI の中核となる依存関係であり、データ検証とシリアライゼーションに使用されます。標準の Python 型注釈を使用してデータモデルを定義でき、データ検証、型変換、ドキュメント生成を自動的に完了します。


Pydantic とは

Pydantic は Python のデータ検証ライブラリです。その中核となる考え方は次のとおりです:Python の型注釈でデータ構造を定義すると、Pydantic が自動的に検証と変換を担当します。FastAPI では、Pydantic は主に次の用途で使用されます:

用途説明
リクエストボディの検証クライアントが送信した JSON データがモデル定義に適合するかを自動的に検証します
レスポンスボディのシリアライゼーションモデルデータを自動的に JSON レスポンスに変換します
自動ドキュメントモデルのフィールド、型、検証ルールが API ドキュメントに自動的に表示されます
エディタサポートモデルの属性はエディタで完全な自動補完を取得します

Pydantic モデルの定義

継承するBaseModelクラスを作成し、Python の標準型を使用してフィールドを宣言します:

インスタンス

from pydantic import BaseModel


class Item(BaseModel):
    name: str               # 必須:商品名
    description: str | None = None  # 任意:商品の説明
    price: float            # 必須:商品価格
    tax: float | None = None        # 任意:税

フィールドが必須かどうかは、デフォルト値があるかどうかによって決まります:

フィールド宣言方法必須かどうか
namename: str必須
descriptiondescription: str | None = None任意
priceprice: float必須
taxtax: float | None = None任意

Pydantic モデルの使用

リクエストボディとして

最も一般的な使用方法は、モデルをパス操作関数のパラメータとして宣言することです:

インスタンス

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None


@app.post("/items/")
async def create_item(item: Item):
    # FastAPI がリクエストボディを自動検証し、検証に合格すると item パラメータに代入します
    return item

モデルデータへのアクセスと操作

インスタンス

@app.post("/items/")
async def create_item(item: Item):
    # モデル属性へのアクセス
    print(item.name)       # 属性に直接アクセス
    print(item.price)      # エディタが自動補完を提供

    # 辞書にシリアライズ
    item_dict = item.model_dump()
    print(item_dict)       # {"name": "Foo", "description": None, "price": 45.2, "tax": None}

    # JSON 文字列にシリアライズ
    item_json = item.model_dump_json()
    print(item_json)       # '{"name":"Foo","description":null,"price":45.2,"tax":null}'

    return item_dict

Pydantic v2 では、model_dump()とmodel_dump_json()が v1 のdict()とjson()メソッドの代わりに使用されます。新しいメソッドはパフォーマンスが向上しています(内部は Rust で実装)。


モデル検証の例

クライアントが送信したデータがモデル定義に適合しない場合、FastAPI は詳細な検証エラーを返します:

インスタンス

# クライアントが必須フィールドが欠落しているデータを送信しました
POST /items/
{
    "description": "name と price が不足しています"
}

# FastAPI が検証エラーを返します
{
    "detail": [
        {
            "type": "missing",
            "loc": ["body", "name"],
            "msg": "Field required",
            "input": {"description": "name と price が不足しています"}
        },
        {
            "type": "missing",
            "loc": ["body", "price"],
            "msg": "Field required",
            "input": {"description": "name と price が不足しています"}
        }
    ]
}

型が間違ったデータを送信した場合:

// price 应该是数字,但传了字符串
{
    "name": "Foo",
    "price": "not a number"
}

// FastAPI 返回的错误
{
    "detail": [
        {
            "type": "float_parsing",
            "loc": ["body", "price"],
            "msg": "Input should be a valid number, unable to parse string as a number",
            "input": "not a number"
        }
    ]
}

Pydantic v2 の一般的なメソッド

メソッドv2(推奨)v1(非推奨)説明
辞書にシリアライズitem.model_dump()item.dict()モデルを Python 辞書に変換します
JSON にシリアライズitem.model_dump_json()item.json()モデルを JSON 文字列に変換します
辞書から作成Item.model_validate(data)Item.parse_obj(data)辞書からモデルを作成し検証します
JSON から作成Item.model_validate_json(json_str)Item.parse_raw(json_str)JSON 文字列からモデルを作成します
JSON Schema の取得Item.model_json_schema()Item.schema()モデルの JSON Schema を取得します

モデル設定(model_config)

Pydantic v2 では、model_configが v1 のConfig内部クラスの代わりに使用されます:

インスタンス

from pydantic import BaseModel, ConfigDict


class Item(BaseModel):
    name: str
    price: float

    # Pydantic v2 の設定方法
    model_config = ConfigDict(
        json_schema_extra={  # API ドキュメントにサンプルを表示
            "examples": [
                {
                    "name": "Foo",
                    "price": 35.4
                }
            ]
        }
    )

Pydantic v2 では、orm_mode = Trueに変更されましたfrom_attributes = True,schema_extraに変更されましたjson_schema_extra,allow_population_by_field_nameに変更されましたpopulate_by_name。


モデルの継承

Pydantic モデルは継承をサポートしており、入力モデルと出力モデルを簡単に作成できます:

インスタンス

from pydantic import BaseModel, EmailStr


# 基本モデル
class UserBase(BaseModel):
    username: str       # 必須
    email: EmailStr     # 必須、メールアドレスの形式を自動検証
    full_name: str | None = None  # 任意


# ユーザー作成時の入力モデル(パスワードを含む)
class UserCreate(UserBase):
    password: str       # 必須


# ユーザー情報を返すときの出力モデル(パスワードを含まない)
class UserOut(UserBase):
    id: int             # サーバー側で生成


# 使用例
@app.post("/users/", response_model=UserOut)
async def create_user(user: UserCreate):
    # 関数は UserCreate(パスワードを含む)を受け取りますが、レスポンスでは UserOut(パスワードを含まない)を使用します
    # これによりパスワードが API レスポンスに表示されなくなります
    return {"id": 1, **user.model_dump(exclude={"password"})}

異なる入力モデルと出力モデルを使用することは、機密データを保護するための重要な手段です。API レスポンスではパスワードなどの機密フィールドを決して返さないでください。


まとめ

Pydantic モデルの重要ポイント:

  • を使用してBaseModelデータモデルを定義し、標準の Python 型でフィールドを宣言します
  • デフォルト値があるフィールドは任意で、デフォルト値がないフィールドは必須です
  • v2 ではmodel_dump()、model_validate()などの新しいメソッドを使用します
  • モデルの継承によって異なる入力/出力モデルを作成し、機密データを保護します
  • すべての検証とドキュメントは自動で行われ、型を一度宣言するだけです
その他の拡張