Класс Annotated

Класс Annotated применяется для расширения стандартных аннотаций типов дополнительными метаданными. В FastAPI он используется для передачи параметров валидации и документации непосредственно в аннотацию типа, что делает код более лаконичным и читаемым. Первым параметром передаётся тип данных, а последующими - метаданные, такие как Query, Path, Body и другие.

Синтаксис

from typing import Annotated

Annotated[type, metadata1, metadata2, ...]

Пример

Давайте создадим простой маршрут с использованием Annotated для валидации query-параметра:

from typing import Annotated
from fastapi import FastAPI, Query

app = FastAPI()

@app.get('/items/')
def read_items(q: Annotated[str | None, Query(max_length=5)] = None):
	return {'q': q}

Результат выполнения кода для адреса /items/?q=abcde:

{"q": "abcde"}

Пример

Давайте применим Annotated для path-параметра с валидацией:

from typing import Annotated
from fastapi import FastAPI, Path

app = FastAPI()

@app.get('/user/{user_id}')
def read_user(user_id: Annotated[int, Path(gt=0, lt=1000)]):
	return {'user_id': user_id}

Результат выполнения кода для адреса /user/5:

{"user_id": 5}

Пример

Давайте используем Annotated с несколькими метаданными для тела запроса:

from typing import Annotated
from fastapi import FastAPI, Body
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
	name: str
	price: float

@app.post('/items/')
def create_item(item: Annotated[Item, Body(embed=True)]):
	return item

Результат выполнения кода при отправке JSON:

{"item": {"name": "article", "price": 10.5}}

Смотрите также

функция jsonable_encoder,
которая преобразует объекты в JSON-совместимые типы
параметр include,
который указывает поля для включения в результат
параметр exclude,
который указывает поля для исключения из результата
параметр exclude_none,
который исключает поля со значением None