FastAPI Pydantic モデル
Pydantic は FastAPI の中核となる依存関係であり、データ検証とシリアライゼーションに使用されます。標準の Python 型注釈を使用してデータモデルを定義でき、データ検証、型変換、ドキュメント生成を自動的に完了します。
Pydantic とは
Pydantic は Python のデータ検証ライブラリです。その中核となる考え方は次のとおりです:Python の型注釈でデータ構造を定義すると、Pydantic が自動的に検証と変換を担当します。FastAPI では、Pydantic は主に次の用途で使用されます:
| 用途 | 説明 |
|---|---|
| リクエストボディの検証 | クライアントが送信した JSON データがモデル定義に適合するかを自動的に検証します |
| レスポンスボディのシリアライゼーション | モデルデータを自動的に JSON レスポンスに変換します |
| 自動ドキュメント | モデルのフィールド、型、検証ルールが API ドキュメントに自動的に表示されます |
| エディタサポート | モデルの属性はエディタで完全な自動補完を取得します |
Pydantic モデルの定義
継承するBaseModelクラスを作成し、Python の標準型を使用してフィールドを宣言します:
インスタンス
class Item(BaseModel):
name: str # 必須:商品名
description: str | None = None # 任意:商品の説明
price: float # 必須:商品価格
tax: float | None = None # 任意:税
フィールドが必須かどうかは、デフォルト値があるかどうかによって決まります:
| フィールド | 宣言方法 | 必須かどうか |
|---|---|---|
name | name: str | 必須 |
description | description: str | None = None | 任意 |
price | price: float | 必須 |
tax | tax: float | None = None | 任意 |
Pydantic モデルの使用
リクエストボディとして
最も一般的な使用方法は、モデルをパス操作関数のパラメータとして宣言することです:
インスタンス
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
モデルデータへのアクセスと操作
インスタンス
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内部クラスの代わりに使用されます:
インスタンス
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 モデルは継承をサポートしており、入力モデルと出力モデルを簡単に作成できます:
インスタンス
# 基本モデル
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()などの新しいメソッドを使用します - モデルの継承によって異なる入力/出力モデルを作成し、機密データを保護します
- すべての検証とドキュメントは自動で行われ、型を一度宣言するだけです