Démarrage
Première API
FastAPI repose sur Starlette et Pydantic. uvicorn est le serveur ASGI. --reload active le rechargement automatique pendant le développement.
# install FastAPI and uvicorn
pip install fastapi uvicorn
# main.py
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
def read_root():
return {"Hello": "World"}
# run: uvicorn main:app --reloadLancer avec Uvicorn
L'instance d'app 'main:app' signifie module 'main', variable 'app'. Utilisez --reload uniquement en développement ; en production, lancez sans lui et utilisez un gestionnaire de processus.
# development with auto-reload
uvicorn main:app --reload
# specify host and port
uvicorn main:app --host 0.0.0.0 --port 8000
# run programmatically
import uvicorn
if __name__ == "__main__":
uvicorn.run("main:app", host="127.0.0.1", port=8000, reload=True)Opérations de chemin asynchrones
Vous pouvez déclarer les opérations de chemin avec 'def' (exécutées dans un threadpool) ou 'async def'. Utilisez async def quand la fonction fait des E/S via des bibliothèques asynchrones ; mélanger des appels bloquants dans async def bloquera la boucle d'événements.
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
async def read_root():
return {"message": "hello"}
@app.get("/sync")
def read_sync():
return {"message": "sync also works"}
# use async when calling async libs (httpx, databases)
@app.get("/data")
async def fetch_data():
import httpx
async with httpx.AsyncClient() as client:
r = await client.get("https://api.example.com")
return r.json()Décorateurs d'opérations de chemin
FastAPI gère toutes les méthodes HTTP : GET, POST, PUT, PATCH, DELETE, OPTIONS, HEAD. Chacune correspond à un décorateur. Utilisez status_code= sur le décorateur pour remplacer le statut de succès par défaut.
from fastapi import FastAPI
app = FastAPI()
@app.get("/items")
def list_items(): ...
@app.post("/items")
def create_item(): ...
@app.put("/items/{item_id}")
def replace_item(item_id: int): ...
@app.patch("/items/{item_id}")
def update_item(item_id: int): ...
@app.delete("/items/{item_id}")
def delete_item(item_id: int): ...
@app.options("/items")
def options_items(): ...
@app.head("/items")
def head_items(): ...Réponse JSON et statut
Renvoyer un dict/list est automatiquement converti en JSON avec 200 (ou votre status_code). Pour un contrôle total du statut, des en-têtes ou du contenu, renvoyez directement une JSONResponse ou une Response.
from fastapi import FastAPI, status
from fastapi.responses import JSONResponse
app = FastAPI()
@app.get("/plain")
def plain():
return {"key": "value"} # auto JSON, 200 OK
@app.post("/created", status_code=status.HTTP_201_CREATED)
def created():
return {"id": 1}
@app.get("/custom")
def custom():
return JSONResponse(
status_code=418,
content={"error": "I'm a teapot"},
headers={"X-Custom": "yes"},
)Structure de projet
Découpez une app qui grandit en modules avec APIRouter, puis enregistrez-les via app.include_router(). Gardez les schémas Pydantic, la config DB et les dépendances dans des fichiers séparés pour la maintenabilité.
myapp/
main.py # creates the FastAPI app
routers/
users.py # APIRouter for /users
items.py # APIRouter for /items
models/
schemas.py # Pydantic models
database.py # DB engine & session
dependencies.py # shared Depends functions
tests/
test_main.py
# main.py
from fastapi import FastAPI
from routers import users, items
app = FastAPI()
app.include_router(users.router)
app.include_router(items.router, prefix="/items")Paramètres de chemin
Paramètres de chemin de base
Les valeurs capturées dans le chemin sont des chaînes, sauf annotation de type. Le nom du paramètre dans le chemin doit correspondre exactement au nom de l'argument de la fonction.
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/{item_id}")
def read_item(item_id):
return {"item_id": item_id}
# GET /items/42 -> {"item_id": "42"} (string by default)Conversion de type
Ajouter une annotation de type (int, float, bool, str, Enum) fait valider et convertir la valeur du chemin par FastAPI. Les valeurs invalides renvoient une réponse 422 avec un message d'erreur clair.
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/{item_id}")
def read_item(item_id: int):
return {"item_id": item_id}
# GET /items/3 -> {"item_id": 3}
# GET /items/abc -> 422 Validation Error (not an integer)Validation du chemin
Path() ajoute métadonnées et contraintes à un paramètre de chemin. Contraintes numériques : ge (>=), gt (>), le (<=), lt (<). Les paramètres de chemin sont toujours requis, Path() ne peut donc pas définir de défaut.
from fastapi import FastAPI, Path
app = FastAPI()
@app.get("/items/{item_id}")
def read_item(
item_id: int = Path(
title="The ID of the item",
description="Must be a positive integer",
ge=1,
le=1000,
),
):
return {"item_id": item_id}Contraintes numériques
Utilisez ge/gt/le/lt sur des paramètres de chemin int ou float pour imposer des plages numériques. Des contraintes combinées donnent une validation de bornes précise avec erreurs 422 automatiques.
from fastapi import FastAPI, Path
app = FastAPI()
@app.get("/ratio/{value}")
def ratio(
value: float = Path(gt=0, lt=1), # 0 < value < 1
):
return {"value": value}
@app.get("/page/{page}")
def page(
page: int = Path(ge=1), # >= 1
size: int = Path(le=100), # <= 100
):
return {"page": page, "size": size}L'ordre des routes compte
Les routes sont appariées dans l'ordre de déclaration. Déclarez les chemins spécifiques comme /users/me avant les motifs dynamiques comme /users/{user_id}, sinon la route dynamique masquera la spécifique.
from fastapi import FastAPI
app = FastAPI()
@app.get("/users/me")
def read_current_user():
return {"user": "me"}
@app.get("/users/{user_id}")
def read_user(user_id: str):
return {"user_id": user_id}
# /users/me MUST be declared before /users/{user_id}
# otherwise 'me' would match the {user_id} patternParamètres de chemin Enum
Utiliser un type Enum pour un paramètre de chemin le restreint aux valeurs prédéfinies et génère un schéma enum dans la doc OpenAPI. Héritez de (str, Enum) pour que les valeurs se sérialisent en chaînes.
from enum import Enum
from fastapi import FastAPI
class ModelName(str, Enum):
alexnet = "alexnet"
resnet = "resnet"
lenet = "lenet"
app = FastAPI()
@app.get("/models/{model_name}")
def get_model(model_name: ModelName):
if model_name is ModelName.alexnet:
return {"model": model_name, "layers": 5}
return {"model": model_name}
# GET /models/resnet -> {"model": "resnet"}Paramètres de requête
Paramètres de requête de base
Les paramètres de fonction qui ne sont PAS dans le chemin deviennent des paramètres de requête. Fournir une valeur par défaut les rend optionnels ; le défaut s'applique quand la clé de requête est absente.
from fastapi import FastAPI
app = FastAPI()
fake_items = [{"item": "a"}, {"item": "b"}, {"item": "c"}]
@app.get("/items")
def list_items(skip: int = 0, limit: int = 10):
return fake_items[skip : skip + limit]
# GET /items?skip=0&limit=2
# GET /items -> skip=0, limit=10Paramètres de requête optionnels
Utilisez Optional[str] = None (ou str | None = None sur Python 3.10+) pour un paramètre de requête qui peut être omis. Les paramètres requis n'ont simplement pas de valeur par défaut.
from typing import Optional
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/{item_id}")
def read_item(item_id: str, q: Optional[str] = None):
if q:
return {"item_id": item_id, "q": q}
return {"item_id": item_id}
# GET /items/1?q=hello
# GET /items/1 (q is None)Validation de requête
Query() ajoute de la validation : min_length/max_length pour les chaînes, ge/gt/le/lt pour les nombres, pattern (regex) pour le format des chaînes. Utilisez default= pour fixer une valeur tout en appliquant les contraintes.
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/search")
def search(q: str = Query(min_length=3, max_length=50, pattern="^[a-zA-Z]+$")):
return {"q": q}
@app.get("/page")
def page(limit: int = Query(default=10, ge=1, le=100)):
return {"limit": limit}Conversion booléenne
Les paramètres booléens de requête acceptent plusieurs valeurs truthy : true, 1, yes, on (insensible à la casse). Tout le reste est interprété comme false. Les types invalides comme ?active=maybe renvoient 422.
from fastapi import FastAPI
app = FastAPI()
@app.get("/flags")
def flags(active: bool = False):
return {"active": active}
# GET /flags?active=true -> {"active": true}
# GET /flags?active=1 -> {"active": true}
# GET /flags?active=yes -> {"active": true}
# GET /flags?active=off -> {"active": false}Paramètres de requête en liste
Un paramètre List[str] accepte la même clé répétée dans la query string. Utilisez Query(default=[]) pour une liste vide par défaut, ou Query(default=None) pour autoriser l'absence de valeur.
from typing import List
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items")
def list_items(q: List[str] = Query(default=[])):
return {"q": q}
# GET /items?q=a&q=b&q=c -> {"q": ["a", "b", "c"]}
# declare default=None to accept a list or nullParamètres de requête requis
Utilisez Query(...) (l'Ellipsis) pour déclarer un paramètre de requête requis qui garde ses métadonnées de validation. Sans défaut et sans Query(...), un paramètre simplement annoté est aussi requis.
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items")
def read_item(q: str = Query(...)):
return {"q": q}
# GET /items?q=hello -> ok
# GET /items -> 422 (q is required)
# Query(...) (Ellipsis) marks a parameter as requiredCorps de requête (Pydantic)
Bases de BaseModel
Un BaseModel Pydantic déclaré comme paramètre de fonction devient le corps JSON de la requête. FastAPI valide la charge utile, convertit les types et renvoie 422 sur des données invalides. Les champs avec défauts sont optionnels.
from fastapi import FastAPI
from pydantic import BaseModel
class Item(BaseModel):
name: str
price: float
in_stock: bool = True
app = FastAPI()
@app.post("/items")
def create_item(item: Item):
return item
# POST /items body: {"name": "Apple", "price": 0.5}
# -> {"name": "Apple", "price": 0.5, "in_stock": true}Types et contraintes de champs
Field() ajoute contraintes et métadonnées aux attributs du modèle : min_length/max_length pour les chaînes, gt/ge/lt/le pour les nombres, default_factory pour les défauts mutables. model_config avec json_schema_extra ajoute des exemples à la doc.
from pydantic import BaseModel, Field
from typing import Optional
class Item(BaseModel):
name: str = Field(min_length=1, max_length=100)
price: float = Field(gt=0, description="must be positive")
tax: Optional[float] = None
tags: list[str] = Field(default_factory=list)
model_config = {
"json_schema_extra": {
"examples": [{"name": "Apple", "price": 0.5, "tags": ["fruit"]}]
}
}Modèles imbriqués
Les modèles peuvent s'imbriquer : déclarez un autre BaseModel comme type de champ. FastAPI valide toute la structure imbriquée récursivement, et le schéma OpenAPI généré reflète les objets imbriqués.
from pydantic import BaseModel
from typing import Optional
class Image(BaseModel):
url: str
name: str
class Item(BaseModel):
name: str
description: Optional[str] = None
image: Optional[Image] = None
images: list[Image] = []
# valid body:
# {"name": "Phone", "image": {"url": "http://x/a.png", "name": "a"}}Validation de champ
Utilisez @field_validator (Pydantic v2) pour ajouter une logique de validation personnalisée par champ. Levez ValueError pour rejeter l'entrée (FastAPI la présente en 422). Renvoyez la valeur (éventuellement transformée) pour la conserver.
from pydantic import BaseModel, field_validator
class User(BaseModel):
name: str
email: str
@field_validator("email")
@classmethod
def email_must_contain_at(cls, v: str) -> str:
if "@" not in v:
raise ValueError("must contain @")
return v.lower()
@field_validator("name")
@classmethod
def name_stripped(cls, v: str) -> str:
return v.strip()Champs optionnels et par défaut
Un champ n'est requis que s'il n'a pas de défaut et n'est pas Optional. Optional[str] = None est le pattern standard pour un champ nullable optionnel ; un défaut simple comme 0.0 rend un champ optionnel avec cette valeur.
from pydantic import BaseModel
from typing import Optional
class Item(BaseModel):
name: str # required
description: Optional[str] = None # optional, defaults to None
price: float = 0.0 # optional, defaults to 0.0
tags: list[str] = [] # optional, defaults to empty list
# All of these are valid:
# {"name": "X"}
# {"name": "X", "price": 9.99, "tags": ["a"]}Corps avec chemin et requête
Paramètres de chemin, de requête et de corps peuvent coexister dans une même opération. FastAPI décide ainsi : paramètre de chemin s'il est dans le chemin, modèle Pydantic (ou Body()) pour le corps, sinon requête. Un corps optionnel exige un défaut None.
from fastapi import FastAPI, Path, Query
from pydantic import BaseModel
class Item(BaseModel):
name: str
price: float
app = FastAPI()
@app.put("/items/{item_id}")
def update_item(
item_id: int = Path(ge=1),
q: Optional[str] = Query(default=None),
item: Item = None,
):
result = {"item_id": item_id, **item.model_dump()}
if q:
result["q"] = q
return resultModèle de réponse
Bases de response_model
response_model filtre les données renvoyées aux seuls champs définis dans le modèle, même si vous renvoyez un objet avec des champs supplémentaires. C'est la façon standard de masquer les champs sensibles comme les mots de passe.
from fastapi import FastAPI
from pydantic import BaseModel
class User(BaseModel):
username: str
email: str
hashed_password: str
class UserOut(BaseModel):
username: str
email: str
app = FastAPI()
@app.get("/users/me", response_model=UserOut)
def read_user():
return User(username="bob", email="[email protected]", hashed_password="secret")
# response: {"username": "bob", "email": "[email protected]"} (no password)Exclure des champs
response_model_include et response_model_exclude permettent de whitelister ou blacklister des champs par route sans définir de nouveaux modèles. Passez un ensemble de noms de champs. Ils s'appliquent en plus du response_model.
from fastapi import FastAPI
from pydantic import BaseModel
class Item(BaseModel):
name: str
price: float
secret: str
app = FastAPI()
@app.get("/items/{id}", response_model=Item, response_model_exclude={"secret"})
def read_item(id: int):
return {"name": "Apple", "price": 0.5, "secret": "hidden"}
@app.get("/items", response_model=list[Item], response_model_include={"name", "price"})
def list_items():
return [{"name": "Apple", "price": 0.5, "secret": "x"}]Réponse en liste
Utilisez response_model=list[Model] (ou List[Model]) pour déclarer qu'un endpoint renvoie un tableau d'objets. FastAPI valide et sérialise chaque élément de la liste.
from fastapi import FastAPI
from pydantic import BaseModel
class Item(BaseModel):
name: str
price: float
app = FastAPI()
@app.get("/items", response_model=list[Item])
def list_items():
return [
{"name": "Apple", "price": 0.5},
{"name": "Banana", "price": 0.3},
]
# response: [{"name": "Apple", "price": 0.5}, {"name": "Banana", "price": 0.3}]Exclure non définis/défauts
exclude_unset omet les champs que le client n'a jamais envoyés (seuls les champs explicitement définis apparaissent). exclude_defaults omet les champs égaux à leur défaut ; exclude_none omet les champs None. Utile pour des réponses éparses.
from fastapi import FastAPI
from pydantic import BaseModel
class Item(BaseModel):
name: str
description: str | None = None
price: float = 0.0
tax: float = 0.0
app = FastAPI()
@app.get("/items/{id}", response_model=Item, response_model_exclude_unset=True)
def read_item(id: int):
return {"name": "Apple", "price": 0.5}
# -> {"name": "Apple", "price": 0.5} (description, tax omitted)
# also: response_model_exclude_defaults=True
# response_model_exclude_none=TrueRéponse par alias
Field(alias=...) permet au JSON entrant d'utiliser un nom de clé différent de l'attribut Python. response_model_by_alias=True produit aussi la sortie avec l'alias. populate_by_name=True accepte aussi le nom d'attribut d'origine en entrée.
from fastapi import FastAPI
from pydantic import BaseModel, ConfigDict, Field
class Item(BaseModel):
model_config = ConfigDict(populate_by_name=True)
name: str = Field(alias="itemName")
price: float
app = FastAPI()
@app.post("/items", response_model=Item, response_model_by_alias=True)
def create(item: Item):
return item
# input: {"itemName": "Apple", "price": 0.5}
# output: {"itemName": "Apple", "price": 0.5}Réponse dict simple
Renvoyer un dict/list se sérialise automatiquement en JSON. Utilisez response_class pour changer le type de réponse par défaut (HTMLResponse, PlainTextResponse), ou renvoyez directement une sous-classe de Response pour un contrôle total.
from fastapi import FastAPI
from fastapi.responses import JSONResponse, PlainTextResponse
app = FastAPI()
@app.get("/dict")
def dict_resp():
return {"a": 1, "b": 2} # auto JSON
@app.get("/text", response_class=PlainTextResponse)
def text_resp():
return "plain text response"
@app.get("/raw")
def raw_resp():
return JSONResponse(content={"a": 1}, status_code=200)Formulaires et UploadFile
Données de formulaire
Form() déclare un paramètre parsé depuis application/x-www-form-urlencoded ou des données de formulaire multipart. On ne peut pas mélanger Form() avec un corps JSON (BaseModel) dans une même opération — choisissez un type de contenu.
from fastapi import FastAPI, Form
app = FastAPI()
@app.post("/login")
def login(username: str = Form(), password: str = Form()):
return {"username": username}
# Content-Type: application/x-www-form-urlencoded
# body: username=bob&password=secretUploadFile de base
UploadFile est une représentation de fichier en flux avec .filename, .content_type, .read(), .write(), .close(). Utilisez 'await file.read()' dans async def. Pour les gros fichiers, préférez file.file (SpooledTemporaryFile) pour éviter de tout charger en mémoire.
from fastapi import FastAPI, UploadFile, File
app = FastAPI()
@app.post("/upload")
async def upload_file(file: UploadFile = File(...)):
contents = await file.read()
return {
"filename": file.filename,
"size": len(contents),
"content_type": file.content_type,
}Plusieurs fichiers
Déclarez list[UploadFile] pour accepter plusieurs fichiers dans une requête. Chaque fichier est envoyé avec le même nom de champ. L'ordre des fichiers dans la liste suit l'ordre d'envoi.
from fastapi import FastAPI, UploadFile
app = FastAPI()
@app.post("/uploads")
async def upload_many(files: list[UploadFile]):
return [
{"filename": f.filename, "size": len(await f.read())}
for f in files
]
# curl: curl -F "[email protected]" -F "[email protected]" http://localhost:8000/uploadsFichier et formulaire ensemble
Form() et UploadFile (File()) se combinent dans un même endpoint car les deux utilisent multipart/form-data. On ne peut toujours pas les combiner avec un corps JSON BaseModel.
from fastapi import FastAPI, UploadFile, File, Form
app = FastAPI()
@app.post("/items")
async def create_item(
name: str = Form(),
description: str = Form(),
file: UploadFile = File(),
):
return {
"name": name,
"description": description,
"file": file.filename,
}Enregistrer le fichier envoyé
Pour les petits fichiers, shutil.copyfileobj envoie le SpooledTemporaryFile sur disque efficacement. Pour les très gros fichiers, lisez par tranches (ex. 1 Mo) pour garder la mémoire basse. Assainissez toujours file.filename pour éviter le path traversal.
import shutil
from pathlib import Path
from fastapi import FastAPI, UploadFile
app = FastAPI()
@app.post("/save")
async def save_file(file: UploadFile):
dest = Path("uploads") / file.filename
dest.parent.mkdir(exist_ok=True)
with dest.open("wb") as buf:
shutil.copyfileobj(file.file, buf)
return {"saved_to": str(dest)}
# async alternative for large files:
# async with dest.open("wb") as buf:
# while chunk := await file.read(1024 * 1024):
# buf.write(chunk)Métadonnées et taille de fichier
Validez file.content_type et la taille avant traitement. Après read(), le curseur est à la fin ; appelez 'await file.seek(0)' pour revenir au début si vous devez relire. Une vraie vérification de type devrait inspecter les magic bytes, pas seulement l'en-tête.
from fastapi import FastAPI, UploadFile, File
app = FastAPI()
@app.post("/validate")
async def validate(file: UploadFile = File(...)):
# allowed types
allowed = {"image/png", "image/jpeg"}
if file.content_type not in allowed:
return {"error": "unsupported type"}
contents = await file.read()
max_size = 5 * 1024 * 1024 # 5 MB
if len(contents) > max_size:
return {"error": "file too large"}
await file.seek(0) # rewind so later reads work
return {"filename": file.filename, "size": len(contents)}Injection de dépendances
Depends de base
Depends() injecte la valeur de retour d'une fonction dans votre opération de chemin. La logique partagée (pagination, parsing, sessions DB) vit à un seul endroit et se réutilise entre endpoints. Les paramètres de la dépendance sont aussi documentés dans OpenAPI.
from fastapi import FastAPI, Depends
app = FastAPI()
def common_params(q: str | None = None, skip: int = 0, limit: int = 10):
return {"q": q, "skip": skip, "limit": limit}
@app.get("/items")
def list_items(commons: dict = Depends(common_params)):
return commons
@app.get("/users")
def list_users(commons: dict = Depends(common_params)):
return commonsDépendances par classe
Une classe avec __init__ peut être une dépendance ; FastAPI l'appelle comme une fonction. Utilisez Depends(CommonQueryParams) ou le raccourci Depends() quand le paramètre est annoté avec la classe. L'instance est injectée.
from fastapi import FastAPI, Depends
class CommonQueryParams:
def __init__(self, q: str | None = None, skip: int = 0, limit: int = 10):
self.q = q
self.skip = skip
self.limit = limit
app = FastAPI()
@app.get("/items")
def list_items(commons: CommonQueryParams = Depends(CommonQueryParams)):
return {"q": commons.q, "skip": commons.skip, "limit": commons.limit}
# shorthand: commons = Depends() infers the typeDépendances imbriquées
Les dépendances peuvent elles-mêmes dépendre d'autres dépendances, formant un graphe. FastAPI résout tout l'arbre, met en cache chaque résultat par requête et propage les exceptions. Idéal pour une auth en couches (token -> user -> permissions).
from fastapi import FastAPI, Depends, Header, HTTPException
def get_token(authorization: str = Header()):
if not authorization.startswith("Bearer "):
raise HTTPException(status_code=401, detail="invalid header")
return authorization.removeprefix("Bearer ")
def get_current_user(token: str = Depends(get_token)):
if token != "admin-token":
raise HTTPException(status_code=403, detail="forbidden")
return {"username": "admin"}
app = FastAPI()
@app.get("/me")
def me(user: dict = Depends(get_current_user)):
return userDépendances yield (nettoyage)
Un générateur de dépendance (yield) est parfait pour les ressources nécessitant un nettoyage : sessions DB, handles de fichiers, transactions. Le code après yield s'exécute comme finaliseur, même si la route lève une exception. Un seul yield par dépendance.
from fastapi import FastAPI, Depends
def get_db():
db = open_db_session() # acquire resource
try:
yield db # injected into the route
finally:
db.close() # always runs after the request
app = FastAPI()
@app.get("/items")
def list_items(db = Depends(get_db)):
return db.query("SELECT * FROM items")Dépendances globales
Passez dependencies=[...] à FastAPI() (ou à un APIRouter) pour les imposer à chaque route sans injecter leur valeur de retour. Utile pour une auth globale, un rate limiting ou la journalisation des requêtes.
from fastapi import FastAPI, Depends, Header, HTTPException
def verify_token(x_token: str = Header()):
if x_token != "supersecret":
raise HTTPException(status_code=400, detail="X-Token missing")
def verify_key(x_key: str = Header()):
if x_key != "realkey":
raise HTTPException(status_code=400, detail="X-Key missing")
# applied to every route in the app
app = FastAPI(dependencies=[Depends(verify_token), Depends(verify_key)])
@app.get("/items")
def list_items():
return [{"item": "a"}] # token & key already checkedDépendances par route
Utilisez dependencies=[Depends(...)] sur un décorateur (ou un APIRouter) pour exiger une dépendance sur des routes précises sans utiliser sa valeur de retour. Les signatures de route restent propres tout en imposant les vérifications.
from fastapi import FastAPI, Depends, Header, HTTPException
def verify_token(x_token: str = Header()):
if x_token != "secret":
raise HTTPException(status_code=401, detail="bad token")
app = FastAPI()
@app.get("/public")
def public():
return {"open": True}
@app.get("/private", dependencies=[Depends(verify_token)])
def private():
return {"secret": "data"}Sécurité (HTTPBasic / OAuth2 / JWT)
Auth HTTP Basic
HTTPBasic parse l'en-tête Authorization: Basic en username/password. Utilisez secrets.compare_digest (pas ==) pour prévenir les attaques temporelles. Renvoyez toujours 401 avec WWW-Authenticate: Basic pour que les navigateurs demandent les identifiants.
import secrets
from fastapi import FastAPI, Depends, HTTPException, status
from fastapi.security import HTTPBasic, HTTPBasicCredentials
security = HTTPBasic()
app = FastAPI()
def get_current_user(credentials: HTTPBasicCredentials = Depends(security)):
correct_user = secrets.compare_digest(credentials.username, "admin")
correct_pass = secrets.compare_digest(credentials.password, "secret")
if not (correct_user and correct_pass):
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="Invalid credentials",
headers={"WWW-Authenticate": "Basic"},
)
return credentials.username
@app.get("/profile")
def profile(user: str = Depends(get_current_user)):
return {"user": user}OAuth2 Password Bearer
OAuth2PasswordBearer déclare que les routes attendent un token Bearer ; la dépendance l'extrait de l'en-tête Authorization. tokenUrl indique à l'UI de doc où envoyer les identifiants. Le token lui-même n'est qu'une chaîne tant que vous ne le validez pas.
from fastapi import FastAPI, Depends
from fastapi.security import OAuth2PasswordBearer
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
app = FastAPI()
@app.get("/me")
def me(token: str = Depends(oauth2_scheme)):
return {"token": token}
# client POSTs username+password to /token, receives an access token,
# then sends it as: Authorization: Bearer <token>Créer un token JWT
Utilisez python-jose (ou PyJWT) pour signer les tokens. La claim 'sub' (subject) porte conventionnellement le username ou l'id utilisateur, et 'exp' fixe l'expiration. Gardez SECRET_KEY longue, aléatoire et chargée depuis l'environnement — ne la commitez jamais.
from datetime import datetime, timedelta, timezone
from jose import jwt
SECRET_KEY = "keep-this-secret"
ALGORITHM = "HS256"
def create_access_token(data: dict, expires_minutes: int = 30) -> str:
to_encode = data.copy()
expire = datetime.now(timezone.utc) + timedelta(minutes=expires_minutes)
to_encode.update({"exp": expire})
return jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)
# token = create_access_token({"sub": "alice"})
# -> eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...Décoder un token JWT
jwt.decode vérifie la signature et la claim 'exp' automatiquement, en levant JWTError en cas d'échec. Mappez la dépendance à un 401 avec WWW-Authenticate: Bearer pour que les clients sachent fournir un token valide.
from fastapi import Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer
from jose import jwt, JWTError
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
SECRET_KEY = "keep-this-secret"
ALGORITHM = "HS256"
def get_current_user(token: str = Depends(oauth2_scheme)) -> str:
try:
payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
username: str | None = payload.get("sub")
if username is None:
raise credentials_exception
return username
except JWTError:
raise credentials_exception
credentials_exception = HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="Could not validate credentials",
headers={"WWW-Authenticate": "Bearer"},
)Hachage des mots de passe
Ne stockez jamais les mots de passe en clair. passlib avec bcrypt (ou argon2) gère salage et hachage. verify() compare une entrée en clair à un hash stocké. pip install passlib[bcrypt] pour obtenir le backend bcrypt.
from passlib.context import CryptContext
pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
def hash_password(plain: str) -> str:
return pwd_context.hash(plain)
def verify_password(plain: str, hashed: str) -> bool:
return pwd_context.verify(plain, hashed)
# usage when issuing tokens:
def authenticate_user(username: str, password: str):
user = fake_db.get(username)
if not user or not verify_password(password, user.hashed_password):
return False
return userFlux de connexion OAuth2
OAuth2PasswordRequestForm lit username/password depuis un POST encodé en formulaire (le flux OAuth2 password standard). Renvoyez access_token et token_type: 'bearer'. Cet endpoint est celui vers lequel pointe tokenUrl de OAuth2PasswordBearer.
from fastapi import FastAPI, Depends, HTTPException, status
from fastapi.security import OAuth2PasswordRequestForm
app = FastAPI()
@app.post("/token")
def login(form: OAuth2PasswordRequestForm = Depends()):
user = authenticate_user(form.username, form.password)
if not user:
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="Incorrect username or password",
)
token = create_access_token({"sub": user.username})
return {"access_token": token, "token_type": "bearer"}
# OAuth2PasswordRequestForm parses username+password from form data
# and powers the 'Authorize' button in the Swagger UI.Middleware
Ajouter un middleware
@app.middleware('http') enregistre une fonction qui enveloppe chaque requête. Elle doit await call_next(request) pour obtenir la réponse, puis peut l'inspecter ou la modifier avant de la renvoyer. Le middleware s'exécute pour toutes les routes.
import time
from fastapi import FastAPI, Request
app = FastAPI()
@app.middleware("http")
async def add_process_time(request: Request, call_next):
start = time.perf_counter()
response = await call_next(request)
duration = time.perf_counter() - start
response.headers["X-Process-Time"] = f"{duration:.4f}"
return responseMiddleware d'en-têtes personnalisés
Le middleware est le bon endroit pour attacher des en-têtes devant figurer sur chaque réponse (en-têtes de sécurité, bannière serveur, IDs de traçage). Modifiez l'objet réponse après avoir await call_next.
from fastapi import FastAPI, Request
app = FastAPI()
@app.middleware("http")
async def add_banner(request: Request, call_next):
response = await call_next(request)
response.headers["X-Powered-By"] = "FastAPI"
response.headers["X-Frame-Options"] = "DENY"
return response
# every response now carries these headersBaseHTTPMiddleware
Pour un middleware réutilisable et configurable, héritez de BaseHTTPMiddleware et enregistrez-le avec app.add_middleware(MyMiddleware, **options). C'est aussi ainsi qu'on ajoute les middlewares intégrés CORS, GZip et TrustedHost.
from starlette.middleware.base import BaseHTTPMiddleware
from fastapi import FastAPI, Request
class TimingMiddleware(BaseHTTPMiddleware):
async def dispatch(self, request: Request, call_next):
start = time.perf_counter()
response = await call_next(request)
response.headers["X-Duration"] = str(time.perf_counter() - start)
return response
app = FastAPI()
app.add_middleware(TimingMiddleware)
# class-based middleware is reusable and configurableRedirection HTTPS
HTTPSRedirectMiddleware renvoie une redirection 308 vers la version HTTPS de toute requête HTTP. Utilisez-le derrière un load balancer qui termine le TLS, pour garantir que les clients passent à une connexion sécurisée.
from fastapi import FastAPI
from fastapi.middleware.httpsredirect import HTTPSRedirectMiddleware
app = FastAPI()
app.add_middleware(HTTPSRedirectMiddleware)
# all HTTP requests are redirected to HTTPS (308)Hôte de confiance
TrustedHostMiddleware rejette les requêtes dont l'en-tête Host n'est pas dans la liste autorisée, prévenant les attaques par injection d'en-tête Host. Les wildcards comme '*.example.com' sont pris en charge. Incluez toujours 'localhost' pour le développement local.
from fastapi import FastAPI
from fastapi.middleware.trustedhost import TrustedHostMiddleware
app = FastAPI()
app.add_middleware(
TrustedHostMiddleware,
allowed_hosts=["example.com", "*.example.com", "localhost"],
)
# requests with a disallowed Host header get a 400 responseOrdre des middleware
Starlette exécute les middleware en ordre LIFO pour les requêtes entrantes : le dernier ajouté tourne en premier. Ajoutez CORS tôt (pour que le preflight fonctionne) et GZip après. Retenez-le quand vous déboguez pourquoi un en-tête posé par un middleware n'est pas vu par un autre.
from fastapi import FastAPI
from fastapi.middleware.gzip import GZipMiddleware
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI()
# Middleware runs in REVERSE order of registration for requests,
# and in registration order for responses.
app.add_middleware(GZipMiddleware, minimum_size=1000)
app.add_middleware(CORSMiddleware, allow_origins=["*"])
# request flow: CORS -> GZip -> route
# response flow: route -> GZip -> CORSCORS
Configuration de CORSMiddleware
CORSMiddleware gère le preflight CORS (OPTIONS) et ajoute les en-têtes Access-Control-*. allow_origins doit lister les origines exactement autorisées ; en production, utilisez une liste d'URLs précises plutôt que ['*'].
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI()
app.add_middleware(
CORSMiddleware,
allow_origins=["https://example.com", "https://www.example.com"],
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
@app.get("/api/data")
def data():
return {"data": 1}Autoriser toutes les origines (dev uniquement)
allow_origins=['*'] autorise toute origine mais ne peut pas se combiner avec allow_credentials=True (les navigateurs le rejettent). Réservez-le aux API totalement publiques en développement ; en production, énumérez les vraies origines.
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI()
app.add_middleware(
CORSMiddleware,
allow_origins=["*"],
allow_methods=["*"],
allow_headers=["*"],
# allow_credentials=True CANNOT be combined with allow_origins=["*"]
)Autoriser les credentials
allow_credentials=True permet au navigateur d'envoyer cookies et en-têtes Authorization en cross-origin. Cela exige des origines spécifiques (jamais '*'). Le navigateur définit Access-Control-Allow-Credentials: true sur les réponses.
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI()
app.add_middleware(
CORSMiddleware,
allow_origins=["https://app.example.com"],
allow_credentials=True, # send cookies / Authorization
allow_methods=["GET", "POST"],
allow_headers=["Authorization", "Content-Type"],
)
# needed when the frontend sends cookies or credentials with requestsMéthodes et en-têtes autorisés
allow_methods/allow_headers restreignent ce que le navigateur peut envoyer. expose_headers liste les en-têtes de réponse que le JavaScript frontal peut lire (sinon les navigateurs masquent les en-têtes personnalisés). Les réponses de preflight sont mises en cache par le navigateur.
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI()
app.add_middleware(
CORSMiddleware,
allow_origins=["https://app.example.com"],
allow_methods=["GET", "POST", "PUT", "PATCH", "DELETE"],
allow_headers=["Authorization", "Content-Type", "X-Request-ID"],
expose_headers=["X-Total-Count", "X-Process-Time"],
)
# expose_headers lets the frontend JS read these response headersRequêtes de preflight
Pour les requêtes « non simples » (ex. en-têtes personnalisés, PUT/DELETE, contenu JSON), le navigateur envoie un preflight OPTIONS. CORSMiddleware intercepte OPTIONS et répond avec les méthodes/en-têtes autorisés. max_age contrôle la durée de mise en cache de cette réponse par le navigateur.
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI()
app.add_middleware(
CORSMiddleware,
allow_origins=["https://app.example.com"],
allow_methods=["*"],
allow_headers=["*"],
max_age=600, # browser caches preflight result for 600s
)
# Browser sends OPTIONS preflight for non-simple requests;
# CORSMiddleware answers automatically with the right headers.Validation dynamique des origines
Pour des listes dynamiques, utilisez allow_origin_regex (correspond à l'Origin de la requête) au lieu d'une liste statique. Pratique quand les origines valides suivent un motif (ex. tout sous-domaine de example.com).
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI()
VALID_DOMAINS = {"example.com", "staging.example.com"}
def origin_check(origin: str) -> str | None:
if origin and origin.replace("https://", "").replace("http://", "") in VALID_DOMAINS:
return origin
return None
app.add_middleware(
CORSMiddleware,
allow_origin_regex=r"https://.*\.example\.com",
allow_methods=["*"],
allow_headers=["*"],
)Gestion des exceptions
Lever HTTPException
Lever HTTPException n'importe où dans une route ou une dépendance court-circuite et renvoie une réponse d'erreur. detail peut être une chaîne, un dict ou une liste — il devient le champ JSON 'detail'. headers ajoute optionnellement des en-têtes de réponse.
from fastapi import FastAPI, HTTPException, status
app = FastAPI()
items = {1: "Apple", 2: "Banana"}
@app.get("/items/{item_id}")
def read_item(item_id: int):
if item_id not in items:
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail="Item not found",
headers={"X-Error": "missing"},
)
return {"item": items[item_id]}Exception personnalisée
Enregistrez un handler avec @app.exception_handler(MyException) pour convertir n'importe quelle exception personnalisée en réponse HTTP. Le handler reçoit la requête et l'exception. Cela centralise le formatage des erreurs du domaine de votre app.
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
class UnicornException(Exception):
def __init__(self, name: str):
self.name = name
app = FastAPI()
@app.exception_handler(UnicornException)
async def unicorn_handler(request: Request, exc: UnicornException):
return JSONResponse(
status_code=418,
content={"message": f"Oops, {exc.name} did it again"},
)
@app.get("/unicorns/{name}")
def read_unicorn(name: str):
if name == "yolo":
raise UnicornException(name=name)
return {"name": name}Surcharger l'erreur de validation
RequestValidationError se lève quand l'entrée échoue à la validation Pydantic. Surchargez son handler avec @app.exception_handler(RequestValidationError) pour personnaliser la forme de la réponse 422, ex. pour coller à une enveloppe d'erreur d'entreprise.
from fastapi import FastAPI, Request, status
from fastapi.responses import JSONResponse
from fastapi.exceptions import RequestValidationError
app = FastAPI()
@app.exception_handler(RequestValidationError)
async def validation_handler(request: Request, exc: RequestValidationError):
return JSONResponse(
status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
content={
"success": False,
"errors": exc.errors(),
"body": exc.body,
},
)Surcharger le handler HTTPException
Surchargez le handler HTTPException par défaut pour imposer une forme d'erreur JSON cohérente à toutes les HTTPException levées. Importez la classe comme fastapi.exceptions.HTTPException (celle utilisée par raise) quand vous re-liez son handler.
from fastapi import FastAPI, HTTPException
from fastapi.responses import JSONResponse
from fastapi.exceptions import HTTPException as FastAPIHTTPException
app = FastAPI()
@app.exception_handler(FastAPIHTTPException)
async def custom_http_handler(request, exc: FastAPIHTTPException):
return JSONResponse(
status_code=exc.status_code,
content={
"success": False,
"status": exc.status_code,
"message": exc.detail,
},
headers=exc.headers,
)Codes de statut courants
Le module status fournit des constantes nommées pour tous les codes de statut HTTP, évitant les nombres magiques. 200 (défaut GET), 201 (créé), 204 (sans contenu), 422 (validation) sont les plus courants dans les apps FastAPI.
from fastapi import FastAPI, status
app = FastAPI()
@app.get("/ok", status_code=status.HTTP_200_OK)
def ok(): return {"ok": True}
@app.post("/create", status_code=status.HTTP_201_CREATED)
def create(): return {"id": 1}
@app.get("/no-content", status_code=status.HTTP_204_NO_CONTENT)
def no_content(): return None
@app.get("/not-found")
def missing():
# raise HTTPException(status.HTTP_404_NOT_FOUND, "nope")
...
# Other common: 400 BAD_REQUEST, 401 UNAUTHORIZED,
# 403 FORBIDDEN, 409 CONFLICT, 422 UNPROCESSABLE_ENTITY, 500 INTERNAL_SERVER_ERRORHandler d'exception générique
Enregistrer un handler pour la classe de base Exception attrape tout ce qui n'est pas déjà géré, empêchant les piles d'erreurs de fuiter vers les clients. Journalisez toujours la pile complète côté serveur ; renvoyez un 500 générique au client.
import logging
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
logger = logging.getLogger("uvicorn.error")
app = FastAPI()
@app.exception_handler(Exception)
async def unhandled(request: Request, exc: Exception):
logger.exception("Unhandled error on %s", request.url.path)
return JSONResponse(
status_code=500,
content={"detail": "Internal Server Error"},
)
@app.get("/boom")
def boom():
raise RuntimeError("something exploded")Tâches en arrière-plan
BackgroundTasks de base
BackgroundTasks exécute des fonctions après l'envoi de la réponse — parfait pour du travail fire-and-forget comme le logging, les emails ou l'invalidation de cache. add_task planifie une fonction (et ses arguments) sans bloquer la réponse.
from fastapi import FastAPI, BackgroundTasks
app = FastAPI()
def write_log(message: str):
with open("log.txt", "a") as f:
f.write(message + "\n")
@app.post("/send")
def send_notification(background_tasks: BackgroundTasks):
background_tasks.add_task(write_log, "notification sent")
return {"message": "notification queued"}Plusieurs tâches
Ajoutez autant de tâches que voulu ; elles s'exécutent séquentiellement dans l'ordre d'ajout, après le renvoi de la réponse. Comme elles tournent dans le même processus, gardez-les rapides et non bloquantes, ou passez à une vraie file (Celery, RQ, Dramatiq).
from fastapi import FastAPI, BackgroundTasks
app = FastAPI()
def send_email(to: str, subject: str): ...
def update_cache(key: str): ...
def notify_slack(msg: str): ...
@app.post("/signup")
def signup(background_tasks: BackgroundTasks):
background_tasks.add_task(send_email, "[email protected]", "Welcome")
background_tasks.add_task(update_cache, "user_count")
background_tasks.add_task(notify_slack, "new signup")
return {"status": "ok"}Tâche avec dépendances
BackgroundTasks s'injecte comme n'importe quelle dépendance. La fonction de tâche peut recevoir des valeurs (comme une session DB) capturées au moment de la requête. Notez que les ressources yieldées/fermées des dépendances se ferment après la fin des tâches, puisque les tâches tournent dans la portée du cycle de vie de la requête.
from fastapi import FastAPI, BackgroundTasks, Depends
app = FastAPI()
def get_db_session():
db = "session"
yield db
def write_log(db, message: str):
print(db, message)
@app.get("/items")
def list_items(background_tasks: BackgroundTasks, db = Depends(get_db_session)):
background_tasks.add_task(write_log, db, "list called")
return {"items": []}Fonction de tâche asynchrone
Les fonctions de tâches en arrière-plan peuvent être synchrones (exécutées dans un threadpool) ou asynchrones (attendues sur la boucle d'événements). Utilisez des tâches async pour le travail lié aux E/S qui utilise lui-même des bibliothèques asynchrones, et des tâches sync pour le travail CPU/bloquant.
from fastapi import FastAPI, BackgroundTasks
import httpx
app = FastAPI()
async def fetch_url(url: str):
async with httpx.AsyncClient() as client:
r = await client.get(url)
return r.status_code
@app.post("/webhook")
def webhook(url: str, background_tasks: BackgroundTasks):
background_tasks.add_task(fetch_url, url)
return {"queued": url}Background vs Celery
Utilisez BackgroundTasks pour du travail léger, non critique, qu'on peut perdre au redémarrage. Pour des jobs qui doivent survivre aux crashs, réessayer ou s'étendre sur plusieurs machines, utilisez une vraie file de tâches (Celery, RQ, Dramatiq, Arq) avec un broker comme Redis ou RabbitMQ.
# BackgroundTasks: in-process, no broker, lost if process crashes
@app.post("/quick")
def quick(tasks: BackgroundTasks):
tasks.add_task(small_job)
return {"ok": True}
# Celery/RQ/Dramatiq: separate workers, persistent, retryable
# from celery import Celery
# @celery.task
# def big_job(payload): ...
#
# @app.post("/heavy")
# def heavy(payload: dict):
# big_job.delay(payload)
# return {"queued": True}Exemple d'envoi d'email
L'envoi d'email est le cas d'usage classique de BackgroundTasks : c'est lent et l'utilisateur ne devrait pas attendre. La réponse revient immédiatement pendant que l'email part ensuite. Pour de gros volumes, préférez une file et un SDK de service email avec reprises.
from fastapi import FastAPI, BackgroundTasks
from pydantic import BaseModel, EmailStr
class Message(BaseModel):
to: EmailStr
subject: str
body: str
app = FastAPI()
def send_email(to: str, subject: str, body: str):
# smtplib or your provider's SDK
import smtplib
with smtplib.SMTP("localhost") as s:
s.sendmail("[email protected]", to, f"Subject: {subject}\n\n{body}")
@app.post("/contact")
def contact(msg: Message, tasks: BackgroundTasks):
tasks.add_task(send_email, msg.to, msg.subject, msg.body)
return {"status": "queued", "to": msg.to}WebSocket
WebSocket de base
Utilisez @app.websocket() pour définir un endpoint WebSocket. Vous devez accept() la connexion avant d'envoyer/recevoir. La fonction boucle typiquement en lisant des messages ; receive_text/receive_bytes/receive_json attendent tous des données du client.
from fastapi import FastAPI, WebSocket
app = FastAPI()
@app.websocket("/ws")
async def websocket_endpoint(ws: WebSocket):
await ws.accept()
while True:
data = await ws.receive_text()
await ws.send_text(f"echo: {data}")
# client (browser):
# const ws = new WebSocket("ws://localhost:8000/ws");
# ws.onmessage = (e) => console.log(e.data);Envoyer du JSON
send_json() et receive_json() gèrent la sérialisation pour vous, en échangeant des objets JSON sur le socket. Pour des données binaires, utilisez send_bytes/receive_bytes. Chaque send/receive est une frame distincte du WebSocket.
import json
from fastapi import FastAPI, WebSocket
app = FastAPI()
@app.websocket("/ws")
async def ws_endpoint(ws: WebSocket):
await ws.accept()
while True:
msg = await ws.receive_json()
await ws.send_json({"reply": msg.get("text", "").upper()})
# send_text / send_bytes / send_json helpers are availableFermeture du WebSocket
WebSocketDisconnect se lève quand le client ferme la connexion — attrapez-le pour nettoyer. Appelez ws.close(code=1000) pour une fermeture normale ; codes courants : 1000 (normal), 1008 (violation de politique), 1011 (erreur serveur).
from fastapi import FastAPI, WebSocket, WebSocketDisconnect
app = FastAPI()
@app.websocket("/ws")
async def ws_endpoint(ws: WebSocket):
await ws.accept()
try:
while True:
data = await ws.receive_text()
if data == "quit":
await ws.close(code=1000)
break
await ws.send_text(data)
except WebSocketDisconnect:
print("client disconnected")Gestionnaire de connexions
Un ConnectionManager suit les sockets actifs pour diffuser à tous les clients connectés (ex. une salle de chat). Retirez toujours le socket à la déconnexion pour ne pas envoyer à des connexions fermées et garder la mémoire bornée.
from fastapi import FastAPI, WebSocket, WebSocketDisconnect
class ConnectionManager:
def __init__(self):
self.active: list[WebSocket] = []
async def connect(self, ws: WebSocket):
await ws.accept()
self.active.append(ws)
def disconnect(self, ws: WebSocket):
self.active.remove(ws)
async def broadcast(self, message: str):
for ws in self.active:
await ws.send_text(message)
manager = ConnectionManager()
app = FastAPI()
@app.websocket("/chat")
async def chat(ws: WebSocket):
await manager.connect(ws)
try:
while True:
msg = await ws.receive_text()
await manager.broadcast(msg)
except WebSocketDisconnect:
manager.disconnect(ws)Auth WebSocket via paramètre de requête
Les navigateurs ne peuvent pas définir d'en-têtes personnalisés sur les connexions WebSocket, donc les tokens d'auth passent couramment en paramètres de requête (ou cookies). Validez avant d'appeler accept(), et fermez avec le code 1008 (violation de politique) si non autorisé.
from fastapi import FastAPI, WebSocket, WebSocketDisconnect, HTTPException
app = FastAPI()
async def authenticate(token: str) -> str:
if token != "secret":
raise HTTPException(status_code=401)
return "alice"
@app.websocket("/ws")
async def ws_endpoint(ws: WebSocket):
token = ws.query_params.get("token")
if not token:
await ws.close(code=1008)
return
user = await authenticate(token)
await ws.accept()
try:
while True:
data = await ws.receive_text()
await ws.send_text(f"{user}: {data}")
except WebSocketDisconnect:
passWebSocket avec dépendances
Les dépendances s'utilisent dans les endpoints WebSocket comme dans les routes HTTP, mais seules les dépendances lisant la poignée de main initiale (en-têtes, paramètres de requête, cookies) ont du sens — il n'y a pas de corps. Injectez-les via Depends() comme d'habitude.
from fastapi import FastAPI, WebSocket, Depends, Header
app = FastAPI()
def token_validator(token: str = Header(default="")):
# for WS, headers come from the initial HTTP handshake
return token == "valid"
@app.websocket("/ws")
async def ws_endpoint(ws: WebSocket, valid: bool = Depends(token_validator)):
if not valid:
await ws.close(code=1008)
return
await ws.accept()
while True:
msg = await ws.receive_text()
await ws.send_text(msg)Base de données (SQLAlchemy)
Configuration SQLAlchemy
create_engine met en place le pool de connexions ; SessionLocal est une factory de sessions ; Base est la base déclarative des modèles. Pour SQLite avec FastAPI, mettez check_same_thread=False car les requêtes peuvent tourner dans des threads différents.
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker, declarative_base
SQLALCHEMY_DATABASE_URL = "sqlite:///./app.db"
# postgresql: "postgresql://user:pass@localhost:5432/dbname"
engine = create_engine(
SQLALCHEMY_DATABASE_URL,
connect_args={"check_same_thread": False}, # sqlite only
)
SessionLocal = sessionmaker(bind=engine, autoflush=False, autocommit=False)
Base = declarative_base()Dépendance de session
Une dépendance yield est la façon canonique de fournir une session DB : chaque requête reçoit une session fraîche, fermée dans le bloc finally. Cela garantit le nettoyage même si la route lève une exception.
from fastapi import Depends
from sqlalchemy.orm import Session
def get_db():
db = SessionLocal()
try:
yield db
finally:
db.close()
@app.get("/items")
def list_items(db: Session = Depends(get_db)):
return db.query(Item).all()
# each request gets its own session, closed automatically afterwardDéfinition de modèle
Définissez les tables comme modèles ORM SQLAlchemy héritant de Base. Utilisez Alembic pour les migrations de schéma en production plutôt que create_all(). Les colonnes peuvent être indexées, nullables, et avoir des défauts appliqués au niveau base ou Python.
from sqlalchemy import Column, Integer, String, Boolean
from sqlalchemy.orm import declarative_base
Base = declarative_base()
class Item(Base):
__tablename__ = "items"
id = Column(Integer, primary_key=True, index=True)
name = Column(String, index=True, nullable=False)
price = Column(Integer, default=0)
in_stock = Column(Boolean, default=True)
# create tables (for dev; use Alembic migrations in prod)
Base.metadata.create_all(bind=engine)Créer un enregistrement
add() met en attente une nouvelle ligne, commit() l'écrit en base, et refresh() recharge l'instance avec les valeurs générées par le serveur (comme l'id auto-incrémenté). Enveloppez plusieurs écritures dans une transaction et commitez une fois à la fin.
from fastapi import FastAPI, Depends
from sqlalchemy.orm import Session
app = FastAPI()
@app.post("/items", status_code=201)
def create_item(payload: ItemCreate, db: Session = Depends(get_db)):
item = Item(name=payload.name, price=payload.price)
db.add(item)
db.commit()
db.refresh(item) # load generated id
return itemRequêter des enregistrements
db.query(Model) démarre une requête ; .filter() applique les conditions WHERE, .offset()/.limit() paginent, .first() renvoie une ligne ou None, .all() une liste. Utilisez .filter_by(name=x) pour des conditions d'égalité simples.
from fastapi import FastAPI, Depends, HTTPException
from sqlalchemy.orm import Session
app = FastAPI()
@app.get("/items")
def list_items(skip: int = 0, limit: int = 10, db: Session = Depends(get_db)):
return db.query(Item).offset(skip).limit(limit).all()
@app.get("/items/{item_id}")
def get_item(item_id: int, db: Session = Depends(get_db)):
item = db.query(Item).filter(Item.id == item_id).first()
if not item:
raise HTTPException(status_code=404, detail="not found")
return itemMise à jour et suppression
Pour les mises à jour partielles, itérez model_dump(exclude_unset=True) pour que seuls les champs fournis changent. delete() met en attente la suppression ; commit() la finalise. Renvoyez 204 No Content pour un DELETE réussi.
from fastapi import FastAPI, Depends, HTTPException
from sqlalchemy.orm import Session
app = FastAPI()
@app.put("/items/{item_id}")
def update_item(item_id: int, payload: ItemUpdate, db: Session = Depends(get_db)):
item = db.query(Item).filter(Item.id == item_id).first()
if not item:
raise HTTPException(status_code=404, detail="not found")
for k, v in payload.model_dump(exclude_unset=True).items():
setattr(item, k, v)
db.commit()
db.refresh(item)
return item
@app.delete("/items/{item_id}", status_code=204)
def delete_item(item_id: int, db: Session = Depends(get_db)):
item = db.query(Item).filter(Item.id == item_id).first()
if item:
db.delete(item)
db.commit()Base de données (Tortoise ORM)
Configuration Tortoise
Tortoise ORM est natif asynchrone, s'accordant bien avec FastAPI. Initialisez-le au démarrage avec db_url et le(s) module(s) contenant vos modèles. generate_schemas() convient en dev ; utilisez Aerich pour les migrations en production. Préférez le handler lifespan à on_event dans le code neuf.
from fastapi import FastAPI
from tortoise import Tortoise
app = FastAPI()
async def init():
await Tortoise.init(
db_url="sqlite://db.sqlite3",
modules={"models": ["app.models"]},
)
await Tortoise.generate_schemas()
@app.on_event("startup")
async def startup():
await init()
@app.on_event("shutdown")
async def shutdown():
await Tortoise.close_connections()Définition de modèle
Les modèles Tortoise héritent de Model et déclarent les champs via tortoise.fields. Les types de champs correspondent aux types de colonnes DB. Fixez le nom de table dans la classe Meta interne. Les relations utilisent ForeignKeyField, ManyToManyField, etc.
from tortoise import fields
from tortoise.models import Model
class Item(Model):
id = fields.IntField(pk=True)
name = fields.CharField(max_length=100)
price = fields.FloatField(default=0.0)
created_at = fields.DatetimeField(auto_now_add=True)
class Meta:
table = "items"
def __str__(self):
return self.nameCréer un enregistrement
Item.create() est une coroutine qui insère et renvoie la nouvelle ligne. Pour renvoyer une réponse Pydantic, construisez un BaseModel avec from_tortoise_orm() (via tortoise.contrib.pydantic) pour que Tortoise sérialise correctement les relations chargées async.
from fastapi import FastAPI
from pydantic import BaseModel
from .models import Item
app = FastAPI()
class ItemIn(BaseModel):
name: str
price: float
@app.post("/items", response_model=ItemOut, status_code=201)
async def create_item(payload: ItemIn):
item = await Item.create(name=payload.name, price=payload.price)
return await ItemOut.from_tortoise_orm(item)Requête asynchrone
Les requêtes Tortoise s'attendent : .all() renvoie un queryset, .filter() ajoute des conditions, .get_or_none() récupère une ligne ou None, .first() le premier match. Évitez .get() sauf si vous attendez exactement une ligne (il lève si introuvable).
from fastapi import FastAPI, HTTPException
from .models import Item
app = FastAPI()
@app.get("/items")
async def list_items(skip: int = 0, limit: int = 10):
return await Item.all().offset(skip).limit(limit)
@app.get("/items/{item_id}")
async def get_item(item_id: int):
item = await Item.get_or_none(id=item_id)
if not item:
raise HTTPException(status_code=404, detail="not found")
return itemMise à jour et suppression
Modifiez les attributs du modèle puis await save() pour mettre à jour une ligne, ou await Item.filter(id=...).update(name=x) pour des mises à jour en masse. await item.delete() retire la ligne. Chaque méthode est une coroutine et doit être attendue.
from fastapi import FastAPI, HTTPException
from .models import Item
app = FastAPI()
@app.put("/items/{item_id}")
async def update_item(item_id: int, name: str):
item = await Item.get_or_none(id=item_id)
if not item:
raise HTTPException(status_code=404, detail="not found")
item.name = name
await item.save()
return item
@app.delete("/items/{item_id}", status_code=204)
async def delete_item(item_id: int):
item = await Item.get_or_none(id=item_id)
if item:
await item.delete()Schémas Pydantic Tortoise
tortoise.contrib.pydantic génère des modèles Pydantic directement depuis les modèles Tortoise, vous ne maintenez donc pas deux schémas. Utilisez pydantic_model_creator pour un objet unique et pydantic_queryset_creator pour une réponse en liste.
from tortoise.contrib.pydantic import pydantic_model_creator, pydantic_queryset_creator
from .models import Item
ItemOut = pydantic_model_creator(Item, name="ItemOut")
ItemList = pydantic_queryset_creator(Item)
@app.get("/items", response_model=ItemList)
async def list_items():
return await Item.all()
# auto-generates a Pydantic model from the Tortoise model,
# including types and docstrings.Tests (TestClient)
TestClient de base
TestClient enveloppe votre app et permet des requêtes dans le processus (pas de vrai socket). Il repose sur httpx et fonctionne avec pytest sans configuration. Importez la même instance d'app que celle exécutée en production.
from fastapi.testclient import TestClient
from main import app
client = TestClient(app)
def test_root():
response = client.get("/")
assert response.status_code == 200
assert response.json() == {"Hello": "World"}
# TestClient is based on httpx; no network is involved —
# it calls the ASGI app directly in-process.Tester GET et POST
Passez json= pour les corps JSON, params= pour les paramètres de requête, headers= pour les en-têtes, et files= pour les uploads multipart. Les échecs de validation renvoient 422 — affirmez sur status_code et la structure du 'detail' d'erreur.
from fastapi.testclient import TestClient
from main import app
client = TestClient(app)
def test_create_item():
response = client.post(
"/items",
json={"name": "Apple", "price": 0.5},
)
assert response.status_code == 201
assert response.json()["name"] == "Apple"
def test_validation_error():
response = client.post("/items", json={"name": "Apple"}) # missing price
assert response.status_code == 422Fixture pytest
Une fixture pytest renvoyant un TestClient évite la répétition et donne à chaque test un client frais. Pour les tests avec base de données, ajoutez une fixture qui crée/supprime les tables ou utilise un rollback de transaction par test pour les isoler.
import pytest
from fastapi.testclient import TestClient
from main import app
@pytest.fixture
def client():
return TestClient(app)
def test_read(client):
r = client.get("/items")
assert r.status_code == 200
def test_create(client):
r = client.post("/items", json={"name": "X"})
assert r.status_code == 201
# run: pytest -vSurcharger les dépendances
app.dependency_overrides remplace une dépendance (comme la vraie session DB ou l'auth) par un mock/fake pendant les tests, sans toucher aux routes. C'est la façon canonique de tester les endpoints isolés des services externes. Videz-le après les tests.
from fastapi.testclient import TestClient
from main import app, get_db
def get_test_db():
# return a test session or mock
yield FakeSession()
app.dependency_overrides[get_db] = get_test_db
client = TestClient(app)
def test_items():
r = client.get("/items")
assert r.status_code == 200
# restore afterwards:
app.dependency_overrides.clear()Tester l'authentification
OAuth2PasswordRequestForm attend des données encodées en formulaire (data=, pas json=). Utilisez le token renvoyé dans l'en-tête Authorization: Bearer pour les requêtes protégées suivantes. Pour contourner entièrement l'auth, surchargez plutôt la dépendance get_current_user.
from fastapi.testclient import TestClient
from main import app
client = TestClient(app)
def get_token():
r = client.post(
"/token",
data={"username": "admin", "password": "secret"},
)
return r.json()["access_token"]
def test_protected():
token = get_token()
r = client.get(
"/me",
headers={"Authorization": f"Bearer {token}"},
)
assert r.status_code == 200
assert r.json()["username"] == "admin"Tester le WebSocket
TestClient.websocket_connect() ouvre un WebSocket dans un gestionnaire de contexte. Utilisez send_text/receive_text (et les variantes json/bytes) pour échanger des messages. Recevoir sur une connexion fermée lève WebSocketDisconnect.
from fastapi.testclient import TestClient
from main import app
client = TestClient(app)
def test_websocket():
with client.websocket_connect("/ws") as ws:
ws.send_text("hello")
data = ws.receive_text()
assert data == "echo: hello"
def test_websocket_close():
with client.websocket_connect("/ws") as ws:
ws.send_text("quit")
# the server closes the connectionDocumentation OpenAPI
Swagger UI
FastAPI génère automatiquement une Swagger UI interactive à /docs à partir de vos routes, types et docstrings. Réglez title/description/version sur l'app, et ajoutez une docstring ou summary/description à chaque route pour enrichir l'UI.
from fastapi import FastAPI
app = FastAPI(
title="My API",
description="Sample API with auto docs",
version="1.0.0",
)
@app.get("/items", summary="List items", description="Returns all items")
def list_items():
"""Get every item in the catalog."""
return [{"id": 1}]
# interactive docs at: http://localhost:8000/docsReDoc
ReDoc à /redoc est une alternative en lecture seule, centrée sur la documentation. Le schéma OpenAPI brut vit à /openapi.json et peut alimenter d'autres outils. Désactivez la doc avec docs_url=None, redoc_url=None, openapi_url=None (ex. en production).
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
def root():
return {"hello": "world"}
# ReDoc (alternative docs UI) at: http://localhost:8000/redoc
# raw OpenAPI JSON at: http://localhost:8000/openapi.json
# disable docs entirely:
# app = FastAPI(docs_url=None, redoc_url=None, openapi_url=None)Tags et regroupement
Les tags regroupent les routes dans l'UI de doc. Déclarez les métadonnées de tags (name, description, externalDocs) dans openapi_tags pour que le groupe apparaisse même avant toute route qui l'utilise. Mettez deprecated=True pour marquer un endpoint comme déprécié dans la doc.
from fastapi import FastAPI
app = FastAPI(openapi_tags=[
{"name": "users", "description": "User management"},
{"name": "items", "description": "Item operations"},
])
@app.get("/users", tags=["users"])
def list_users(): ...
@app.post("/items", tags=["items"])
def create_item(): ...
@app.get("/items/{id}", tags=["items"], deprecated=True)
def get_item(id: int): ...Métadonnées de route
Les décorateurs acceptent des métadonnées qui alimentent OpenAPI : summary (titre court), description (texte long), response_description, tags, deprecated et status_code. Une docstring sert de description si vous n'en passez pas explicitement.
from fastapi import FastAPI, status
from pydantic import BaseModel
class Item(BaseModel):
name: str
price: float
app = FastAPI()
@app.post(
"/items",
response_model=Item,
status_code=status.HTTP_201_CREATED,
summary="Create an item",
description="Creates a new item and returns it.",
tags=["items"],
response_description="The created item",
)
def create_item(item: Item):
"""Create endpoint docstring — also shown in docs."""
return itemExemples de champs
Field(examples=[...]) et Body(examples=[...]) ajoutent des charges utiles d'exemple au « Try it out » de Swagger UI et au menu déroulant d'exemples. Les exemples de Body peuvent inclure plusieurs cas avec des résumés pour montrer des entrées valides et invalides.
from pydantic import BaseModel, Field
from fastapi import FastAPI, Body
class Item(BaseModel):
name: str = Field(examples=["Apple"])
price: float = Field(examples=[0.5], gt=0)
app = FastAPI()
@app.post("/items")
def create_item(item: Item):
return item
@app.post("/manual")
def manual(
item: Item = Body(
examples=[
{"summary": "valid", "value": {"name": "Apple", "price": 0.5}},
{"summary": "invalid", "value": {"name": "Apple", "price": -1}},
],
),
):
return itemSchéma OpenAPI personnalisé
Surchargez app.openapi pour personnaliser le schéma généré — ajouter un logo, des métadonnées supplémentaires, ou retirer/transformer des opérations. Mettez le résultat en cache dans app.openapi_schema pour qu'il ne soit généré qu'une fois. Le schéma est ce que sert /openapi.json.
from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi
app = FastAPI()
def custom_openapi():
if app.openapi_schema:
return app.openapi_schema
schema = get_openapi(
title="Custom API",
version="2.0.0",
routes=app.routes,
)
schema["info"]["x-logo"] = {"url": "https://example.com/logo.png"}
app.openapi_schema = schema
return schema
app.openapi = custom_openapiDéploiement (Uvicorn / Gunicorn)
Uvicorn en production
En production, exécutez Uvicorn derrière un reverse proxy (Nginx, Caddy, un load balancer cloud). Utilisez --proxy-headers pour que l'app voie la vraie IP/hôte du client depuis X-Forwarded-For/X-Forwarded-Proto. Évitez --reload en production.
# Run directly with uvicorn (single worker)
uvicorn main:app --host 0.0.0.0 --port 8000 --workers 1
# Recommended: behind a reverse proxy (nginx) on port 8000
# Use --proxy-headers so X-Forwarded-* is trusted
uvicorn main:app --host 0.0.0.0 --port 8000 --proxy-headers --forwarded-allow-ips='*'Gunicorn avec workers Uvicorn
Gunicorn gère plusieurs processus workers Uvicorn, offrant des recharges gracieuses, des redémarrages après crash et un scaling pré-fork. Utilisez la classe UvicornWorker. Commencez avec workers à (2 * cœurs CPU + 1), puis benchmarkez.
# install the uvicorn worker class
pip install "uvicorn[standard]" gunicorn
# run 4 worker processes managed by gunicorn
gunicorn main:app \
-w 4 \
-k uvicorn.workers.UvicornWorker \
-b 0.0.0.0:8000 \
--timeout 120
# -w workers (commonly 2*CPU+1), -k worker classDéploiement Docker
Une image de base Python slim garde l'image légère. Installez les dépendances avant de copier le code pour exploiter le cache de couches de Docker. Exécutez avec des workers gunicorn+uvicorn dans le conteneur, et exposez le port 8000 à l'hôte ou à l'orchestrateur.
# Dockerfile
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["gunicorn", "main:app", "-w", "4", \
"-k", "uvicorn.workers.UvicornWorker", \
"-b", "0.0.0.0:8000"]
# build & run:
# docker build -t myapi .
# docker run -p 8000:8000 myapiConfiguration par environnement
pydantic-settings (ex-pydantic.BaseSettings) charge la config depuis les variables d'environnement et les fichiers .env avec validation de type. La même image peut ainsi tourner dans différents environnements (dev/staging/prod) en changeant simplement les variables.
import os
from pydantic_settings import BaseSettings
class Settings(BaseSettings):
database_url: str = "sqlite:///./app.db"
secret_key: str = "change-me"
debug: bool = False
allowed_origins: list[str] = ["http://localhost:3000"]
class Config:
env_file = ".env"
env_file_encoding = "utf-8"
settings = Settings()
# .env file:
# DATABASE_URL=postgresql://user:pass@db:5432/app
# SECRET_KEY=long-random-string
# DEBUG=falseReverse proxy Nginx
Nginx termine le HTTP(S) et transmet à Uvicorn sur localhost:8000. Réglez les en-têtes X-Forwarded-* (et utilisez --proxy-headers sur Uvicorn) pour que l'app voie la vraie IP et le schéma du client. Les lignes Upgrade/Connection activent le support WebSocket.
# /etc/nginx/conf.d/api.conf
server {
listen 80;
server_name api.example.com;
location / {
proxy_pass http://127.0.0.1:8000;
proxy_set_header Host \$host;
proxy_set_header X-Real-IP \$remote_addr;
proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto \$scheme;
proxy_http_version 1.1;
proxy_set_header Upgrade \$http_upgrade;
proxy_set_header Connection "upgrade";
}
}Scaling et concurrence
Deux axes de montée en charge : plus de processus workers Uvicorn par machine (lié au CPU), et plus de machines derrière un load balancer (horizontal). Pour les apps asynchrones, la boucle d'événements gère de nombreuses requêtes I/O concurrentes par worker. Ajoutez un endpoint /health pour que les orchestrateurs (k8s, ECS) sondent l'état de vie.
# Workers = process count (vertical scaling); pick ~2*CPU
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker
# Inside async app: concurrency is cooperative via the event loop.
# CPU-bound work blocks it — offload to a threadpool or task queue.
# Horizontal scaling: run several containers behind a load balancer.
# Use a shared store (Redis) for session state and rate limits.
# Health check endpoint for the balancer:
@app.get("/health")
def health():
return {"status": "ok"}Sujets avancés
Événements de lifespan
Le gestionnaire de contexte lifespan remplace les handlers dépréciés on_event('startup'/'shutdown'). Le code avant yield s'exécute au démarrage ; celui après yield à l'arrêt, même si le démarrage échoue. Servez-vous en pour initialiser les connexions DB, les modèles ML et les caches.
from contextlib import asynccontextmanager
from fastapi import FastAPI
@asynccontextmanager
async def lifespan(app: FastAPI):
# runs at startup
print("starting up")
app.state.cache = {}
yield
# runs at shutdown
print("shutting down")
await app.state.cache.clear()
app = FastAPI(lifespan=lifespan)
# the old @app.on_event("startup") / "shutdown" are deprecated
# in favor of the lifespan handler above.Sous-applications (mount)
app.mount() attache une sous-application sous un préfixe de chemin, utile pour des API versionnées ou combiner plusieurs apps. Chaque sous-app a ses propres routes et schéma OpenAPI ; la doc du parent n'inclut pas les routes de l'enfant par défaut.
from fastapi import FastAPI
app = FastAPI()
api_v1 = FastAPI()
api_v2 = FastAPI()
@api_v1.get("/items")
def v1_items():
return {"version": 1}
@api_v2.get("/items")
def v2_items():
return {"version": 2}
app.mount("/v1", api_v1)
app.mount("/v2", api_v2)
# GET /v1/items -> {"version": 1}
# GET /v2/items -> {"version": 2}APIRouter
APIRouter regroupe des routes liées dans un module avec préfixe, tags, dépendances et réponses partagés. Incluez-le via app.include_router(router) (éventuellement avec son propre préfixe ou ses tags). C'est le pattern standard pour structurer des apps non triviales.
from fastapi import APIRouter, Depends
router = APIRouter(
prefix="/items",
tags=["items"],
dependencies=[Depends(verify_token)],
responses={404: {"description": "Not found"}},
)
@router.get("/")
def list_items():
return []
@router.get("/{item_id}")
def get_item(item_id: int):
return {"id": item_id}
# in main.py: app.include_router(router)Fichiers statiques
StaticFiles sert un répertoire de ressources statiques (images, CSS, JS) à un préfixe d'URL. Montez-le une fois par répertoire. Pour des frontends SPA, montez une route finale fourre-tout pointant vers index.html. Les fichiers statiques contournent le système de routage pour la rapidité.
from fastapi import FastAPI
from fastapi.staticfiles import StaticFiles
app = FastAPI()
# serve files from ./static at /static
app.mount("/static", StaticFiles(directory="static"), name="static")
# /static/logo.png -> ./static/logo.png
# /static/css/app.css -> ./static/css/app.cssRéponse en flux
StreamingResponse envoie une réponse générée par tranches (un générateur/itérateur) au lieu de construire tout le corps en mémoire — idéal pour les exports CSV volumineux, le streaming de fichiers ou le SSE. Réglez media_type en conséquence pour que les clients gèrent le flux correctement.
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
import csv, io
app = FastAPI()
def iter_csv():
output = io.StringIO()
writer = csv.writer(output)
writer.writerow(["id", "name"])
for i in range(1000):
writer.writerow([i, f"name-{i}"])
yield output.getvalue()
output.seek(0)
output.truncate(0)
@app.get("/export.csv")
def export():
return StreamingResponse(
iter_csv(),
media_type="text/csv",
headers={"Content-Disposition": "attachment; filename=export.csv"},
)Classe de route personnalisée
Hériter d'APIRoute permet d'envelopper chaque handler de route avec une logique personnalisée (logging, tracing, timing) sans toucher à chaque endpoint. Réglez app.router.route_class ou passez route_class à APIRouter. Le handler s'exécute pour chaque requête correspondante.
from fastapi import FastAPI, Request, Response
from fastapi.routing import APIRoute
from typing import Callable
class LoggingRoute(APIRoute):
def get_route_handler(self) -> Callable:
original = super().get_route_handler()
async def handler(request: Request) -> Response:
print(f"-> {request.method} {request.url.path}")
response = await original(request)
print(f"<- {response.status_code}")
return response
return handler
app = FastAPI()
app.router.route_class = LoggingRoute
@app.get("/items")
def items():
return {"items": []}Snippets FastAPI associés
Copy-paste ready code for common tasks.
Path Parameters
Capture typed path segments with validation.
Query Parameters
Parse query strings with defaults and validation.
Pydantic Request Body
Validate JSON bodies with Pydantic models.
Dependency Injection
Share logic via Depends and yield-based dependencies.
Response Model
Shape and filter responses with response_model.
JWT Auth
Issue and verify JSON Web Tokens with OAuth2.
Async and Await
Define async handlers and run blocking work in a thread.
Middleware
Add CORS, timing, and custom middleware.
Was this helpful?