Lidsky řečeno
Kuchař umí vařit, ale nechce běhat ke stolům. Číšník vezme objednávku, ověří, že to jídlo je na lístku, předá ji do kuchyně a přinese talíř. Když si host objedná něco, co neexistuje, kuchař se o tom vůbec nedozví. FastAPI je ten číšník. Tvoje funkce jsou kuchaři a jídelní lístek si číšník napíše sám podle nich.
Proč vůbec framework
V lekci HTTP a návrh REST API jsi viděl, z čeho se skládá požadavek: metoda, cesta, parametry, hlavičky a tělo. Každý koncový bod (anglicky endpoint, jedna adresa s jednou metodou) musí udělat pořád totéž: rozebrat adresu, převést text na čísla, zkontrolovat data, poslat srozumitelnou chybu a výsledek převést na JSON.
FastAPI je knihovna, která tuhle rutinu odvodí z typů, které u funkce stejně píšeš. Instalace do virtuálního prostředí:
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install "fastapi[standard]"Celá první aplikace:
from fastapi import FastAPI
app = FastAPI(title="Úkolníček")
@app.get("/health")
def health() -> dict[str, str]:
return {"status": "ok"}
@app.get("/tasks/{task_id}")
def read_task(task_id: int, detail: bool = False) -> dict[str, object]:
return {"id": task_id, "detail": detail}Spustíš ji vývojovým serverem, který se po každé změně souboru sám restartuje:
fastapi dev main.pyNa http://127.0.0.1:8000/docs teď najdeš interaktivní dokumentaci, kde jde každý endpoint rovnou vyzkoušet. Nenapsal jsi pro ni ani řádek. A takhle se server chová:
| Požadavek | Odpověď |
|---|---|
GET /tasks/7 | 200 a {"id": 7, "detail": false} |
GET /tasks/7?detail=true | 200 a {"id": 7, "detail": true} |
GET /tasks/sedm | 422, protože sedm není celé číslo |
GET /neexistuje | 404 |
Pravidlo, odkud se hodnota vezme, je jednoduché:
- Jméno je v cestě ve složených závorkách: parametr cesty.
- Jednoduchý typ, který v cestě není: query parametr za otazníkem. S výchozí hodnotou je nepovinný.
- Třída odvozená od
BaseModel: tělo požadavku v JSONu.
Co se děje uvnitř
Kouzlo se líp chápe, když si ho napíšeš sám. Následujících pár desítek řádků je zmenšenina toho, co FastAPI dělá: dekorátor si funkci zapamatuje, inspect.signature přečte její parametry a typy a podle nich se text z adresy převede.
import inspect
import json
from urllib.parse import parse_qsl, urlsplit
def convert(raw, target):
if target is bool:
word = raw.lower()
if word in {"1", "true", "yes", "on"}:
return True
if word in {"0", "false", "no", "off"}:
return False
raise ValueError(raw)
return target(raw)
def match_path(pattern, path):
want = pattern.strip("/").split("/")
got = path.strip("/").split("/")
if len(want) != len(got):
return None
params = {}
for expected, actual in zip(want, got):
if expected.startswith("{"):
params[expected[1:-1]] = actual
elif expected != actual:
return None
return params
class MiniAPI:
def __init__(self):
self.routes = []
def get(self, pattern):
def register(func):
self.routes.append((pattern, func))
return func
return register
def call(self, func, raw_values):
kwargs, errors = {}, []
for name, param in inspect.signature(func).parameters.items():
if name in raw_values:
try:
kwargs[name] = convert(raw_values[name], param.annotation)
except ValueError:
errors.append({"loc": name, "msg": "špatný typ"})
elif param.default is inspect.Parameter.empty:
errors.append({"loc": name, "msg": "chybí"})
if errors:
return 422, {"detail": errors}
return 200, func(**kwargs)
def handle(self, url):
parts = urlsplit(url)
for pattern, func in self.routes:
params = match_path(pattern, parts.path)
if params is not None:
return self.call(func, dict(parse_qsl(parts.query)) | params)
return 404, {"detail": "Not Found"}
app = MiniAPI()
@app.get("/tasks/{task_id}")
def read_task(task_id: int, detail: bool = False):
return {"id": task_id, "detail": detail}
for url in ["/tasks/7", "/tasks/7?detail=true", "/tasks/sedm", "/nic"]:
status, body = app.handle(url)
print(status, json.dumps(body, ensure_ascii=False))
200 {"id": 7, "detail": false}
200 {"id": 7, "detail": true}
422 {"detail": [{"loc": "task_id", "msg": "špatný typ"}]}
404 {"detail": "Not Found"}Všimni si dvou věcí. Funkce read_task nedostane špatná data, protože se k ní vůbec nedostanou. A bool potřebuje zvláštní zacházení, protože bool("false") je v Pythonu True: každý neprázdný text je pravdivý.
Napiš párování cest
Doplň funkci match_path(pattern, path). Vrátí slovník parametrů, když cesta odpovídá vzoru, jinak None. Vzor /users/{uid}/tasks/{tid} a cesta /users/5/tasks/9 dají {"uid": "5", "tid": "9"}. Vzor bez parametrů, který sedí, dá prázdný slovník. Lomítko na začátku a na konci nehraje roli.
def match_path(pattern, path):
# doplň
return None
Klient pošle GET /tasks/abc a funkce má task_id: int. Co se stane?
Validace proběhne před voláním funkce. Trasa sice sedí, ale hodnota neprojde typem, a to FastAPI hlásí stavem 422.
Pod kapotou · ASGI: co je pod FastAPI
FastAPI stojí na Starlette (směrování, požadavky, odpovědi) a Pydanticu (validace, jehož jádro je v Rustu). Server, typicky Uvicorn, s aplikací mluví protokolem ASGI: aplikace je asynchronní funkce se třemi argumenty. Žádná magie, jde to zavolat ručně, a přesně takhle se dají psát middlewary bez závislosti na frameworku.
import asyncio
import json
async def app(scope, receive, send):
body = json.dumps({"path": scope["path"]}).encode()
await send({
"type": "http.response.start",
"status": 200,
"headers": [(b"content-type", b"application/json")],
})
await send({"type": "http.response.body", "body": body})
async def fake_server():
async def receive():
return {"type": "http.request", "body": b"", "more_body": False}
async def send(message):
print(message["type"], message.get("status", message.get("body")))
await app({"type": "http", "method": "GET", "path": "/ahoj"}, receive, send)
asyncio.run(fake_server())
http.response.start 200
http.response.body b'{"path": "/ahoj"}'Důsledek pro návrh: analýza signatur a stavba validátorů proběhne při registraci tras, tedy při importu. Za běhu se už jen vyhodnocují hotové validátory. Pomalý start velké aplikace proto často neznamená pomalé požadavky. A pozor na meze: FastAPI ani Uvicorn samy neomezují velikost těla požadavku, to je práce reverzní proxy nebo vlastního ASGI middlewaru.
Data v těle: Pydantic
Query parametry stačí na filtrování. Když klient něco vytváří, pošle JSON v těle. Jeho tvar popíšeš třídou odvozenou od BaseModel z knihovny Pydantic. Vypadá jako dataclass, ale při vytvoření data opravdu kontroluje.
from pydantic import BaseModel, Field, ValidationError
class TaskCreate(BaseModel):
title: str = Field(min_length=1, max_length=200)
priority: int = Field(default=3, ge=1, le=5)
done: bool = False
task = TaskCreate.model_validate({"title": "Koupit mléko", "priority": "2"})
print(task)
print(task.model_dump())
try:
TaskCreate.model_validate({"title": "", "priority": 9})
except ValidationError as error:
for item in error.errors():
print(item["loc"], item["type"])
title='Koupit mléko' priority=2 done=False
{'title': 'Koupit mléko', 'priority': 2, 'done': False}
('title',) string_too_short
('priority',) less_than_equalge znamená „větší nebo rovno“, le „menší nebo rovno“. Text "2" se převedl na číslo, protože Pydantic ve výchozím režimu rozumné převody dělá. Chyby nesbírá po jedné: nahlásí všechny najednou, takže klient opraví formulář na jeden pokus.
Model registrace
Doplň model Registrace:
username: text o délce 3 až 20 znaků, jen malá písmena bez diakritiky, číslice a podtržítko,age: celé číslo, nejméně 18,newsletter: logická hodnota, výchozíFalse,- neznámá pole se mají odmítnout. Nastav to přes
model_config = ConfigDict(extra="forbid").
from pydantic import BaseModel, ConfigDict, Field
class Registrace(BaseModel):
username: str
age: int
Tady je úplné API nad pamětí. Stavový kód 201 znamená „vytvořeno“, 204 „hotovo a nic nevracím“. Návratový typ není jen ozdoba: FastAPI podle něj odpověď zkontroluje, odfiltruje pole navíc a popíše ji v dokumentaci.
from itertools import count
from typing import Annotated
from fastapi import FastAPI, HTTPException, Query, status
from pydantic import BaseModel, Field
app = FastAPI(title="Úkolníček")
class TaskCreate(BaseModel):
title: str = Field(min_length=1, max_length=200)
priority: int = Field(default=3, ge=1, le=5)
class TaskPatch(BaseModel):
title: str | None = Field(default=None, min_length=1, max_length=200)
priority: int | None = Field(default=None, ge=1, le=5)
class TaskOut(TaskCreate):
id: int
tasks: dict[int, TaskOut] = {}
ids = count(1)
def find_task(task_id: int) -> TaskOut:
task = tasks.get(task_id)
if task is None:
raise HTTPException(status.HTTP_404_NOT_FOUND, "Úkol neexistuje")
return task
@app.post("/tasks", status_code=status.HTTP_201_CREATED)
def create_task(payload: TaskCreate) -> TaskOut:
task = TaskOut(id=next(ids), **payload.model_dump())
tasks[task.id] = task
return task
@app.get("/tasks")
def list_tasks(
limit: Annotated[int, Query(ge=1, le=100)] = 20,
offset: Annotated[int, Query(ge=0)] = 0,
) -> list[TaskOut]:
return list(tasks.values())[offset : offset + limit]
@app.get("/tasks/{task_id}")
def read_task(task_id: int) -> TaskOut:
return find_task(task_id)
@app.patch("/tasks/{task_id}")
def update_task(task_id: int, payload: TaskPatch) -> TaskOut:
changes = payload.model_dump(exclude_unset=True)
task = find_task(task_id).model_copy(update=changes)
tasks[task_id] = task
return task
@app.delete("/tasks/{task_id}", status_code=status.HTTP_204_NO_CONTENT)
def delete_task(task_id: int) -> None:
find_task(task_id)
del tasks[task_id]exclude_unset=True vrátí jen pole, která klient opravdu poslal. Díky tomu PATCH pozná rozdíl mezi „titulek neměň“ a „titulek jsem poslal“.
Pod kapotou · kudy uniká, co nemělo
Filtrování podle návratového typu platí, jen když vracíš data. Když vrátíš přímo JSONResponse, validace odpovědi se přeskočí a pole navíc odejdou klientovi. Pokud funkce vrací bohatší objekt, než chceš ukázat, použij response_model=UserOut: má přednost před anotací a mypy zůstane spokojený.
@app.get("/me", response_model=UserOut)
def me() -> UserInDb:
return load_current_user()U model_copy(update=...) si dej pozor, že hodnoty se nevalidují. Ukázka výše na to má slabé místo: klient může poslat "title": null, typ str | None to pustí, exclude_unset pole nechá a do úkolu se zapíše None, přestože TaskOut slibuje text. Hotová instance se při výstupu ve výchozím nastavení Pydanticu znovu nevaliduje (revalidate_instances="never"), takže taková hodnota může dojít až ke klientovi. V produkci to řeš validátorem, nebo pole s None z changes vyřaď. U modelů pro PATCH mají „chybí“ a „null“ opravdu dva různé významy.
Databáze a závislosti
Skoro každý endpoint potřebuje totéž: připojení k databázi, přihlášeného uživatele, nastavení. Místo opakování řekneš, co funkce potřebuje, a framework jí to dodá. Říká se tomu vkládání závislostí (dependency injection). Znovu zmenšenina, tentokrát jde o mechanismus Depends:
import inspect
class Depends:
def __init__(self, provider):
self.provider = provider
def call_with_deps(func, overrides, cache, cleanups):
kwargs = {}
for name, param in inspect.signature(func).parameters.items():
if isinstance(param.default, Depends):
wanted = param.default.provider
provider = overrides.get(wanted, wanted)
if provider not in cache:
cache[provider] = call_with_deps(provider, overrides, cache, cleanups)
kwargs[name] = cache[provider]
result = func(**kwargs)
if inspect.isgenerator(result):
cleanups.append(result)
return next(result)
return result
def run_request(func, overrides=None):
cleanups = []
try:
return call_with_deps(func, overrides or {}, {}, cleanups)
finally:
for generator in reversed(cleanups):
next(generator, None)
def get_db():
print("otevírám databázi")
yield "spojení"
print("zavírám databázi")
def get_user(db=Depends(get_db)):
print("hledám uživatele přes", db)
return "Eva"
def endpoint(user=Depends(get_user), db=Depends(get_db)):
print("obsluhuji", user, "přes", db)
return {"user": user}
print(run_request(endpoint))
print("--- v testu podstrčíme uživatele")
print(run_request(endpoint, {get_user: lambda: "Testovací Tom"}))
otevírám databázi
hledám uživatele přes spojení
obsluhuji Eva přes spojení
zavírám databázi
{'user': 'Eva'}
--- v testu podstrčíme uživatele
otevírám databázi
obsluhuji Testovací Tom přes spojení
zavírám databázi
{'user': 'Testovací Tom'}Databáze se otevřela jednou, přestože ji chtěly dvě funkce: v rámci jednoho požadavku se výsledek závislosti pamatuje. Kód za yield je úklid a běží i při chybě. A slovník overrides je přesně to, co ti ve FastAPI umožní v testech vyměnit skutečnou závislost za falešnou.
Ve skutečném FastAPI s sqlite3 to vypadá takhle. Alias přes Annotated ušetří opakování:
import sqlite3
from collections.abc import AsyncIterator, Iterator
from contextlib import asynccontextmanager
from typing import Annotated
from fastapi import Depends, FastAPI, HTTPException, status
from pydantic import BaseModel, Field
DB_PATH = "tasks.db"
SCHEMA = """
CREATE TABLE IF NOT EXISTS tasks (
id INTEGER PRIMARY KEY,
title TEXT NOT NULL,
priority INTEGER NOT NULL
);
"""
@asynccontextmanager
async def lifespan(app: FastAPI) -> AsyncIterator[None]:
conn = sqlite3.connect(DB_PATH) # runs once at startup
conn.executescript(SCHEMA)
conn.close()
yield # the app serves requests here
app = FastAPI(title="Úkolníček", lifespan=lifespan)
def get_db() -> Iterator[sqlite3.Connection]:
# FastAPI may run this and the endpoint in different threads.
conn = sqlite3.connect(DB_PATH, check_same_thread=False)
conn.row_factory = sqlite3.Row
try:
yield conn
conn.commit()
except Exception:
conn.rollback()
raise
finally:
conn.close()
Db = Annotated[sqlite3.Connection, Depends(get_db)]
class TaskCreate(BaseModel):
title: str = Field(min_length=1, max_length=200)
priority: int = Field(default=3, ge=1, le=5)
class TaskOut(TaskCreate):
id: int
@app.post("/tasks", status_code=status.HTTP_201_CREATED)
def create_task(payload: TaskCreate, db: Db) -> TaskOut:
cursor = db.execute(
"INSERT INTO tasks (title, priority) VALUES (?, ?)",
(payload.title, payload.priority),
)
return TaskOut(id=cursor.lastrowid, **payload.model_dump())
@app.get("/tasks/{task_id}")
def read_task(task_id: int, db: Db) -> TaskOut:
row = db.execute(
"SELECT id, title, priority FROM tasks WHERE id = ?", (task_id,)
).fetchone()
if row is None:
raise HTTPException(status.HTTP_404_NOT_FOUND, "Úkol neexistuje")
return TaskOut(**dict(row))lifespan je kód, který běží jednou při startu (před yield) a jednou při vypnutí (za ním). Hodí se pro přípravu schématu, načtení modelu nebo vytvoření sdíleného klienta. Otazníky v SQL znáš z lekce SQL a sqlite3: hodnoty se nikdy nelepí do textu dotazu.
Pod kapotou · závislosti s yield v praxi
Vlákna. Synchronní závislost i synchronní endpoint jdou do poolu vláken, každý zvlášť, klidně do jiného vlákna. Výchozí check_same_thread=True by proto náhodně házelo ProgrammingError. Vypnutí je tady bezpečné, protože spojení patří jednomu požadavku a nikdo ho nepoužívá souběžně.
Čas úklidu. Kdy přesně běží kód za yield vzhledem k odeslání odpovědi, se mezi verzemi FastAPI měnilo (změny přinesly verze 0.106 a 0.118). U běžné JSON odpovědi to nepoznáš. U StreamingResponse, který čte z databáze, na tom závisí, jestli je spojení ještě otevřené. Ověř si chování ve své verzi a v release notes.
Commit a odpověď. Když conn.commit() běží až po vytvoření odpovědi a selže, klient už mohl dostat 201 na zápis, který neexistuje. Kde na tom záleží, commituj explicitně uvnitř endpointu nebo service vrstvy, než odpověď vrátíš.
Cache. Výsledek se pamatuje v rámci požadavku podle funkce. Depends(get_x, use_cache=False) to vypne. Parametrizovaná závislost jako třída s __call__ se klíčuje podle instance, takže dvě různé instance se volají zvlášť.
Chyby: doména nemá znát HTTP
HTTPException je pohodlná, ale patří jen do vrstvy API. Funkce, která počítá nebo ukládá, by neměla vědět, že existuje stav 404. Jinak ji nepůjde použít z příkazové řádky ani z fronty úloh. Doména vyhodí vlastní výjimku a jedno místo ji přeloží:
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
app = FastAPI()
class TaskNotFound(Exception):
pass
@app.exception_handler(TaskNotFound)
def task_not_found(request: Request, error: TaskNotFound) -> JSONResponse:
return JSONResponse(status_code=404, content={"detail": "Úkol neexistuje"})Překlad výjimek na odpovědi
Napiš to_http(func, *args). Zavolá func(*args) a vrátí dvojici (stav, tělo):
- bez chyby
(200, výsledek), TaskNotFounddá(404, {"detail": "Úkol neexistuje"}),TaskConflictdá(409, {"detail": "Úkol už existuje"}),- jakákoli jiná výjimka dá
(500, {"detail": "Interní chyba"}). Text původní výjimky do odpovědi nepatří, mohou v něm být citlivé údaje.
class TaskNotFound(Exception):
pass
class TaskConflict(Exception):
pass
tasks = {1: "Koupit mléko"}
def get_task(task_id):
if task_id not in tasks:
raise TaskNotFound(task_id)
return {"id": task_id, "title": tasks[task_id]}
def add_task(task_id, title):
if task_id in tasks:
raise TaskConflict(task_id)
tasks[task_id] = title
return {"id": task_id, "title": title}
def to_http(func, *args):
return 200, func(*args)
Jaký stav FastAPI vrátí, když tělo požadavku neodpovídá modelu Pydantic?
Výchozí odpověď na neplatná data je 422 se seznamem chyb. Pokud tvé API potřebuje jiný formát, přepíšeš handler pro RequestValidationError.
def, nebo async def
FastAPI přijme obojí a rozdíl je podstatný.
defse spustí ve vlákně z připraveného poolu. Může v klidu čekat na databázi nebo soubor.async defběží přímo ve smyčce událostí, kterou sdílí všechny požadavky. Tam se smí čekat jen přesawait.
Co se stane, když v async def zavoláš něco blokujícího, ukáže tenhle pokus. time.sleep nepustí k slovu nikoho dalšího, asyncio.sleep ano.
import asyncio
import time
async def blocking(log):
log.append("blokující začátek")
time.sleep(0.05)
log.append("blokující konec")
async def polite(log):
log.append("slušný začátek")
await asyncio.sleep(0.05)
log.append("slušný konec")
async def other_request(log):
log.append("jiný požadavek obsloužen")
async def main():
for handler in (blocking, polite):
log = []
await asyncio.gather(handler(log), other_request(log))
print(log)
asyncio.run(main())
['blokující začátek', 'blokující konec', 'jiný požadavek obsloužen'] ['slušný začátek', 'jiný požadavek obsloužen', 'slušný konec']
Lidsky řečeno
Smyčka událostí je jeden číšník na celou restauraci. Zvládne desítky stolů, protože u žádného nestojí a nečeká. Když si ale jeden host řekne, ať číšník počká, než dočte jídelní lístek, a ten opravdu čeká, všichni ostatní hladoví. await znamená „zavolej mě, až bude host hotový, a běž zatím jinam“.
Praktické pravidlo: používáš-li sqlite3, requests nebo jiné blokující knihovny, piš obyčejné def. async def použij, když všechno, na co čekáš, má asynchronní verzi, například httpx.AsyncClient.
Pod kapotou · pool vláken a výpočty
Synchronní handlery jdou přes anyio.to_thread s výchozím limitem 40 souběžných vláken. Když jsou všechna obsazená pomalým I/O, další požadavky čekají, i když CPU nic nedělá. Latence pak skočí bez jediné chyby v logu, proto měř čekání, ne jen dobu handleru.
Výpočetně náročná práce nepomůže ani ve vlákně, protože ve standardním buildu CPythonu 3.12 drží GIL. Patří do procesu (ProcessPoolExecutor) nebo do fronty s workerem. BackgroundTasks z FastAPI běží v tom samém procesu po odeslání odpovědi: při pádu nebo restartu se ztratí, takže na nic, co se musí stát, nejsou vhodné.
Z async def zavoláš blokující kód přes await run_in_threadpool(func, arg) ze starlette.concurrency, případně standardním asyncio.to_thread.
Endpoint volá requests.get(...) a nic asynchronního nepoužívá. Jak ho napsat?
V async def by blokující requests.get zastavil všechny ostatní požadavky v procesu.
Testy bez serveru
TestClient volá aplikaci přímo, bez sítě a bez spuštěného Uvicornu. Díky dependency_overrides dostane test vlastní databázi v paměti. Je potřeba balík httpx, který fastapi[standard] přináší.
import sqlite3
import pytest
from fastapi.testclient import TestClient
from main import SCHEMA, app, get_db
@pytest.fixture
def client():
conn = sqlite3.connect(":memory:", check_same_thread=False)
conn.row_factory = sqlite3.Row
conn.executescript(SCHEMA)
def override_db():
yield conn
app.dependency_overrides[get_db] = override_db
yield TestClient(app)
app.dependency_overrides.clear()
conn.close()
def test_create_and_read(client):
created = client.post("/tasks", json={"title": "Napsat test"})
assert created.status_code == 201
task_id = created.json()["id"]
response = client.get(f"/tasks/{task_id}")
assert response.status_code == 200
assert response.json()["title"] == "Napsat test"
def test_empty_title_is_rejected(client):
response = client.post("/tasks", json={"title": ""})
assert response.status_code == 422
def test_missing_task(client):
assert client.get("/tasks/999").status_code == 404TestClient(app) bez with nespustí lifespan, takže test na ostrý soubor tasks.db nesáhne. Když chceš otestovat i start aplikace, napiš with TestClient(app) as client:.
Mimo vývoj se aplikace spouští bez automatického restartu:
fastapi run main.py --port 8000
# nebo přímo serverem
uvicorn main:app --host 0.0.0.0 --port 8000Jak ji zabalit a dostat na server, je obsah další lekce, Docker a CI/CD.