Dataclasses の使用¶

🌐 AI と人間による翻訳

この翻訳は、人間のガイドに基づいて AI によって作成されました。🤝

原文の意図を取り違えていたり、不自然な表現になっている可能性があります。🤖

FastAPI は Pydantic の上に構築されており、これまでにリクエストやレスポンスを宣言するために Pydantic モデルを使う方法を紹介してきました。

しかし FastAPI は、同様の方法で dataclasses もサポートします:

Python 3.10+

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 を使用できます:

Python 3.10+

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 に置き換えるだけで済みます。これはドロップイン置換です:

Python 3.10+

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 のドロップイン置換です。
Author dataclass は Item dataclass のリストを含みます。
Author dataclass を response_model パラメータとして使用しています。
リクエストボディとしての dataclass と併せて、他の標準の型注釈を使用できます。

この例では、Item dataclass のリストです。
ここでは、dataclass のリストである items を含む辞書を返しています。

FastAPI はデータを JSON にシリアライズできます。
ここでは response_model に Author dataclass のリストという型注釈を使用しています。

このように、dataclasses は標準の型注釈と組み合わせられます。
この path operation 関数 は、async def ではなく通常の def を使用しています。

いつもどおり、FastAPI では必要に応じて def と async def を組み合わせられます。

どちらをいつ使うかの復習が必要な場合は、async と await に関するドキュメントの 「急いでいますか？」 セクションを参照してください。
この path operation 関数 は（可能ではありますが）dataclass 自体は返さず、内部データを持つ辞書のリストを返しています。

FastAPI は dataclass を含む response_model パラメータを使ってレスポンスを変換します。

dataclasses は他の型注釈と多様な組み合わせが可能で、複雑なデータ構造を構成できます。

上記のコード内の注釈のヒントを参照して、より具体的な詳細を確認してください。

さらに学ぶ¶

dataclasses を他の Pydantic モデルと組み合わせたり、継承したり、自分のモデルに含めたりもできます。

詳しくは、dataclasses に関する Pydantic ドキュメントを参照してください。

バージョン¶

これは FastAPI バージョン 0.67.0 以降で利用可能です。🔖

Dataclasses の使用¶

response_model での dataclasses¶

ネストしたデータ構造での dataclasses¶

さらに学ぶ¶

バージョン¶

`response_model` での dataclasses¶