Використання dataclasses¶

🌐 Переклад ШІ та людьми

Цей переклад виконано ШІ під керівництвом людей. 🤝

Можливі помилки через неправильне розуміння початкового змісту або неприродні формулювання тощо. 🤖

Ви можете покращити цей переклад, допомігши нам краще спрямовувати AI LLM.

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, адже він має внутрішню підтримку dataclasses.

Тож навіть із наведеним вище кодом, який явно не використовує Pydantic, FastAPI використовує Pydantic, щоб перетворити стандартні dataclasses у власний варіант dataclasses Pydantic.

І, звісно, підтримується те саме:

валідація даних
серіалізація даних
документація даних тощо

Це працює так само, як із моделями Pydantic. Насправді під капотом це також досягається за допомогою Pydantic.

Інформація

Майте на увазі, що dataclasses не можуть робити все те, що можуть моделі Pydantic.

Тож вам усе ще може знадобитися використовувати моделі Pydantic.

Але якщо у вас вже є чимало dataclasses, це зручний трюк, щоб задіяти їх для веб-API на FastAPI. 🤓

Dataclasses у `response_model`¶

Ви також можете використовувати dataclasses у параметрі response_model:

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 буде автоматично перетворено на dataclass Pydantic.

Таким чином його схема з'явиться в інтерфейсі користувача документації API:

Dataclasses у вкладених структурах даних¶

Можна поєднувати dataclasses з іншими анотаціями типів, щоб створювати вкладені структури даних.

У деяких випадках вам усе ж доведеться використовувати варіант dataclasses від Pydantic. Наприклад, якщо виникають помилки з автоматично згенерованою документацією API.

У такому разі ви можете просто замінити стандартні 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",
                },
            ],
        },
    ]

Ми все ще імпортуємо field зі стандартних dataclasses.
pydantic.dataclasses - це взаємозамінник для dataclasses.
Dataclass Author містить список dataclass Item.
Dataclass Author використовується як параметр response_model.
Ви можете використовувати інші стандартні анотації типів із dataclasses як тіло запиту.

У цьому випадку це список dataclass Item.
Тут ми повертаємо словник, що містить items, який є списком dataclass.

FastAPI усе ще здатний серіалізувати дані до JSON.
Тут у response_model використано анотацію типу список dataclass Author.

Знову ж, ви можете поєднувати dataclasses зі стандартними анотаціями типів.
Зверніть увагу, що ця функція операції шляху використовує звичайний def замість async def.

Як завжди, у FastAPI ви можете поєднувати def і async def за потреби.

Якщо вам потрібне коротке нагадування, коли що використовувати, перегляньте розділ «Поспішаєте?» у документації про async та await.
Ця функція операції шляху не повертає dataclasses (хоча могла б), а список словників із внутрішніми даними.

FastAPI використає параметр response_model (що включає dataclasses), щоб перетворити відповідь.

Ви можете поєднувати dataclasses з іншими анотаціями типів у багатьох поєднаннях, щоб формувати складні структури даних.

Перегляньте підказки щодо анотацій у коді вище, щоб побачити більше деталей.

Дізнатися більше¶

Можна поєднувати dataclasses з іншими моделями Pydantic, наслідувати їх, включати у власні моделі тощо.

Щоб дізнатися більше, перегляньте документацію Pydantic про dataclasses.

Версія¶

Доступно починаючи з версії FastAPI 0.67.0. 🔖

Використання dataclasses¶

Dataclasses у response_model¶

Dataclasses у вкладених структурах даних¶

Дізнатися більше¶

Версія¶

Dataclasses у `response_model`¶