Dataclasses を使う¶

FastAPI は Pydantic の上に構築されており、Pydantic モデルを使ってリクエストとレスポンスを宣言する方法を説明してきました。

しかし、FastAPI は dataclasses も同じように使用することをサポートしています

Python 3.8 以降

from dataclasses import dataclass
from typing import Union

from fastapi import FastAPI


@dataclass
class Item:
    name: str
    price: float
    description: Union[str, None] = None
    tax: Union[float, None] = None


app = FastAPI()


@app.post("/items/")
async def create_item(item: Item):
    return item

これは Pydantic のおかげで引き続きサポートされており、Pydantic は dataclasses の内部サポートを持っています。

そのため、Pydantic を明示的に使用しない上記のコードでも、FastAPI は Pydantic を使用して、これらの標準的な dataclasses を Pydantic 独自の dataclasses に変換しています。

そしてもちろん、同じものをサポートしています

データ検証
データシリアル化
データドキュメントなど。

これは Pydantic モデルと同じように機能します。そして、実際には Pydantic を使用して、内部で同じ方法で実現されています。

情報

dataclasses は Pydantic モデルができることのすべてができるわけではないことに注意してください。

そのため、Pydantic モデルを使用する必要がある場合もあります。

しかし、もし多くの dataclasses を持っているなら、これらは FastAPI を使って Web API を動かすための素晴らしいトリックです。 🤓

`response_model` における Dataclasses¶

response_model パラメータでも dataclasses を使用できます。

Python 3.8 以降

from dataclasses import dataclass, field
from typing import List, Union

from fastapi import FastAPI


@dataclass
class Item:
    name: str
    price: float
    tags: List[str] = field(default_factory=list)
    description: Union[str, None] = None
    tax: Union[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 ドキュメントのユーザーインターフェースに表示されます。

ネストされたデータ構造における Dataclasses¶

dataclasses を他の型アノテーションと組み合わせて、ネストされたデータ構造を作成することもできます。

場合によっては、Pydantic 版の dataclasses を使用する必要があるかもしれません。例えば、自動生成された API ドキュメントにエラーがある場合などです。

その場合、標準の dataclasses を pydantic.dataclasses に置き換えるだけでよく、これはドロップイン置換可能です。

Python 3.8 以降

from dataclasses import field  # (1)
from typing import List, Union

from fastapi import FastAPI
from pydantic.dataclasses import dataclass  # (2)


@dataclass
class Item:
    name: str
    description: Union[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",
                },
            ],
        },
    ]

field は引き続き標準の dataclasses からインポートします。
pydantic.dataclasses は dataclasses のドロップイン代替です。
Author dataclass には Item dataclasses のリストが含まれています。
Author dataclass は response_model パラメータとして使用されます。
他の標準型アノテーションをリクエストボディとして dataclasses と一緒に使用できます。

この場合、それは Item dataclasses のリストです。
ここでは、dataclasses のリストである items を含む辞書を返しています。

FastAPI は引き続きデータを JSON にシリアル化することができます。
ここでは、response_model が Author dataclasses のリストの型アノテーションを使用しています。

ここでも、dataclasses と標準型アノテーションを組み合わせることができます。
この パス操作関数 は、async def の代わりに通常の def を使用していることに注目してください。

FastAPI では、常に必要に応じて def と async def を組み合わせることができます。

どちらをいつ使うべきかについて再確認が必要な場合は、async と await に関するドキュメントの 「お急ぎですか？」 セクションを確認してください。
この パス操作関数 は dataclasses を返していません（返すこともできますが）、内部データを含む辞書のリストを返しています。

FastAPI は response_model パラメータ（dataclasses を含む）を使用してレスポンスを変換します。

dataclasses を他の型アノテーションと組み合わせて、さまざまな組み合わせで複雑なデータ構造を形成できます。

より具体的な詳細については、上記のコード内アノテーションのヒントを確認してください。

詳細を見る¶

dataclasses を他の Pydantic モデルと組み合わせたり、それらから継承したり、独自のモデルに含めたりすることもできます。

詳細については、dataclasses に関する Pydantic のドキュメントを確認してください。

バージョン¶

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

Dataclasses を使う¶

response_model における Dataclasses¶

ネストされたデータ構造における Dataclasses¶

詳細を見る¶

バージョン¶

`response_model` における Dataclasses¶