Body - Вложенные модели¶

С помощью FastAPI, вы можете определять, валидировать, документировать и использовать модели произвольной вложенности (благодаря библиотеке Pydantic).

Определение полей содержащих списки¶

Вы можете определять атрибут как подтип. Например, тип list в Python:

Python 3.10+

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None
    tags: list = []


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    results = {"item_id": item_id, "item": item}
    return results

🤓 Other versions and variants

Python 3.8+

from typing import Union

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None
    tags: list = []


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    results = {"item_id": item_id, "item": item}
    return results

Это приведёт к тому, что обьект tags преобразуется в список, несмотря на то что тип его элементов не объявлен.

Определение полей содержащих список с определением типов его элементов¶

Однако в Python есть способ объявления списков с указанием типов для вложенных элементов:

Импортируйте `List` из модуля typing¶

В Python 3.9 и выше вы можете использовать стандартный тип list для объявления аннотаций типов, как мы увидим ниже. 💡

Но в версиях Python до 3.9 (начиная с 3.6) сначала вам необходимо импортировать List из стандартного модуля typing в Python:

Python 3.8+

from typing import List, Union

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None
    tags: List[str] = []


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    results = {"item_id": item_id, "item": item}
    return results

🤓 Other versions and variants

Python 3.10+Python 3.9+

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None
    tags: list[str] = []


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    results = {"item_id": item_id, "item": item}
    return results

from typing import Union

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None
    tags: list[str] = []


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    results = {"item_id": item_id, "item": item}
    return results

Объявление `list` с указанием типов для вложенных элементов¶

Объявление типов для элементов (внутренних типов) вложенных в такие типы как list, dict, tuple:

Если у вас Python версии ниже чем 3.9, импортируйте их аналог из модуля typing
Передайте внутренний(ие) тип(ы) как "параметры типа", используя квадратные скобки: [ и ]

В Python версии 3.9 это будет выглядеть так:

my_list: list[str]

В версиях Python до 3.9 это будет выглядеть так:

from typing import List

my_list: List[str]

Это всё стандартный синтаксис Python для объявления типов.

Используйте этот же стандартный синтаксис для атрибутов модели с внутренними типами.

Таким образом, в нашем примере мы можем явно указать тип данных для поля tags как "список строк":

Python 3.10+

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None
    tags: list[str] = []


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    results = {"item_id": item_id, "item": item}
    return results

🤓 Other versions and variants

Python 3.9+Python 3.8+

from typing import Union

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None
    tags: list[str] = []


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    results = {"item_id": item_id, "item": item}
    return results

from typing import List, Union

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None
    tags: List[str] = []


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    results = {"item_id": item_id, "item": item}
    return results

Типы множеств¶

Но затем мы подумали и поняли, что теги не должны повторяться и, вероятно, они должны быть уникальными строками.

И в Python есть специальный тип данных для множеств уникальных элементов - set.

Тогда мы можем обьявить поле tags как множество строк:

Python 3.10+

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None
    tags: set[str] = set()


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    results = {"item_id": item_id, "item": item}
    return results

🤓 Other versions and variants

Python 3.9+Python 3.8+

from typing import Union

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None
    tags: set[str] = set()


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    results = {"item_id": item_id, "item": item}
    return results

from typing import Set, Union

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None
    tags: Set[str] = set()


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    results = {"item_id": item_id, "item": item}
    return results

С помощью этого, даже если вы получите запрос с повторяющимися данными, они будут преобразованы в множество уникальных элементов.

И когда вы выводите эти данные, даже если исходный набор содержал дубликаты, они будут выведены в виде множества уникальных элементов.

И они также будут соответствующим образом аннотированы / задокументированы.

Вложенные Модели¶

У каждого атрибута Pydantic-модели есть тип.

Но этот тип может сам быть другой моделью Pydantic.

Таким образом вы можете объявлять глубоко вложенные JSON "объекты" с определёнными именами атрибутов, типами и валидацией.

Всё это может быть произвольно вложенным.

Определение подмодели¶

Например, мы можем определить модель Image:

Python 3.10+

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Image(BaseModel):
    url: str
    name: str


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None
    tags: set[str] = set()
    image: Image | None = None


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    results = {"item_id": item_id, "item": item}
    return results

🤓 Other versions and variants

Python 3.9+Python 3.8+

from typing import Union

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Image(BaseModel):
    url: str
    name: str


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None
    tags: set[str] = set()
    image: Union[Image, None] = None


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    results = {"item_id": item_id, "item": item}
    return results

from typing import Set, Union

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Image(BaseModel):
    url: str
    name: str


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None
    tags: Set[str] = set()
    image: Union[Image, None] = None


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    results = {"item_id": item_id, "item": item}
    return results

Использование вложенной модели в качестве типа¶

Также мы можем использовать эту модель как тип атрибута:

Python 3.10+

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Image(BaseModel):
    url: str
    name: str


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None
    tags: set[str] = set()
    image: Image | None = None


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    results = {"item_id": item_id, "item": item}
    return results

🤓 Other versions and variants

Python 3.9+Python 3.8+

from typing import Union

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Image(BaseModel):
    url: str
    name: str


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None
    tags: set[str] = set()
    image: Union[Image, None] = None


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    results = {"item_id": item_id, "item": item}
    return results

from typing import Set, Union

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Image(BaseModel):
    url: str
    name: str


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None
    tags: Set[str] = set()
    image: Union[Image, None] = None


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    results = {"item_id": item_id, "item": item}
    return results

Это означает, что FastAPI будет ожидать тело запроса, аналогичное этому:

{
    "name": "Foo",
    "description": "The pretender",
    "price": 42.0,
    "tax": 3.2,
    "tags": ["rock", "metal", "bar"],
    "image": {
        "url": "http://example.com/baz.jpg",
        "name": "The Foo live"
    }
}

Ещё раз: сделав такое объявление, с помощью FastAPI вы получите:

Поддержку редакторов IDE (автодополнение и т.д), даже для вложенных моделей
Преобразование данных
Валидацию данных
Автоматическую документацию

Особые типы и валидация¶

Помимо обычных простых типов, таких как str, int, float, и т.д. Вы можете использовать более сложные базовые типы, которые наследуются от типа str.

Чтобы увидеть все варианты, которые у вас есть, ознакомьтесь с документацией по необычным типам Pydantic. Вы увидите некоторые примеры в следующей главе.

Например, так как в модели Image у нас есть поле url, то мы можем объявить его как тип HttpUrl из модуля Pydantic вместо типа str:

Python 3.10+

from fastapi import FastAPI
from pydantic import BaseModel, HttpUrl

app = FastAPI()


class Image(BaseModel):
    url: HttpUrl
    name: str


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None
    tags: set[str] = set()
    image: Image | None = None


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    results = {"item_id": item_id, "item": item}
    return results

🤓 Other versions and variants

Python 3.9+Python 3.8+

from typing import Union

from fastapi import FastAPI
from pydantic import BaseModel, HttpUrl

app = FastAPI()


class Image(BaseModel):
    url: HttpUrl
    name: str


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None
    tags: set[str] = set()
    image: Union[Image, None] = None


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    results = {"item_id": item_id, "item": item}
    return results

from typing import Set, Union

from fastapi import FastAPI
from pydantic import BaseModel, HttpUrl

app = FastAPI()


class Image(BaseModel):
    url: HttpUrl
    name: str


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None
    tags: Set[str] = set()
    image: Union[Image, None] = None


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    results = {"item_id": item_id, "item": item}
    return results

Строка будет проверена на соответствие допустимому URL-адресу и задокументирована в JSON схему / OpenAPI.

Атрибуты, содержащие списки подмоделей¶

Вы также можете использовать модели Pydantic в качестве типов вложенных в list, set и т.д:

Python 3.10+

from fastapi import FastAPI
from pydantic import BaseModel, HttpUrl

app = FastAPI()


class Image(BaseModel):
    url: HttpUrl
    name: str


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None
    tags: set[str] = set()
    images: list[Image] | None = None


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    results = {"item_id": item_id, "item": item}
    return results

🤓 Other versions and variants

Python 3.9+Python 3.8+

from typing import Union

from fastapi import FastAPI
from pydantic import BaseModel, HttpUrl

app = FastAPI()


class Image(BaseModel):
    url: HttpUrl
    name: str


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None
    tags: set[str] = set()
    images: Union[list[Image], None] = None


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    results = {"item_id": item_id, "item": item}
    return results

from typing import List, Set, Union

from fastapi import FastAPI
from pydantic import BaseModel, HttpUrl

app = FastAPI()


class Image(BaseModel):
    url: HttpUrl
    name: str


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None
    tags: Set[str] = set()
    images: Union[List[Image], None] = None


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    results = {"item_id": item_id, "item": item}
    return results

Такая реализация будет ожидать (конвертировать, валидировать, документировать и т.д) JSON-содержимое в следующем формате:

{
    "name": "Foo",
    "description": "The pretender",
    "price": 42.0,
    "tax": 3.2,
    "tags": [
        "rock",
        "metal",
        "bar"
    ],
    "images": [
        {
            "url": "http://example.com/baz.jpg",
            "name": "The Foo live"
        },
        {
            "url": "http://example.com/dave.jpg",
            "name": "The Baz"
        }
    ]
}

Информация

Заметьте, что теперь у ключа images есть список объектов изображений.

Глубоко вложенные модели¶

Вы можете определять модели с произвольным уровнем вложенности:

Python 3.10+

from fastapi import FastAPI
from pydantic import BaseModel, HttpUrl

app = FastAPI()


class Image(BaseModel):
    url: HttpUrl
    name: str


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None
    tags: set[str] = set()
    images: list[Image] | None = None


class Offer(BaseModel):
    name: str
    description: str | None = None
    price: float
    items: list[Item]


@app.post("/offers/")
async def create_offer(offer: Offer):
    return offer

🤓 Other versions and variants

Python 3.9+Python 3.8+

from typing import Union

from fastapi import FastAPI
from pydantic import BaseModel, HttpUrl

app = FastAPI()


class Image(BaseModel):
    url: HttpUrl
    name: str


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None
    tags: set[str] = set()
    images: Union[list[Image], None] = None


class Offer(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    items: list[Item]


@app.post("/offers/")
async def create_offer(offer: Offer):
    return offer

from typing import List, Set, Union

from fastapi import FastAPI
from pydantic import BaseModel, HttpUrl

app = FastAPI()


class Image(BaseModel):
    url: HttpUrl
    name: str


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None
    tags: Set[str] = set()
    images: Union[List[Image], None] = None


class Offer(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    items: List[Item]


@app.post("/offers/")
async def create_offer(offer: Offer):
    return offer

Информация

Заметьте, что у объекта Offer есть список объектов Item, которые, в свою очередь, могут содержать необязательный список объектов Image

Тела с чистыми списками элементов¶

Если верхний уровень значения тела JSON-объекта представляет собой JSON array (в Python - list), вы можете объявить тип в параметре функции, так же, как в моделях Pydantic:

images: List[Image]

в Python 3.9 и выше:

images: list[Image]

например так:

Python 3.9+

from fastapi import FastAPI
from pydantic import BaseModel, HttpUrl

app = FastAPI()


class Image(BaseModel):
    url: HttpUrl
    name: str


@app.post("/images/multiple/")
async def create_multiple_images(images: list[Image]):
    return images

🤓 Other versions and variants

Python 3.8+

from typing import List

from fastapi import FastAPI
from pydantic import BaseModel, HttpUrl

app = FastAPI()


class Image(BaseModel):
    url: HttpUrl
    name: str


@app.post("/images/multiple/")
async def create_multiple_images(images: List[Image]):
    return images

Универсальная поддержка редактора¶

И вы получаете поддержку редактора везде.

Даже для элементов внутри списков:

Вы не могли бы получить такую поддержку редактора, если бы работали напрямую с dict, а не с моделями Pydantic.

Но вы также не должны беспокоиться об этом, входящие словари автоматически конвертируются, а ваш вывод также автоматически преобразуется в формат JSON.

Тела запросов с произвольными словарями (`dict` )¶

Вы также можете объявить тело запроса как dict с ключами определенного типа и значениями другого типа данных.

Без необходимости знать заранее, какие значения являются допустимыми для имён полей/атрибутов (как это было бы в случае с моделями Pydantic).

Это было бы полезно, если вы хотите получить ключи, которые вы еще не знаете.

Другой полезный случай - когда вы хотите чтобы ключи были другого типа данных, например, int.

Именно это мы сейчас и увидим здесь.

В этом случае вы принимаете dict, пока у него есть ключи типа int со значениями типа float:

Python 3.9+

from fastapi import FastAPI

app = FastAPI()


@app.post("/index-weights/")
async def create_index_weights(weights: dict[int, float]):
    return weights

🤓 Other versions and variants

Python 3.8+

from typing import Dict

from fastapi import FastAPI

app = FastAPI()


@app.post("/index-weights/")
async def create_index_weights(weights: Dict[int, float]):
    return weights

Совет

Имейте в виду, что JSON поддерживает только ключи типа str.

Но Pydantic обеспечивает автоматическое преобразование данных.

Это значит, что даже если пользователи вашего API могут отправлять только строки в качестве ключей, при условии, что эти строки содержат целые числа, Pydantic автоматический преобразует и валидирует эти данные.

А dict, с именем weights, который вы получите в качестве ответа Pydantic, действительно будет иметь ключи типа int и значения типа float.

Резюме¶

С помощью FastAPI вы получаете максимальную гибкость, предоставляемую моделями Pydantic, сохраняя при этом простоту, краткость и элегантность вашего кода.

И дополнительно вы получаете:

Поддержку редактора (автодополнение доступно везде!)
Преобразование данных (также известно как парсинг / сериализация)
Валидацию данных
Документацию схемы данных
Автоматическую генерацию документации

Body - Вложенные модели¶

Определение полей содержащих списки¶

Определение полей содержащих список с определением типов его элементов¶

Импортируйте List из модуля typing¶

Объявление list с указанием типов для вложенных элементов¶

Типы множеств¶

Вложенные Модели¶

Определение подмодели¶

Использование вложенной модели в качестве типа¶

Особые типы и валидация¶

Атрибуты, содержащие списки подмоделей¶

Глубоко вложенные модели¶

Тела с чистыми списками элементов¶

Универсальная поддержка редактора¶

Тела запросов с произвольными словарями (dict )¶

Резюме¶

Импортируйте `List` из модуля typing¶

Объявление `list` с указанием типов для вложенных элементов¶

Тела запросов с произвольными словарями (`dict` )¶