Тело запроса — вложенные модели¶
С FastAPI вы можете определять, валидировать, документировать и использовать сколь угодно глубоко вложенные модели (благодаря Pydantic).
Поля-списки¶
Вы можете определить атрибут как подтип. Например, Python list:
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
Это сделает tags списком, хотя тип элементов списка не объявлен.
Поля-списки с параметром типа¶
Но в Python есть специальный способ объявления списков с внутренними типами, или «параметрами типа»:
Объявление list с параметром типа¶
Чтобы объявить типы, имеющие параметры типа (внутренние типы), такие как list, dict, tuple,
передайте внутренний тип(ы) как «параметры типа», используя квадратные скобки: [ и ]
my_list: list[str]
Это стандартный синтаксис Python для объявления типов.
Используйте тот же стандартный синтаксис для атрибутов модели с внутренними типами.
Итак, в нашем примере мы можем сделать tags именно «списком строк»:
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
Типы-множества¶
Но затем мы подумаем и поймём, что теги не должны повторяться, скорее всего, это будут уникальные строки.
И в Python есть специальный тип данных для множеств уникальных элементов — set.
Тогда мы можем объявить tags как множество строк:
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
С этим, даже если вы получите запрос с дублирующимися данными, они будут преобразованы в множество уникальных элементов.
И всякий раз, когда вы выводите эти данные, даже если в источнике были дубликаты, они будут выведены как множество уникальных элементов.
И это также будет соответствующим образом аннотировано / задокументировано.
Вложенные модели¶
Каждый атрибут модели Pydantic имеет тип.
Но этот тип сам по себе может быть другой моделью Pydantic.
Таким образом, вы можете объявлять глубоко вложенные JSON «объекты» с конкретными именами атрибутов, типами и валидациями.
Всё это, произвольно вложенное.
Определение подмодели¶
Например, мы можем определить модель Image:
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
Использование подмодели как типа¶
И затем мы можем использовать её как тип атрибута:
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
Это будет означать, что 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 вы получаете:
- Поддержку редактора (автодополнение и т.д.), даже для вложенных моделей
- Преобразование данных
- Валидацию данных
- Автоматическую документацию
Специальные типы и валидация¶
Помимо обычных единичных типов, таких как str, int, float и т.д., вы можете использовать более сложные единичные типы, которые наследуются от str.
Чтобы увидеть все доступные вам варианты, ознакомьтесь с Обзором типов Pydantic. Некоторые примеры вы увидите в следующей главе.
Например, как в модели Image у нас есть поле url, мы можем объявить его как экземпляр HttpUrl из Pydantic вместо str:
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
Строка будет проверена на то, что она является допустимым URL, и задокументирована в JSON Schema / OpenAPI как таковая.
Атрибуты со списками подмоделей¶
Вы также можете использовать модели Pydantic как подтипы list, set и т.д.:
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
Это будет ожидать (преобразовывать, валидировать, документировать и т.д.) 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 содержит список объектов изображений.
Глубоко вложенные модели¶
Вы можете определять сколь угодно глубоко вложенные модели:
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
Примечание
Обратите внимание, что Offer содержит список Item, которые, в свою очередь, содержат необязательный список Image
Тела из чистых списков¶
Если значение верхнего уровня JSON-тела, которое вы ожидаете, является JSON array (Python list), вы можете объявить тип в параметре функции так же, как в моделях Pydantic:
images: list[Image]
как в:
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.
Но вам не нужно о них беспокоиться: входящие dict автоматически преобразуются, и ваш вывод также автоматически преобразуется в JSON.
Тела из произвольных dict¶
Вы также можете объявить тело как dict с ключами одного типа и значениями другого типа.
Таким образом, вам не нужно заранее знать, какими будут допустимые имена полей/атрибутов (как это было бы в случае с моделями Pydantic).
Это было бы полезно, если вы хотите принимать ключи, которые вы ещё не знаете.
Другой полезный случай — когда вы хотите иметь ключи другого типа (например, int).
Именно это мы здесь и рассмотрим.
В этом случае вы примете любой dict, если у него есть ключи int со значениями float:
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, фактически будет иметь ключи int и значения float.
Итог¶
С FastAPI вы получаете максимальную гибкость, предоставляемую моделями Pydantic, сохраняя при этом ваш код простым, коротким и элегантным.
Но со всеми преимуществами:
- Поддержка редактора (автодополнение повсюду!)
- Преобразование данных (также известное как парсинг / сериализация)
- Валидация данных
- Документирование схемы
- Автоматическая документация