Dataclasses の使用¶
🌐 AI と人間による翻訳
この翻訳は、人間のガイドに基づいて AI によって作成されました。🤝
原文の意図を取り違えていたり、不自然な表現になっている可能性があります。🤖
AI LLM をより適切に誘導するのを手伝う ことで、この翻訳を改善できます。
FastAPI は Pydantic の上に構築されており、これまでにリクエストやレスポンスを宣言するために Pydantic モデルを使う方法を紹介してきました。
しかし FastAPI は、同様の方法で dataclasses もサポートします:
from dataclasses import dataclass
from fastapi import FastAPI
@dataclass
class Item:
name: str
price: float
description: str | None = None
tax: float | None = None
app = FastAPI()
@app.post("/items/")
async def create_item(item: Item):
return item
これは Pydantic によって引き続きサポートされています。Pydantic には dataclasses の内部サポート があるためです。
そのため、上記のように明示的に Pydantic を使っていないコードでも、FastAPI は標準の dataclass を Pydantic 独自の dataclass に変換するために Pydantic を使用しています。
そして当然ながら、次の点も同様にサポートされます:
- データ検証
- データのシリアライズ
- データのドキュメント化 など
これは Pydantic モデルの場合と同じように動作します。内部的にも同様に Pydantic を使って実現されています。
情報
dataclasses は、Pydantic モデルができることをすべては行えない点に留意してください。
そのため、Pydantic モデルを使う必要がある場合もあります。
しかし既存の dataclass が多数あるなら、FastAPI で Web API を構築する際にそれらを活用するちょっとしたテクニックになります。🤓
response_model での dataclasses¶
response_model パラメータでも dataclasses を使用できます:
from dataclasses import dataclass, field
from fastapi import FastAPI
@dataclass
class Item:
name: str
price: float
tags: list[str] = field(default_factory=list)
description: str | None = None
tax: float | None = None
app = FastAPI()
@app.get("/items/next", response_model=Item)
async def read_next_item():
return {
"name": "Island In The Moon",
"price": 12.99,
"description": "A place to be playin' and havin' fun",
"tags": ["breater"],
}
dataclass は自動的に Pydantic の dataclass に変換されます。
このため、そのスキーマは API ドキュメントの UI に表示されます:
ネストしたデータ構造での dataclasses¶
dataclasses を他の型注釈と組み合わせて、ネストしたデータ構造を作成できます。
場合によっては、自動生成された API ドキュメントでエラーが発生するなどの理由で、Pydantic 版の dataclasses を使う必要があるかもしれません。
その場合は、標準の dataclasses を pydantic.dataclasses に置き換えるだけで済みます。これはドロップイン置換です:
from dataclasses import field # (1)
from fastapi import FastAPI
from pydantic.dataclasses import dataclass # (2)
@dataclass
class Item:
name: str
description: str | None = None
@dataclass
class Author:
name: str
items: list[Item] = field(default_factory=list) # (3)
app = FastAPI()
@app.post("/authors/{author_id}/items/", response_model=Author) # (4)
async def create_author_items(author_id: str, items: list[Item]): # (5)
return {"name": author_id, "items": items} # (6)
@app.get("/authors/", response_model=list[Author]) # (7)
def get_authors(): # (8)
return [ # (9)
{
"name": "Breaters",
"items": [
{
"name": "Island In The Moon",
"description": "A place to be playin' and havin' fun",
},
{"name": "Holy Buddies"},
],
},
{
"name": "System of an Up",
"items": [
{
"name": "Salt",
"description": "The kombucha mushroom people's favorite",
},
{"name": "Pad Thai"},
{
"name": "Lonely Night",
"description": "The mostests lonliest nightiest of allest",
},
],
},
]
-
依然として標準の
dataclassesからfieldをインポートします。 -
pydantic.dataclassesはdataclassesのドロップイン置換です。 -
Authordataclass はItemdataclass のリストを含みます。 -
Authordataclass をresponse_modelパラメータとして使用しています。 -
リクエストボディとしての dataclass と併せて、他の標準の型注釈を使用できます。
この例では、
Itemdataclass のリストです。 -
ここでは、dataclass のリストである
itemsを含む辞書を返しています。FastAPI はデータを JSON に シリアライズ できます。
-
ここでは
response_modelにAuthordataclass のリストという型注釈を使用しています。このように、
dataclassesは標準の型注釈と組み合わせられます。 -
この path operation 関数 は、
async defではなく通常のdefを使用しています。いつもどおり、FastAPI では必要に応じて
defとasync defを組み合わせられます。どちらをいつ使うかの復習が必要な場合は、
asyncとawait{.internal-link target=blank} に関するドキュメントの _"In a hurry?" セクションを参照してください。 -
この path operation 関数 は（可能ではありますが）dataclass 自体は返さず、内部データを持つ辞書のリストを返しています。
FastAPI は dataclass を含む
response_modelパラメータを使ってレスポンスを変換します。
dataclasses は他の型注釈と多様な組み合わせが可能で、複雑なデータ構造を構成できます。
上記のコード内コメントのヒントを参照して、より具体的な詳細を確認してください。
さらに学ぶ¶
dataclasses を他の Pydantic モデルと組み合わせたり、継承したり、自分のモデルに含めたりもできます。
詳しくは、dataclasses に関する Pydantic ドキュメント を参照してください。
バージョン¶
これは FastAPI バージョン 0.67.0 以降で利用可能です。🔖