Démarrage
Première application
Flask est un microframework — il fournit l'essentiel et vous laisse ajouter ce dont vous avez besoin. debug=True active le rechargement automatique et des pages d'erreur détaillées.
# install Flask
pip install flask
# app.py
from flask import Flask, render_template
app = Flask(__name__)
@app.route("/")
def home():
return render_template("index.html")
if __name__ == "__main__":
app.run(debug=True)Lancer le serveur de développement
N'utilisez jamais le serveur intégré en production. FLASK_APP pointe vers le module contenant l'instance d'app. Utilisez --host=0.0.0.0 pour le rendre joignable sur le réseau.
# Set the entry point and enable debug mode
export FLASK_APP=app.py
export FLASK_ENV=development
flask run
# Override host and port
flask run --host=0.0.0.0 --port=5000
# Or run the module directly
python app.pyEnvironnement virtuel
Un environnement virtuel isole les dépendances du projet du Python système. requirements.txt enregistre les versions exactes pour que d'autres reproduisent l'environnement avec pip install -r requirements.txt.
# Create an isolated environment
python -m venv venv
# Activate (Linux/macOS)
source venv/bin/activate
# Activate (Windows PowerShell)
venv\Scripts\Activate.ps1
# Install dependencies
pip install flask
pip freeze > requirements.txtStructure de projet
Flask n'impose pas de disposition, mais séparer fichiers statiques, templates et config est la convention. Le dossier instance/ héberge les secrets propres au déploiement qui ne doivent pas être versionnés.
myapp/
app.py # application factory or instance
config.py # configuration classes
requirements.txt # pinned dependencies
instance/
config.py # secret instance config (not in VCS)
static/ # CSS, JS, images
css/style.css
templates/ # Jinja2 templates
base.html
index.html
models.py # database models
views.py # route handlersPattern de factory d'application
Le pattern factory diffère la création de l'app jusqu'à l'appel d'une fonction, ce qui est essentiel pour les instances multiples, les tests et les extensions. L'option --app de Flask accepte un callable qui renvoie une app.
from flask import Flask
def create_app(config_name="default"):
app = Flask(__name__)
app.config.from_object(f"config.{config_name.title()}Config")
from .views import bp as views_bp
app.register_blueprint(views_bp)
@app.route("/health")
def health():
return {"status": "ok"}
return app
# Run with: flask --app myapp create_app run
# or export FLASK_APP=myapp:create_appAnatomie d'une application minimale
Passer __name__ indique à Flask où trouver les fichiers statiques et les templates. Vous pouvez remplacer les emplacements des dossiers par des arguments de constructeur si votre disposition diffère des défauts.
from flask import Flask
app = Flask(
__name__,
static_folder="static",
template_folder="templates",
static_url_path="/static",
)
# __name__ lets Flask locate resources relative to the module.
# Route decorators map URL patterns to view functions.
@app.route("/")
def index():
return "Hello, Flask!"Routage
Règles à variables
Les sections marquées <converter:varname> capturent des segments d'URL. Convertisseurs intégrés : string (défaut), int, float, path (accepte les slashes), uuid. La valeur est passée en argument de fonction.
from flask import Flask
app = Flask(__name__)
@app.route("/user/<username>")
def show_user(username):
return f"User: {username}"
@app.route("/post/<int:post_id>")
def show_post(post_id):
return f"Post #{post_id}"
@app.route("/path/<path:subpath>")
def show_path(subpath):
return f"Path: {subpath}"Convertisseurs d'URL
Les convertisseurs valident et castent les variables d'URL. Enregistrez une sous-classe de BaseConverter sur app.url_map.converters pour imposer un motif regex, comme des codes produits.
@app.route("/item/<int:item_id>")
def item_int(item_id):
return f"Integer ID: {item_id}"
@app.route("/weight/<float:kg>")
def weight(kg):
return f"{kg} kg"
@app.route("/uid/<uuid:token>")
def by_token(token):
return str(token)
# Custom converter
from werkzeug.routing import BaseConverter
class RegexConverter(BaseConverter):
def __init__(self, url_map, *items):
super().__init__(url_map)
self.regex = items[0]
app.url_map.converters["re"] = RegexConverter
@app.route("/code/<re:[a-z]{3}-[0-9]{4}:code>")
def code(code):
return codeURLs uniques et redirection
Les slashes finaux comptent. Une route finissant par '/' redirige la forme sans slash ; une route sans '/' renvoie 404 pour la forme avec slash. Choisissez une convention par route et restez cohérent.
@app.route("/projects/")
def projects():
return "Projects page"
# /projects/ -> 200 OK
# /projects -> 301 redirect to /projects/
@app.route("/about")
def about():
return "About page"
# /about -> 200 OK
# /about/ -> 404 Not FoundMéthodes HTTP
Utilisez l'argument methods pour accepter plusieurs verbes, ou les raccourcis @app.get / @app.post (Flask 2.0+) pour des routes à méthode unique. GET est le défaut.
from flask import request, render_template
@app.route("/login", methods=["GET", "POST"])
def login():
if request.method == "POST":
return do_login()
return render_template("login.html")
# Method-specific shortcuts
@app.get("/profile")
def profile_get():
return render_template("profile.html")
@app.post("/profile")
def profile_post():
return update_profile()Construire des URLs avec url_for
url_for génère des URLs depuis le nom d'endpoint (le nom de la fonction de vue par défaut). Il survit aux changements d'URL et produit des URLs absolues avec _external=True.
from flask import Flask, url_for
app = Flask(__name__)
@app.route("/")
def index():
# builds '/user/alice' instead of hardcoding
return f'<a href="{url_for("show_user", username="alice")}">Alice</a>'
@app.route("/user/<username>")
def show_user(username):
return f"Hello {username}"
with app.test_request_context():
print(url_for("show_user", username="bob")) # /user/bobPlusieurs règles pour une vue
add_url_rule enregistre une URL sans décorateur. En donnant à chaque règle un endpoint distinct mais la même fonction de vue avec des défauts, un handler sert plusieurs formes d'URL.
from flask import Flask
app = Flask(__name__)
def show(id=None, name=None):
if id is not None:
return f"By id: {id}"
return f"By name: {name}"
app.add_url_rule("/by-id/<int:id>", "by_id", show, defaults={"name": None})
app.add_url_rule("/by-name/<name>", "by_name", show, defaults={"id": None})
# Two endpoints share one function with different defaults.Requête et réponse
L'objet Request
request est un proxy thread-local lié au contexte de la requête courante. Il expose l'URL, la méthode, les en-têtes, le corps et les infos client sans être passé explicitement.
from flask import Flask, request
app = Flask(__name__)
@app.route("/info")
def info():
return {
"url": request.url,
"method": request.method,
"remote_addr": request.remote_addr,
"user_agent": str(request.user_agent),
"headers": dict(request.headers),
}Fabriquer une réponse
make_response donne un contrôle total sur statut, en-têtes et corps. Pour les cas simples, renvoyez une chaîne, un dict (JSON) ou un tuple (corps, statut, en-têtes).
from flask import Flask, make_response
app = Flask(__name__)
@app.route("/")
def index():
resp = make_response("Hello, World!")
resp.status_code = 201
resp.headers["X-Custom"] = "yes"
resp.set_cookie("visited", "1")
return resp
# Returning a tuple: (body, status, headers)
@app.route("/quick")
def quick():
return "OK", 202, {"X-Quick": "1"}Objets Response
Utilisez Response quand vous avez besoin d'un mimetype personnalisé (ex. XML, CSV) ou d'en-têtes. Régler Content-Disposition sur attachment force un téléchargement dans le navigateur.
from flask import Response
@app.route("/xml")
def xml():
return Response("<msg>hi</msg>", mimetype="application/xml")
@app.route("/text")
def text():
return Response("plain text", mimetype="text/plain")
@app.route("/csv")
def csv():
body = "a,b,c\n1,2,3\n"
headers = {"Content-Disposition": "attachment; filename=data.csv"}
return Response(body, mimetype="text/csv", headers=headers)Statut et en-têtes personnalisés
Renvoyez un tuple (corps, statut, en-têtes) pour des réponses personnalisées concises. Utilisez 204 No Content pour des réponses réussies sans corps, et les codes de statut HTTP standards pour la sémantique.
@app.route("/created")
def created():
return "done", 201, {"Location": "/resource/1"}
@app.route("/no-content")
def no_content():
return "", 204
@app.route("/teapot")
def teapot():
return "I'm a teapot", 418Réponses en flux
Une valeur de retour générateur envoie les données en flux au client. Utile pour les gros fichiers (évite de tout charger en mémoire) et les Server-Sent Events. Réglez un mimetype approprié.
from flask import Response
def generate():
yield "data: first\n\n"
yield "data: second\n\n"
yield "data: third\n\n"
@app.route("/stream")
def stream():
return Response(generate(), mimetype="text/event-stream")
@app.route("/big-file")
def big_file():
def chunks():
with open("large.log", "rb") as f:
while chunk := f.read(8192):
yield chunk
return Response(chunks(), mimetype="application/octet-stream")Cookies dans la réponse
set_cookie écrit un en-tête Set-Cookie ; delete_cookie l'expire. Réglez toujours httponly et samesite pour la sécurité. Les cookies font partie de la réponse, pas du corps de la requête.
from flask import make_response
@app.route("/set-theme")
def set_theme():
resp = make_response("theme set")
resp.set_cookie("theme", "dark", max_age=30*86400, httponly=True, samesite="Lax")
return resp
@app.route("/clear-theme")
def clear_theme():
resp = make_response("cleared")
resp.delete_cookie("theme")
return respObjet Request (form/args/files)
Paramètres de requête (args)
request.args est un MultiDict des valeurs de la query string. Utilisez get avec un défaut et une conversion de type, et getlist pour les clés répétées. N'indexez jamais directement — les clés manquantes lèvent un 400.
from flask import request
@app.route("/search")
def search():
q = request.args.get("q", "") # default ""
page = request.args.get("page", 1, type=int)
tags = request.args.getlist("tag") # /search?tag=a&tag=b -> ["a","b"]
return {"q": q, "page": page, "tags": tags}Données de formulaire
request.form porte les données application/x-www-form-urlencoded ou multipart envoyées en POST. Utilisez .get() pour éviter les KeyError sur les champs optionnels. Les requêtes GET ont un form vide.
from flask import request, render_template
@app.route("/login", methods=["GET", "POST"])
def login():
if request.method == "POST":
username = request.form.get("username")
password = request.form.get("password")
if not username or not password:
return "Missing fields", 400
return f"Welcome {username}"
return render_template("login.html")Uploads de fichiers
request.files est un MultiDict d'objets FileStorage. Faites toujours passer les noms de fichiers fournis par les utilisateurs dans secure_filename pour retirer séparateurs de chemins et caractères dangereux avant enregistrement.
from flask import request
from werkzeug.utils import secure_filename
import os
@app.route("/upload", methods=["POST"])
def upload():
file = request.files.get("file")
if not file or file.filename == "":
return "No file", 400
name = secure_filename(file.filename)
file.save(os.path.join("uploads", name))
return "saved"Corps JSON
get_json() parse le corps en JSON seulement si le Content-Type est application/json. force=True ignore l'en-tête (à utiliser avec prudence). silent=True supprime les erreurs de parsing.
from flask import request
@app.route("/api/echo", methods=["POST"])
def echo():
data = request.get_json() # returns None if not JSON
if data is None:
return "Expected JSON", 415
return {"you_sent": data}
# Force parsing even without the right header (risky)
@app.route("/api/force")
def force():
data = request.get_json(force=True)
return dataEn-têtes et cookies
request.headers est un objet EnvironHeaders semblable à un dict ; request.cookies porte les cookies entrants envoyés par le client. Les deux sont en lecture seule — réglez les en-têtes/cookies sur la réponse.
from flask import request
@app.route("/inspect")
def inspect():
auth = request.headers.get("Authorization")
accept = request.headers.get("Accept")
session_id = request.cookies.get("session_id")
return {
"auth": auth,
"accept": accept,
"session_id": session_id,
}Méthodes et propriétés de Request
request expose les métadonnées de la connexion et du corps. is_json vérifie le Content-Type, is_secure vérifie le HTTPS, et query_string est les octets bruts après '?'.
from flask import request
@app.route("/state")
def state():
return {
"method": request.method,
"is_xhr": request.is_json,
"content_type": request.content_type,
"content_length": request.content_length,
"is_secure": request.is_secure,
"scheme": request.scheme,
"host": request.host,
"path": request.path,
"query_string": request.query_string.decode(),
}Templates Jinja2
Rendre des templates
render_template charge un fichier Jinja2 depuis le dossier templates/ et injecte les arguments nommés comme variables. La syntaxe {{ }} affiche une expression ; Flask échappe automatiquement le HTML par sécurité.
from flask import render_template
@app.route("/<name>")
def hello(name):
return render_template("hello.html", name=name, title="Welcome")
# templates/hello.html
# <!DOCTYPE html>
# <html>
# <head><title>{{ title }}</title></head>
# <body>
# <h1>Hello {{ name }}!</h1>
# </body>
# </html>Variables de template
Jinja2 gère l'accès attribut (user.name) et l'accès item (user['age']). Le filtre safe marque une chaîne comme fiable pour ne pas l'échapper — ne l'employez que sur du contenu que vous contrôlez entièrement.
# View
@app.route("/")
def index():
return render_template(
"index.html",
user={"name": "Alice", "age": 30},
items=["apple", "banana", "cherry"],
html_content="<b>safe?</b>",
)
# Template
# <p>Name: {{ user.name }}</p>
# <p>Age: {{ user["age"] }}</p>
# <p>First: {{ items[0] }}</p>
# <p>Raw HTML: {{ html_content | safe }}</p>Structures de contrôle
Jinja2 gère {% if %}, {% for %} et {% block %}. Dans les boucles, la variable spéciale loop donne index, index0, first, last, length et revindex. Le for-else s'exécute quand l'itérable est vide.
{# if / elif / else #}
{% if user.age >= 18 %}
Adult
{% elif user.age >= 13 %}
Teen
{% else %}
Child
{% endif %}
{# for loop #}
<ul>
{% for item in items %}
<li>{{ loop.index }}: {{ item }}</li>
{% else %}
<li>No items</li>
{% endfor %}
</ul>Héritage de templates
extends tire un template de base et les templates enfants remplacent les blocs nommés. Cela garde la disposition partagée (navigation, scripts) à un seul endroit. super() rend le contenu du bloc parent.
{# templates/base.html #}
<!DOCTYPE html>
<html>
<head>
<title>{% block title %}Default{% endblock %}</title>
</head>
<body>
{% block content %}{% endblock %}
</body>
</html>
{# templates/child.html #}
{% extends "base.html" %}
{% block title %}Home{% endblock %}
{% block content %}
<h1>Welcome home</h1>
{% endblock %}Filtres
Les filtres transforment les valeurs via la syntaxe pipe (|) et acceptent des arguments. Enregistrez des filtres personnalisés sur app.jinja_env.filters pour réutiliser la logique entre templates.
{{ name | capitalize }} {# alice -> Alice #}
{{ price | round(2) }} {# 3.14159 -> 3.14 #}
{{ items | length }} {# count #}
{{ text | truncate(20) }} {# shorten #}
{{ tags | join(", ") }} {# ["a","b"] -> "a, b" #}
{{ value | default("n/a") }} {# fallback #}
{{ html | striptags }} {# remove HTML tags #}
{# Custom filter #}
def reverse_filter(s):
return s[::-1]
app.jinja_env.filters["reverse"] = reverse_filter
{{ "hello" | reverse }} {# olleh #}Macros
Les macros sont des extraits de template réutilisables, comme des fonctions. Importez-les avec {% from %} ou {% import %}. Elles gardent le HTML répétitif (champs de formulaire, cartes) DRY.
{# templates/macros.html #}
{% macro input(name, value="", type="text") %}
<input type="{{ type }}" name="{{ name }}" value="{{ value }}">
{% endmacro %}
{% macro label(text, for_id) %}
<label for="{{ for_id }}">{{ text }}</label>
{% endmacro %}
{# In another template #}
{% from "macros.html" import input, label %}
<form>
{{ label("Username", "u") }}
{{ input("username") }}
{{ label("Password", "p") }}
{{ input("password", type="password") }}
</form>Fichiers statiques
Servir des fichiers statiques
Flask enregistre automatiquement une route /static/<path:filename> pour le dossier static. Construisez toujours les URLs avec url_for pour que les chemins restent corrects même si static_url_path change.
# Files in the static/ folder are served at /static/<filename>
# static/css/style.css -> http://localhost:5000/static/css/style.css
# Reference them in templates
# <link rel="stylesheet" href="{{ url_for('static', filename='css/style.css') }}">
# <script src="{{ url_for('static', filename='js/app.js') }}"></script>
# <img src="{{ url_for('static', filename='img/logo.png') }}">url_for pour les ressources statiques
url_for('static', filename=...) résout le chemin d'un fichier statique. Passez _external=True pour une URL absolue (utile dans les emails ou flux) et des arguments de requête pour le cache busting.
from flask import Flask, url_for
app = Flask(__name__)
with app.test_request_context():
print(url_for("static", filename="css/style.css"))
# /static/css/style.css
print(url_for("static", filename="js/app.js", _external=True))
# http://localhost/static/js/app.jsDossier statique personnalisé
Remplacez static_folder (emplacement disque) et static_url_path (préfixe d'URL) pour coller aux conventions de votre projet. Le défaut est le dossier 'static' mappé à /static.
from flask import Flask
app = Flask(
__name__,
static_folder="assets", # folder on disk
static_url_path="/public", # URL prefix
)
# Now files in assets/ are served at /public/<filename>
# Template: url_for('static', filename='css/style.css') -> /public/css/style.cssFavicon
Les navigateurs demandent /favicon.ico à la racine par défaut. Ajoutez une route explicite ou liez l'icône via une balise <link>. send_from_directory sert un fichier depuis un répertoire en toute sécurité.
from flask import send_from_directory
import os
@app.route("/favicon.ico")
def favicon():
return send_from_directory(
os.path.join(app.root_path, "static"),
"favicon.ico",
mimetype="image/vnd.microsoft.icon",
)
# Or place favicon.ico in static/ and link it:
# <link rel="icon" href="{{ url_for('static', filename='favicon.ico') }}">Cache busting
Les navigateurs mettent en cache les ressources statiques par URL. Ajouter un hash de version force les clients à récupérer de nouvelles copies après un changement de fichier. Un outil de build (Vite, Flask-Assets) automatise cela dans les grands projets.
# Append a version query param to force reloads
# <link href="{{ url_for('static', filename='css/app.css', v='1.2') }}">
# Or compute a hash at startup
import hashlib, os
def asset_version(filename):
path = os.path.join(app.static_folder, filename)
with open(path, "rb") as f:
return hashlib.md5(f.read()).hexdigest()[:8]
@app.template_filter("bust")
def bust(filename):
v = asset_version(filename)
return url_for("static", filename=filename) + f"?v={v}"
# Template: <link href="{{ 'css/app.css' | bust }}">Blueprints
Créer un Blueprint
Un Blueprint regroupe routes, templates et fichiers statiques liés dans un module. Le premier argument est le nom du blueprint ; url_prefix préfixe un chemin à chaque route qu'il définit.
# auth.py
from flask import Blueprint, render_template
bp = Blueprint("auth", __name__, url_prefix="/auth")
@bp.route("/login")
def login():
return render_template("auth/login.html")
@bp.route("/register")
def register():
return render_template("auth/register.html")Enregistrer des Blueprints
register_blueprint attache un blueprint à l'app. Vous pouvez remplacer url_prefix à l'enregistrement, donc le même blueprint peut se monter sous des chemins différents dans des apps différentes.
from flask import Flask
from auth import bp as auth_bp
from blog import bp as blog_bp
app = Flask(__name__)
app.register_blueprint(auth_bp) # /auth/*
app.register_blueprint(blog_bp, url_prefix="/blog") # /blog/*
# Register later, or with a name override
app.register_blueprint(auth_bp, name="alt_auth")Blueprint avec préfixe d'URL
Définissez url_prefix sur le Blueprint ou à l'enregistrement. Versionner le chemin de l'API (/api/v1) permet d'introduire /api/v2 plus tard sans casser les clients existants.
# api/__init__.py
from flask import Blueprint
bp = Blueprint("api", __name__, url_prefix="/api/v1")
@bp.route("/users")
def list_users():
return {"users": []}
@bp.route("/users/<int:uid>")
def get_user(uid):
return {"id": uid}
# All routes become /api/v1/users...Ressources de Blueprint
Un blueprint peut porter ses propres dossiers templates et static. La résolution des templates regarde d'abord le blueprint, puis l'app, donc les fichiers propres au blueprint l'emportent sur ceux de l'app portant le même nom.
bp = Blueprint(
"admin",
__name__,
url_prefix="/admin",
template_folder="templates", # blueprint-local templates
static_folder="static", # blueprint-local static
)
# Templates: blueprint lookups first, then app templates
# render_template("admin/dashboard.html")
# Static: url_for('admin.static', filename='css/admin.css')Handlers d'erreurs de Blueprint
Les handlers d'erreurs au niveau blueprint n'attrapent que les erreurs levées par les routes de ce blueprint, offrant des pages d'erreur par section. Les handlers au niveau app traitent tout ce qui n'est pas intercepté.
from flask import Blueprint, render_template
bp = Blueprint("blog", __name__)
@bp.errorhandler(404)
def blog_not_found(e):
return render_template("blog/404.html"), 404
@bp.errorhandler(403)
def blog_forbidden(e):
return render_template("blog/403.html"), 403Blueprints imbriqués
Flask 2.0+ gère l'imbrication des blueprints. Enregistrez un blueprint enfant sur un parent avec register_blueprint ; leurs url_prefixes se concatènent, permettant de composer de grandes apps à partir de petits modules.
from flask import Blueprint
parent = Blueprint("parent", __name__, url_prefix="/parent")
child = Blueprint("child", __name__, url_prefix="/child")
@child.route("/info")
def info():
return "nested info"
parent.register_blueprint(child)
app.register_blueprint(parent)
# Final URL: /parent/child/infoContexte (g / session)
Contexte d'application
Le contexte d'application rend current_app et g disponibles hors requête (ex. dans des commandes CLI ou des tâches en arrière-plan). Poussez-le avec app.app_context() quand vous travaillez hors requête.
from flask import current_app, g
@app.route("/")
def index():
app_name = current_app.name
config_value = current_app.config["SECRET_KEY"]
return f"Running {app_name}"
# Push a context manually (scripts, shell)
with app.app_context():
print(current_app.config["DEBUG"])L'objet g
g est un espace de noms par requête pour stocker les ressources partagées comme les connexions à la base. Il se réinitialise à chaque requête et se nettoie dans un handler teardown_appcontext.
from flask import g
import sqlite3
def get_db():
if "db" not in g:
g.db = sqlite3.connect("app.db")
g.db.row_factory = sqlite3.Row
return g.db
@app.teardown_appcontext
def close_db(exc):
db = g.pop("db", None)
if db is not None:
db.close()Contexte de requête
Le contexte de requête lie request, session et url_for à un thread. Utilisez test_request_context dans les tests et scripts pour simuler une requête sans serveur HTTP.
from flask import request
# Flask pushes a request context automatically during dispatch.
# Push one manually to use request/url_for outside a view:
with app.test_request_context("/?q=flask"):
print(request.args.get("q")) # flask
print(request.path) # /
# request_context for real WSGI environments
from werkzeug.test import EnvironBuilder
env = EnvironBuilder("/post/1").get_environ()
with app.request_context(env):
print(request.path)Proxys current_app et request
current_app, request, session et g sont des LocalProxy qui transfèrent l'accès aux attributs vers le contexte actif. Ne les capturez jamais dans une variable globale — accédez-y toujours au moment de l'appel.
from flask import current_app, request, session, g
# These are LocalProxy objects, not the real thing.
# They resolve to the current context's object at access time.
@app.route("/")
def index():
current_app.logger.info("hit /")
g.request_start = time.time()
session["visited"] = True
return current_app.config["APP_NAME"]
# Avoid storing proxies in module-level variables;
# always access them inside a context.Objet session
session est un dict basé sur un cookie signé. Réglez app.secret_key pour que Flask puisse le signer. Les valeurs sont stockées côté client et lisibles par l'utilisateur (mais non falsifiables), donc n'y stockez jamais de secrets.
from flask import session
@app.route("/login")
def login():
session["user_id"] = 42
session["role"] = "admin"
return "logged in"
@app.route("/who")
def who():
uid = session.get("user_id")
return f"user {uid}" if uid else "anonymous"
@app.route("/logout")
def logout():
session.clear()
return "logged out"Cycle de vie du contexte
Comprendre le cycle de vie est la clé pour bien utiliser les hooks. Les handlers teardown_* s'exécutent toujours, même en cas d'erreur, c'est donc le bon endroit pour fermer les connexions de base et libérer les ressources.
# Per-request lifecycle:
# 1. Application context pushed
# 2. Request context pushed
# 3. before_request handlers run
# 4. View function runs
# 5. after_request handlers run (can modify response)
# 6. Request context popped
# 7. teardown_request handlers run
# 8. teardown_appcontext handlers run (close resources)
@app.before_request
def before():
g.start = time.time()
@app.teardown_request
def teardown(exc):
elapsed = time.time() - getattr(g, "start", time.time())
app.logger.debug("request took %.3fs", elapsed)Intégration SQLAlchemy
Configurer Flask-SQLAlchemy
Flask-SQLAlchemy enveloppe SQLAlchemy et l'intègre au contexte d'app de Flask. Réglez SQLALCHEMY_DATABASE_URI sur la chaîne de connexion et désactivez le suivi des modifications pour économiser la mémoire.
pip install flask-sqlalchemy
from flask import Flask
from flask_sqlalchemy import SQLAlchemy
app = Flask(__name__)
app.config["SQLALCHEMY_DATABASE_URI"] = "sqlite:///app.db"
app.config["SQLALCHEMY_TRACK_MODIFICATIONS"] = False
db = SQLAlchemy(app)
# In a factory, init with db.init_app(app)Définir des modèles
Les modèles héritent de db.Model ; les colonnes sont des instances de db.Column. Types courants : Integer, String, Text, DateTime, Boolean. Utilisez unique=True et nullable=False pour les contraintes.
from datetime import datetime
class User(db.Model):
id = db.Column(db.Integer, primary_key=True)
username = db.Column(db.String(80), unique=True, nullable=False)
email = db.Column(db.String(120), unique=True)
created_at = db.Column(db.DateTime, default=datetime.utcnow)
def __repr__(self):
return f"<User {self.username}>"
class Post(db.Model):
id = db.Column(db.Integer, primary_key=True)
title = db.Column(db.String(200), nullable=False)
body = db.Column(db.Text)
user_id = db.Column(db.Integer, db.ForeignKey("user.id"))Requêter les données
Model.query est une interface de requête de commodité. filter_by(keyword=value) est simple ; filter(expression) gère les opérateurs comme >, <, like, in_. paginate() renvoie les items plus les métadonnées de page.
# Fetch all
users = User.query.all()
# Primary key lookup
user = User.query.get(1)
# Filter
admins = User.query.filter_by(role="admin").all()
active = User.query.filter(User.email.isnot(None)).first()
# Order, limit, paginate
recent = User.query.order_by(User.created_at.desc()).limit(10).all()
page = User.query.paginate(page=2, per_page=20)
# Count
total = User.query.count()Ajouter et mettre à jour
Tous les changements passent par une transaction via db.session. add met en attente un nouvel objet ; commit l'écrit. En cas d'erreur, faites db.session.rollback() pour garder la session utilisable.
# Create
u = User(username="alice", email="[email protected]")
db.session.add(u)
db.session.commit()
# Update
u.email = "[email protected]"
db.session.commit()
# Delete
db.session.delete(u)
db.session.commit()
# Bulk insert
db.session.add_all([User(username="b"), User(username="c")])
db.session.commit()Relations
db.relationship définit le lien entre modèles. backref ajoute un attribut inverse. lazy='dynamic' renvoie un objet query au lieu d'une liste, utile pour les grandes collections que vous voulez filtrer davantage.
class User(db.Model):
id = db.Column(db.Integer, primary_key=True)
username = db.Column(db.String(80))
posts = db.relationship("Post", backref="author", lazy="dynamic")
class Post(db.Model):
id = db.Column(db.Integer, primary_key=True)
title = db.Column(db.String(200))
user_id = db.Column(db.Integer, db.ForeignKey("user.id"))
# Usage
user = User.query.get(1)
user.posts.all() # list of posts
post = Post.query.get(5)
post.author.username # backref to userMigrations avec Flask-Migrate
Flask-Migrate enveloppe Alembic pour versionner votre schéma. Lancez migrate pour générer automatiquement un script depuis les changements de modèles, puis upgrade pour l'appliquer. Relisez toujours les scripts générés avant de les commiter.
pip install flask-migrate
from flask_migrate import Migrate
migrate = Migrate(app, db)
# CLI commands
# flask db init # create migrations folder
# flask db migrate -m "create users"
# flask db upgrade # apply migrations
# flask db downgrade # revert one step
# flask db current # show current revisionWTForms (Flask-WTF)
Installer Flask-WTF
Flask-WTF intègre WTForms à Flask et ajoute automatiquement la protection CSRF. Une SECRET_KEY est requise pour signer le token CSRF. Désactivez le CSRF uniquement pour les endpoints d'API publics.
pip install flask-wtf
from flask import Flask
from flask_wtf import FlaskForm
app = Flask(__name__)
app.config["SECRET_KEY"] = "change-me-in-production"
app.config["WTF_CSRF_ENABLED"] = True
# CSRF protection is enabled by default
# when SECRET_KEY is set.Définir un formulaire
Les formulaires héritent de FlaskForm. Chaque champ prend un label et une liste de validateurs exécutés à validate(). Les validateurs imposent entrée requise, longueur, format email, etc.
from flask_wtf import FlaskForm
from wtforms import StringField, PasswordField, SubmitField
from wtforms.validators import DataRequired, Email, Length
class LoginForm(FlaskForm):
email = StringField("Email", validators=[DataRequired(), Email()])
password = PasswordField("Password", validators=[DataRequired(), Length(min=8)])
submit = SubmitField("Log In")
class RegisterForm(FlaskForm):
username = StringField("Username", validators=[DataRequired(), Length(min=3, max=20)])
email = StringField("Email", validators=[DataRequired(), Email()])
submit = SubmitField("Sign Up")Rendre le formulaire dans un template
form.hidden_tag() rend le token CSRF et les champs cachés. Chaque champ peut rendre son label, son input et ses erreurs séparément. Pour une sortie rapide, {{ form.field() }} rend l'input HTML.
{# templates/login.html #}
<form method="POST">
{{ form.hidden_tag() }} {# CSRF token #}
<p>
{{ form.email.label }}
{{ form.email() }}
{% for err in form.email.errors %}<span class="err">{{ err }}</span>{% endfor %}
</p>
<p>
{{ form.password.label }}
{{ form.password() }}
</p>
{{ form.submit() }}
</form>Valider le formulaire
validate_on_submit() renvoie True uniquement pour une requête POST où tous les validateurs passent. En cas de succès, lisez les valeurs dans form.field.data. En cas d'échec, re-rendez le template pour montrer les erreurs.
from flask import render_template, redirect, url_for, flash
@app.route("/login", methods=["GET", "POST"])
def login():
form = LoginForm()
if form.validate_on_submit(): # POST + valid
email = form.email.data
flash(f"Logged in as {email}")
return redirect(url_for("dashboard"))
return render_template("login.html", form=form)
# validate_on_submit() returns False on GET or invalid POSTValidateurs intégrés
Les validateurs sont des callables qui lèvent ValidationError en cas d'échec. EqualTo est courant pour la confirmation de mot de passe. Chaînez-les dans une liste ; ils s'exécutent dans l'ordre jusqu'au premier échec.
from wtforms.validators import (
DataRequired, # field not empty
Email, # valid email format
Length, # Length(min=3, max=20)
NumberRange, # NumberRange(min=0, max=100)
URL, # valid URL
Regexp, # Regexp(r"^\\w+$")
EqualTo, # EqualTo("password") - match another field
Optional, # skip validation if empty
InputRequired, # field submitted (even if empty string)
NoneOf, # NoneOf(["admin", "root"])
)
password = PasswordField("Password", validators=[DataRequired(), Length(min=8)])
confirm = PasswordField("Confirm", validators=[EqualTo("password")])FileField
Utilisez FileField de flask_wtf.file avec FileRequired et FileAllowed pour valider les uploads. Le fichier envoyé est un objet FileStorage disponible à form.field.data. La balise form doit inclure enctype=multipart/form-data.
from flask_wtf import FlaskForm
from flask_wtf.file import FileField, FileRequired, FileAllowed
class UploadForm(FlaskForm):
image = FileField("Image", validators=[
FileRequired(),
FileAllowed(["jpg", "png", "gif"], "Images only!"),
])
submit = SubmitField("Upload")
@app.route("/upload", methods=["GET", "POST"])
def upload():
form = UploadForm()
if form.validate_on_submit():
f = form.image.data
f.save("uploads/" + f.filename)
return "uploaded"
return render_template("upload.html", form=form)Authentification Flask-Login
Configurer Flask-Login
Flask-Login gère les sessions utilisateur : connexion, déconnexion et mémorisation des utilisateurs. Réglez login_view pour que les utilisateurs non authentifiés y soient redirigés. login_message s'affiche en flash à cette redirection.
pip install flask-login
from flask import Flask
from flask_login import LoginManager
app = Flask(__name__)
app.config["SECRET_KEY"] = "secret"
login_manager = LoginManager()
login_manager.init_app(app)
login_manager.login_view = "login"
login_manager.login_message = "Please log in to access this page."Modèle utilisateur
Le modèle utilisateur doit mixer UserMixin (qui fournit is_authenticated, is_active, get_id, etc.) et implémenter un callback user_loader qui renvoie un utilisateur par ID. Ne stockez jamais les mots de passe en clair — hachez-les.
from flask_login import UserMixin
from werkzeug.security import generate_password_hash, check_password_hash
class User(UserMixin, db.Model):
id = db.Column(db.Integer, primary_key=True)
username = db.Column(db.String(80), unique=True)
password_hash = db.Column(db.String(256))
def set_password(self, pw):
self.password_hash = generate_password_hash(pw)
def check_password(self, pw):
return check_password_hash(self.password_hash, pw)
@login_manager.user_loader
def load_user(user_id):
return User.query.get(int(user_id))Vue de connexion
login_user charge l'utilisateur dans la session. Passez remember=True pour des cookies persistants. Vérifiez toujours le mot de passe par un contrôle de hachage avant de connecter, et affichez une erreur générique en cas d'échec.
from flask import render_template, redirect, url_for, flash
from flask_login import login_user
from forms import LoginForm
@app.route("/login", methods=["GET", "POST"])
def login():
form = LoginForm()
if form.validate_on_submit():
user = User.query.filter_by(username=form.username.data).first()
if user and user.check_password(form.password.data):
login_user(user, remember=form.remember.data)
return redirect(url_for("dashboard"))
flash("Invalid username or password")
return render_template("login.html", form=form)Protéger les routes
Le décorateur @login_required rejette les utilisateurs anonymes et les redirige vers login_view. current_user est un proxy vers l'utilisateur connecté (ou un AnonymousUserMixin) disponible dans les vues et templates.
from flask_login import login_required, current_user
@app.route("/dashboard")
@login_required
def dashboard():
return f"Welcome {current_user.username}"
@app.route("/settings")
@login_required
def settings():
return render_template("settings.html", user=current_user)
# Unauthenticated users redirect to login_view
# @login_required must be the innermost decoratorDéconnexion
logout_user retire l'utilisateur de la session. Protégez la route avec @login_required pour que seuls les utilisateurs connectés puissent se déconnecter. Redirigez ensuite vers une page publique (index ou login).
from flask_login import logout_user, login_required
from flask import redirect, url_for, flash
@app.route("/logout")
@login_required
def logout():
logout_user()
flash("You have been logged out.")
return redirect(url_for("index"))
# logout_user() clears the session and cookiesRemember me et current_user
remember=True définit un cookie séparé pour que les utilisateurs restent connectés après fermeture du navigateur. current_user fonctionne dans les vues comme dans les templates, facilitant le rendu conditionnel de l'UI selon le statut d'authentification.
from flask_login import current_user
# In the login view
login_user(user, remember=True)
# remember=True stores a separate long-lived cookie
# so the session survives a browser restart.
# current_user is available everywhere a context exists
@app.route("/")
def index():
if current_user.is_authenticated:
return f"Hi {current_user.username}"
return "Welcome, guest"
# In templates:
# {% if current_user.is_authenticated %}
# <a href="{{ url_for('logout') }}">Logout</a>
# {% endif %}Gestion des erreurs
abort()
abort() arrête immédiatement la vue et renvoie une erreur HTTP. Passez un code de statut et un message optionnel. Il lève une HTTPException que Flask convertit en réponse d'erreur correspondante.
from flask import abort
@app.route("/user/<int:id>")
def get_user(id):
user = find_user(id)
if user is None:
abort(404) # Not Found
if not can_access(user):
abort(403, "Forbidden") # Forbidden with description
return render_template("user.html", user=user)
# Common codes: 400 Bad Request, 401 Unauthorized,
# 403 Forbidden, 404 Not Found, 418 Teapot, 500 Server ErrorPages d'erreur personnalisées
Enregistrez des handlers avec @app.errorhandler(code). Renvoyez un tuple (template, status_code). Ces handlers attrapent à la fois les abort() et les exceptions qui correspondent à ce statut.
from flask import render_template
@app.errorhandler(404)
def not_found(e):
return render_template("errors/404.html"), 404
@app.errorhandler(403)
def forbidden(e):
return render_template("errors/403.html"), 403
@app.errorhandler(500)
def server_error(e):
return render_template("errors/500.html"), 500Handlers d'erreurs pour exceptions
Vous pouvez enregistrer des handlers pour des classes d'exceptions personnalisées, pas seulement des codes HTTP. Lever l'exception n'importe où dans une vue déclenche le handler, centralisant les réponses d'erreur du domaine.
from werkzeug.exceptions import HTTPException
class InvalidUsage(Exception):
status_code = 400
def __init__(self, message, status_code=None, payload=None):
super().__init__()
self.message = message
if status_code is not None:
self.status_code = status_code
self.payload = payload
@app.errorhandler(InvalidUsage)
def handle_invalid_usage(e):
return {"error": e.message}, e.status_code
@app.route("/raise")
def raise_err():
raise InvalidUsage("Bad input", status_code=422)Handler fourre-tout 404
Un handler générique d'Exception est un dernier recours pour les 500. Re-levez les HTTPException pour que les pages intégrées fonctionnent toujours, et journalisez la pile. Attention à ne pas fuiter les piles d'erreurs aux utilisateurs en production.
@app.errorhandler(404)
def page_not_found(e):
# Log the missing URL for analysis
app.logger.info("404: %s", request.path)
return render_template("errors/404.html", path=request.path), 404
@app.errorhandler(Exception)
def unhandled(e):
# Catch any uncaught exception -> 500
if isinstance(e, HTTPException):
return e
app.logger.exception("Unhandled error")
return render_template("errors/500.html"), 500Journaliser les erreurs
Journalisez les erreurs avec exc_info=True pour capturer la pile complète. Un RotatingFileHandler empêche les fichiers de log de croître sans limite. En production, envoyez les logs vers un service centralisé.
import logging
from logging.handlers import RotatingFileHandler
handler = RotatingFileHandler("app.log", maxBytes=10*1024*1024, backupCount=5)
handler.setLevel(logging.ERROR)
handler.setFormatter(logging.Formatter(
"%(asctime)s %(levelname)s: %(message)s [in %(pathname)s:%(lineno)d]"
))
app.logger.addHandler(handler)
@app.errorhandler(500)
def server_error(e):
app.logger.error("Server error: %s", e, exc_info=True)
return "Internal error", 500Gestion des exceptions HTTP
HTTPException est la classe de base de toutes les erreurs HTTP de Werkzeug. Un handler pour HTTPException les attrape toutes d'un coup, tandis qu'un handler spécifique à une sous-classe (NotFound) prend le dessus pour ce code.
from werkzeug.exceptions import HTTPException, NotFound, BadRequest
@app.errorhandler(HTTPException)
def handle_http_exception(e):
# All HTTP exceptions in one handler
return render_template(
"errors/generic.html",
code=e.code,
name=e.name,
description=e.description,
), e.code
# Specific subclasses still work
@app.errorhandler(NotFound)
def specific_404(e):
return "custom 404", 404JSON et API
jsonify
jsonify convertit les dicts/listes Python en réponse JSON avec le bon Content-Type et un échappement compatible ASCII. Depuis Flask 2.1+, vous pouvez passer une liste directement ; les anciennes versions exigent un dict.
from flask import jsonify
@app.route("/api/user")
def api_user():
return jsonify(username="alice", age=30)
@app.route("/api/users")
def api_users():
users = [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]
return jsonify(users)
# jsonify sets Content-Type: application/json
# and dumps with proper escapingRenvoyer du JSON
Renvoyer un dict ou une liste directement est la façon la plus simple d'envoyer du JSON. Pour des codes de statut ou en-têtes personnalisés, renvoyez un tuple. Utilisez Response + json.dumps seulement si vous avez besoin d'un contrôle total de la sérialisation.
# Returning a dict/list is auto-converted to JSON (Flask 1.1+)
@app.route("/api/quick")
def quick():
return {"status": "ok", "count": 42}
# With custom status and headers
@app.route("/api/created", methods=["POST"])
def created():
return {"id": 99}, 201, {"Location": "/api/99"}
# A Response with JSON body
from flask import Response
import json
@app.route("/api/raw")
def raw():
return Response(json.dumps({"k": "v"}), mimetype="application/json")Recevoir du JSON
get_json() parse le corps en JSON quand le Content-Type est application/json. Validez toujours la structure parsée avant de l'utiliser — ne faites jamais confiance aux entrées du client. Renvoyez 400/422 pour des charges malformées.
from flask import request, jsonify
@app.route("/api/echo", methods=["POST"])
def echo():
data = request.get_json()
if not data:
return jsonify({"error": "Invalid JSON"}), 400
return jsonify({"received": data})
# Validate the structure
@app.route("/api/signup", methods=["POST"])
def signup():
data = request.get_json()
if not data or "email" not in data:
return jsonify({"error": "email required"}), 422
return jsonify({"email": data["email"]}), 201Blueprint d'API
Regroupez les routes d'API dans un blueprint avec un url_prefix versionné (/api/v1). Cela sépare la logique d'API des routes de pages et rend le versionnage explicite — passez à /api/v2 quand arrivent les changements cassants.
from flask import Blueprint, jsonify, request
api = Blueprint("api", __name__, url_prefix="/api/v1")
@api.route("/health")
def health():
return jsonify(status="ok")
@api.route("/items", methods=["GET", "POST"])
def items():
if request.method == "POST":
return jsonify(created=True), 201
return jsonify(items=[])
# Register: app.register_blueprint(api)CORS
flask-cors ajoute l'en-tête Access-Control-Allow-Origin pour que les navigateurs autorisent les requêtes cross-origin. Restreignez les origines aux domaines de confiance en production plutôt que d'utiliser le joker '*'.
pip install flask-cors
from flask import Flask
from flask_cors import CORS
app = Flask(__name__)
# Enable for all routes
CORS(app)
# Or restrict to specific origins
CORS(app, resources={r"/api/*": {"origins": ["https://example.com", "http://localhost:3000"]}})
# Per-route
@app.route("/api/public")
@cross_origin(origins="*")
def public():
return {"data": "open"}Réponses d'erreur d'API
Une fonction helper garde les réponses d'erreur uniformes entre endpoints — même forme, mêmes noms de clés. Des corps d'erreur cohérents facilitent énormément la gestion des erreurs côté client. Incluez les détails qui aident à déboguer sans fuiter de secrets.
from flask import jsonify, abort
def api_error(message, status=400, **extra):
body = {"error": message}
body.update(extra)
return jsonify(body), status
@app.route("/api/users/<int:id>")
def get_user(id):
user = find_user(id)
if not user:
return api_error("User not found", 404, user_id=id)
return jsonify(user.serialize())
# Consistent error shape across the API:
# {"error": "User not found", "user_id": 1}Upload de fichiers
Upload de base
La balise form exige enctype=multipart/form-data pour l'upload de fichiers. Réglez MAX_CONTENT_LENGTH pour rejeter les uploads trop gros avec un 413 avant lecture complète du corps — cela protège le serveur.
from flask import request
import os
app.config["UPLOAD_FOLDER"] = "uploads"
app.config["MAX_CONTENT_LENGTH"] = 16 * 1024 * 1024 # 16 MB
@app.route("/upload", methods=["POST"])
def upload():
file = request.files["file"]
file.save(os.path.join(app.config["UPLOAD_FOLDER"], file.filename))
return "uploaded"
# HTML form must include enctype:
# <form method="POST" enctype="multipart/form-data">
# <input type="file" name="file">
# <button>Upload</button>
# </form>Nom de fichier sécurisé
secure_filename retire la traversée de répertoires et les caractères dangereux des noms de fichiers fournis par les utilisateurs. Il ne garantit pas l'unicité — ajoutez un UUID ou vérifiez les collisions si l'écrasement est un risque.
from werkzeug.utils import secure_filename
import os
@app.route("/upload", methods=["POST"])
def upload():
f = request.files.get("file")
if not f:
return "no file", 400
safe = secure_filename(f.filename) # "my file!!/x.txt" -> "my_file__x.txt"
if not safe:
return "invalid filename", 400
f.save(os.path.join("uploads", safe))
return f"saved as {safe}"Plusieurs fichiers
Utilisez request.files.getlist('files') avec un input portant l'attribut multiple pour accepter plusieurs fichiers d'un coup. Validez l'extension et la taille de chaque fichier avant enregistrement.
from flask import request
@app.route("/upload-many", methods=["POST"])
def upload_many():
files = request.files.getlist("files")
saved = []
for f in files:
if f and f.filename:
name = secure_filename(f.filename)
f.save(os.path.join("uploads", name))
saved.append(name)
return {"saved": saved}
# <form method="POST" enctype="multipart/form-data">
# <input type="file" name="files" multiple>
# </form>Upload avec WTForms
Le FileField de Flask-WTF valide l'extension et la présence de l'upload. La balise form doit inclure enctype=multipart/form-data. Le fichier envoyé est accessible à form.photo.data.
from flask_wtf import FlaskForm
from flask_wtf.file import FileField, FileRequired, FileAllowed
class PhotoForm(FlaskForm):
photo = FileField("Photo", validators=[
FileRequired(),
FileAllowed(["jpg", "jpeg", "png"], "Images only"),
])
submit = SubmitField("Upload")
@app.route("/photo", methods=["GET", "POST"])
def photo():
form = PhotoForm()
if form.validate_on_submit():
f = form.photo.data
f.save(os.path.join("uploads", secure_filename(f.filename)))
return "uploaded"
return render_template("photo.html", form=form)Valider le type et la taille du fichier
Validez à la fois l'extension et la longueur du contenu avant enregistrement. MAX_CONTENT_LENGTH rejette tôt les requêtes énormes, mais les vérifications par fichier offrent un contrôle plus fin. Pour plus de sûreté, inspectez les magic bytes du fichier, pas seulement l'extension.
import os
from flask import request
ALLOWED = {".png", ".jpg", ".jpeg", ".gif", ".pdf"}
MAX_SIZE = 5 * 1024 * 1024 # 5 MB
@app.route("/upload", methods=["POST"])
def upload():
f = request.files.get("file")
if not f or not f.filename:
return "no file", 400
ext = os.path.splitext(f.filename)[1].lower()
if ext not in ALLOWED:
return "file type not allowed", 415
f.stream.seek(0, 2) # seek to end
size = f.stream.tell()
f.stream.seek(0)
if size > MAX_SIZE:
return "file too large", 413
f.save(os.path.join("uploads", secure_filename(f.filename)))
return "ok"Hooks avant/après requête
before_request
Les handlers before_request s'exécutent avant chaque vue. Utilisez-les pour les vérifications d'auth, le mode maintenance ou le chargement d'état partagé sur g. Renvoyer une valeur saute la vue et utilise cette réponse directement.
from flask import g, request
@app.before_request
def check_maintenance():
if app.config.get("MAINTENANCE"):
return "Site under maintenance", 503
@app.before_request
def load_user():
token = request.headers.get("Authorization")
if token:
g.user = verify_token(token)
# Return a value to short-circuit the requestafter_request
Les handlers after_request s'exécutent après la vue, recevant et renvoyant la réponse. Ils sont parfaits pour ajouter des en-têtes, logger ou mettre en cache. Si une exception non gérée survient, after_request est sauté.
@app.after_request
def add_security_headers(resp):
resp.headers["X-Content-Type-Options"] = "nosniff"
resp.headers["X-Frame-Options"] = "SAMEORIGIN"
return resp
@app.after_request
def log_response(resp):
app.logger.info("%s %s -> %s", request.method, request.path, resp.status_code)
return resp
# Must take and return a Response objectteardown_request
teardown_request s'exécute à la fin de chaque requête, même en cas d'erreur — contrairement à after_request. Il reçoit l'exception (ou None) et est le bon endroit pour libérer les ressources comme les connexions DB ou les handles de fichiers.
import sqlite3
from flask import g
def get_db():
if "db" not in g:
g.db = sqlite3.connect("app.db")
return g.db
@app.teardown_request
def close_db(exc):
db = g.pop("db", None)
if db is not None:
db.close()
# teardown_request always runs, even if the view raisedbefore_first_request (déprécié)
before_first_request a été retiré dans Flask 2.3 car il casse avec les serveurs asynchrones modernes et les configurations multi-processus. Effectuez la configuration ponctuelle dans un contexte d'app à l'import ou dans une commande CLI.
# Flask 2.3+ removed before_first_request.
# Old code:
# @app.before_first_request
# def init():
# warm_cache()
# Modern alternative: use the app context at startup
with app.app_context():
warm_cache()
# Or a CLI command run once during deployment
@app.cli.command("init")
def init_cmd():
warm_cache()Modifier la réponse
Plusieurs handlers after_request s'enchaînent en ordre inverse d'enregistrement. Chacun doit renvoyer une réponse. Ils sont utiles pour les en-têtes de sécurité, les directives de cache et les IDs de traçage.
@app.after_request
def no_cache(resp):
resp.headers["Cache-Control"] = "no-store"
resp.headers["Pragma"] = "no-cache"
return resp
@app.after_request
def add_request_id(resp):
rid = getattr(g, "request_id", "n/a")
resp.headers["X-Request-ID"] = rid
return resp
# Multiple after_request handlers run in reverse
# registration order; each receives the previous one's output.Pattern de connexion à la base
Un pattern courant : ouvrir une connexion à la demande dans get_db (stockée sur g) et la fermer dans teardown_appcontext. Chaque requête a sa propre connexion et le nettoyage est garanti même en cas d'erreur.
import sqlite3
from flask import g, current_app
def get_db():
if "db" not in g:
g.db = sqlite3.connect(
current_app.config["DATABASE"],
detect_types=sqlite3.PARSE_DECLTYPES,
)
g.db.row_factory = sqlite3.Row
return g.db
@app.teardown_appcontext
def close_db(exc):
db = g.pop("db", None)
if db is not None:
db.close()
@app.route("/users")
def users():
db = get_db()
rows = db.execute("SELECT * FROM users").fetchall()
return {"users": [dict(r) for r in rows]}Commandes CLI
Commandes personnalisées
Utilisez @app.cli.command pour enregistrer une commande CLI, décorée d'arguments et d'options click. La docstring devient le texte d'aide. Lancez flask --help pour lister toutes les commandes disponibles.
import click
from flask import Flask
app = Flask(__name__)
@app.cli.command("create-user")
@click.argument("name")
@click.option("--admin", is_flag=True, default=False)
def create_user(name, admin):
"""Create a new user."""
role = "admin" if admin else "user"
click.echo(f"Created {name} as {role}")
# Run: flask create-user alice --adminflask run
flask run démarre le serveur de dev Werkzeug. --debug active le reloader et le débogueur interactif. --app permet de pointer vers un module ou une factory. N'utilisez jamais ce serveur en production — il est monothread et peu sûr.
# Basic
flask run
# Custom host/port
flask run --host=0.0.0.0 --port=8000
# Enable reloader and debugger
flask run --debug
# Specify the app explicitly
flask --app myapp run
flask --app myapp:create_app run
# With SSL (development)
flask run --cert=cert.pem --key=key.pemContexte du shell
shell_context_processor injecte des noms dans le flask shell pour expérimenter sans imports. Inestimable pour déboguer les modèles et lancer des requêtes ad-hoc sur votre app.
from flask import Flask
from models import db, User
app = Flask(__name__)
@app.shell_context_processor
def make_shell_context():
return {"db": db, "User": User, "app": app}
# flask shell
# >>> User.query.all()
# >>> db.session.add(User(username="x"))Factory d'application avec CLI
Avec le pattern factory, enregistrez les commandes CLI dans create_app pour qu'elles accèdent à l'app configurée. L'option --app de Flask détecte la factory et l'invoque pour vous.
# myapp/__init__.py
from flask import Flask
def create_app():
app = Flask(__name__)
app.config.from_object("config.Config")
@app.cli.command("init-db")
def init_db():
"""Initialize the database."""
click.echo("Initialized")
return app
# Run: flask --app myapp init-db
# The factory is detected automatically.Groupes CLI
Regroupez les commandes liées sous un parent avec @app.cli.group. Les sous-commandes s'enregistrent sur le groupe, gardant la CLI organisée : flask db init, flask db migrate, etc.
import click
from flask import Flask
app = Flask(__name__)
@app.cli.group("db")
def db_group():
"""Database commands."""
pass
@db_group.command("init")
def db_init():
click.echo("DB initialized")
@db_group.command("drop")
def db_drop():
click.echo("DB dropped")
# flask db init
# flask db dropVariables d'environnement
FLASK_APP et FLASK_DEBUG configurent la CLI. Utilisez .flaskenv pour les réglages de dev partagés et .env pour les secrets (tous deux auto-chargés si python-dotenv est installé). Gardez les secrets hors de .flaskenv car il est typiquement commité.
# Flask reads these env vars:
# FLASK_APP -> module/app to run (app.py, myapp, myapp:create_app)
# FLASK_DEBUG -> 1/0 to toggle debug mode
# FLASK_ENV -> development/production (deprecated, use FLASK_DEBUG)
# FLASK_RUN_PORT -> default port
# FLASK_RUN_HOST -> default host
# .env or .flaskenv files are auto-loaded by python-dotenv
# .flaskenv (committed): FLASK_APP=app.py
# .env (gitignored): SECRET_KEY=..., DATABASE_URL=...
# Prefer app.config.from_envvar or from_object for app secrets.Tests
Bases du client de test
test_client() renvoie un client qui fait des requêtes sans réseau. Mettez TESTING=True pour de meilleurs messages d'erreur et désactiver la capture d'erreurs. Utilisez une fixture pour que chaque test ait une app fraîche.
import pytest
from myapp import create_app
@pytest.fixture()
def client():
app = create_app()
app.config["TESTING"] = True
with app.test_client() as client:
with app.app_context():
pass # init DB here
yield client
def test_home(client):
resp = client.get("/")
assert resp.status_code == 200
assert b"Hello" in resp.dataFaire des requêtes dans les tests
Le client de test imite un navigateur : get/post/put/delete avec data (formulaire), json, query_string et headers. Utilisez resp.get_json() pour parser une réponse JSON et resp.headers pour les inspecter.
def test_get(client):
resp = client.get("/users/1")
assert resp.status_code == 200
def test_post_form(client):
resp = client.post("/login", data={"username": "a", "password": "b"})
assert resp.status_code == 302 # redirect
def test_post_json(client):
resp = client.post("/api/echo", json={"key": "value"})
assert resp.get_json() == {"received": {"key": "value"}}
def test_query(client):
resp = client.get("/search?q=flask&page=2")
assert resp.status_code == 200
def test_headers(client):
resp = client.get("/", headers={"X-Test": "1"})Tester une API JSON
Passez json=... pour envoyer un corps JSON avec le bon Content-Type. Affirmez sur le statut, le corps JSON parsé et des en-têtes comme Location. Tester les chemins de succès et d'erreur garantit une API au comportement cohérent.
def test_create_user(client):
resp = client.post(
"/api/users",
json={"username": "alice", "email": "[email protected]"},
)
assert resp.status_code == 201
body = resp.get_json()
assert body["username"] == "alice"
assert "id" in body
assert resp.headers["Location"].endswith(str(body["id"]))
def test_error(client):
resp = client.post("/api/users", json={})
assert resp.status_code == 422
assert "error" in resp.get_json()Fixtures avec pytest
Les fixtures fournissent une mise en place réutilisable : une base en mémoire, un client de test, un runner CLI. Yield la ressource et nettoyez après. test_cli_runner() invoque les commandes CLI dans les tests et vérifie leur sortie et code de sortie.
import pytest
from myapp import create_app, db
@pytest.fixture()
def app():
app = create_app()
app.config["SQLALCHEMY_DATABASE_URI"] = "sqlite:///:memory:"
with app.app_context():
db.create_all()
yield app
db.drop_all()
@pytest.fixture()
def client(app):
return app.test_client()
@pytest.fixture()
def runner(app):
return app.test_cli_runner()
def test_cli(runner):
result = runner.invoke(args=["create-user", "alice"])
assert result.exit_code == 0Base de test
Utilisez une base SQLite en mémoire pour des tests rapides et isolés. Créez les tables et semez les données dans la fixture, puis supprimez tout ensuite. Chaque test démarre sur une base vierge, évitant la contamination entre tests.
import pytest
from myapp import create_app, db
from myapp.models import User
@pytest.fixture()
def app():
app = create_app()
app.config["TESTING"] = True
app.config["SQLALCHEMY_DATABASE_URI"] = "sqlite:///:memory:"
with app.app_context():
db.create_all()
db.session.add(User(username="alice"))
db.session.commit()
yield app
db.session.remove()
db.drop_all()
def test_user_count(app):
with app.app_context():
assert User.query.count() == 1Mocking
patch remplace les appels externes (HTTP, email, files) par des mocks pour que les tests restent rapides et déterministes. Affirmez que le mock a été appelé avec les arguments attendus. Patchez toujours là où le nom est recherché, pas là où il est défini.
from unittest.mock import patch, MagicMock
import myapp
def test_external_call(client):
with patch("myapp.requests.get") as mock_get:
mock_get.return_value = MagicMock(status_code=200, json=lambda: {"ok": True})
resp = client.get("/proxy")
assert resp.status_code == 200
mock_get.assert_called_once()
def test_email(client):
with patch("myapp.send_email") as mock_send:
client.post("/register", data={"email": "[email protected]"})
mock_send.assert_called_once_with("[email protected]", "Welcome!")Déploiement
Avertissement serveur de production
Le serveur de dev Werkzeug est monothread et peu sûr — ne l'exposez jamais à Internet. Utilisez un serveur WSGI de production (Gunicorn, uWSGI, Waitress) derrière un reverse proxy. Le débogueur de debug est un risque d'exécution de code à distance.
# WARNING: Flask's built-in server is for development only!
# app.run() / flask run -> single-threaded, no security, not scalable
# For production use a WSGI server:
# - Gunicorn (Linux/macOS)
# - uWSGI
# - Waitress (Windows-friendly)
# Behind a reverse proxy (Nginx, Apache, Caddy)
# The dev server also enables the interactive debugger
# when debug=True, which allows arbitrary code execution.
# NEVER deploy with debug=True.Gunicorn
Gunicorn est le serveur WSGI le plus populaire sur Linux/macOS. La formule (2 × CPU + 1) workers est un bon point de départ. Derrière Nginx, liez-vous à 127.0.0.1 et laissez le proxy gérer TLS et les fichiers statiques.
pip install gunicorn
# Basic
gunicorn "app:app"
# With factory
gunicorn "myapp:create_app()"
# Workers and binding
gunicorn -w 4 -b 0.0.0.0:8000 "app:app"
# With timeout and logging
gunicorn -w 4 -b 0.0.0.0:8000 --timeout 120 --access-logfile - "app:app"
# Recommended workers: (2 * CPU) + 1
# Use --preload to share memory, or -k gevent for async.uWSGI
uWSGI est un serveur WSGI performant et très configurable. Le processus maître gère les workers ; vacuum nettoie à la sortie. Associez-le à Nginx via le protocole uwsgi pour le meilleur débit.
pip install uwsgi
# Command line
uwsgi --http 0.0.0.0:8000 --module app:app --processes 4 --threads 2
# INI config (uwsgi.ini)
# [uwsgi]
# module = app:app
# http = 0.0.0.0:8000
# processes = 4
# threads = 2
# master = true
# vacuum = true
# die-on-term = true
# Run: uwsgi uwsgi.iniReverse proxy (Nginx)
Nginx se place devant Gunicorn : il sert directement les fichiers statiques (plus rapide), termine le TLS et transmet les requêtes au serveur WSGI. Les en-têtes X-Forwarded-* permettent à Flask de voir la vraie IP et le schéma du client — réglez ProxyFix pour leur faire confiance.
# /etc/nginx/sites-available/myapp
server {
listen 80;
server_name example.com;
location /static/ {
alias /path/to/app/static/;
expires 30d;
}
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;
}
}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. Passez les secrets via des variables d'environnement (--env-file), ne les cuisez jamais dans l'image.
# Dockerfile
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["gunicorn", "-w", "4", "-b", "0.0.0.0:8000", "app:app"]
# .dockerignore
# __pycache__/
# venv/
# *.pyc
# .env
# Build and run
# docker build -t myapp .
# docker run -p 8000:8000 --env-file .env myappConfiguration par environnement
Superposez la configuration : défauts dans le code, surcharges par environnement, et secrets d'instance depuis les variables d'env. Cela garde les secrets hors gestion de versions et permet à une même base de code de tourner en dev, staging et production.
import os
from flask import Flask
app = Flask(__name__)
app.config.from_object("config.DefaultConfig")
# Override with environment-specific config
env = os.environ.get("FLASK_ENV", "development")
app.config.from_object(f"config.{env.title()}Config")
# Then instance-specific secrets from env vars
app.config["SECRET_KEY"] = os.environ["SECRET_KEY"]
app.config["SQLALCHEMY_DATABASE_URI"] = os.environ["DATABASE_URL"]
# Use python-dotenv for local .env files
from dotenv import load_dotenv
load_dotenv()Configuration
Objet de configuration
Définissez la config comme des classes héritant d'un Config de base. Ne surchargez que ce qui change par environnement. from_object copie les attributs en majuscules sur app.config, les helpers en minuscules sont donc ignorés.
class Config:
DEBUG = False
TESTING = False
SECRET_KEY = "change-me"
SQLALCHEMY_DATABASE_URI = "sqlite:///app.db"
class DevelopmentConfig(Config):
DEBUG = True
SECRET_KEY = "dev-secret"
class ProductionConfig(Config):
DEBUG = False
SECRET_KEY = os.environ["SECRET_KEY"]
class TestingConfig(Config):
TESTING = True
SQLALCHEMY_DATABASE_URI = "sqlite:///:memory:"
app.config.from_object(DevelopmentConfig)Variables d'environnement
Utilisez os.environ pour les secrets afin qu'ils ne vivent jamais dans le code. from_envvar charge un fichier Python pointé par une variable d'env — utile pour des surcharges propres au déploiement. python-dotenv charge un fichier .env pour le développement local.
import os
from flask import Flask
app = Flask(__name__)
# Read individual values
app.config["SECRET_KEY"] = os.environ.get("SECRET_KEY", "dev")
app.config["DATABASE_URL"] = os.environ.get("DATABASE_URL", "sqlite:///app.db")
# Load a whole config file from an env var path
# export MYAPP_SETTINGS=/etc/myapp/prod.py
app.config.from_envvar("MYAPP_SETTINGS", silent=True)
# python-dotenv loads .env automatically if installed
from dotenv import load_dotenv
load_dotenv()Dossier instance
Le dossier instance héberge les fichiers propres au déploiement (secrets, config) hors gestion de versions. Mettez instance_relative_config=True et chargez avec from_pyfile. Cela sépare proprement le code de la configuration d'environnement.
# The instance/ folder sits outside the package, not in VCS.
# Flask searches it automatically for config files.
app = Flask(__name__, instance_relative_config=True)
# Load from instance/config.py
app.config.from_pyfile("config.py", silent=True)
# instance/config.py (deployment-specific, gitignored)
# SECRET_KEY = "real-production-key"
# SQLALCHEMY_DATABASE_URI = "postgresql://user:pass@db/app"
# Access the path
print(app.instance_path) # /abs/path/to/instanceConfig depuis un fichier
from_object importe un module ou un chemin d'objet ; from_pyfile charge un fichier absolu ; from_file (Flask 2.0+) utilise une fonction de chargeur, acceptant JSON, TOML ou YAML. Choisissez un format et restez cohérent.
# config.py
DEBUG = True
SECRET_KEY = "dev"
SQLALCHEMY_DATABASE_URI = "sqlite:///dev.db"
# Load a Python file
app.config.from_object("config")
# Load by path
app.config.from_pyfile("/etc/myapp/config.py")
# Load from a JSON file
app.config.from_file("config.json", load=json.load)
# config.json
# { "DEBUG": true, "SECRET_KEY": "dev" }Développement vs production
Changez de config par variable d'environnement pour que le même code tourne partout. La production doit désactiver debug (le débogueur est une faille) et utiliser une vraie base. Journalisez un avertissement si debug est actif en production.
import os
from flask import Flask
env = os.environ.get("FLASK_ENV", "development")
configs = {
"development": DevelopmentConfig,
"production": ProductionConfig,
"testing": TestingConfig,
}
app = Flask(__name__)
app.config.from_object(configs[env])
# In production, never enable debug:
if app.config["DEBUG"]:
print("WARNING: running in debug mode!")Configuration du logging
Configurez le logging seulement hors mode debug (Flask logue sur stderr par défaut en debug). RotatingFileHandler empêche une croissance illimitée des logs. En production, envisagez un logging JSON structuré pour les services d'agrégation.
import logging
from logging.handlers import RotatingFileHandler
if not app.debug:
handler = RotatingFileHandler("app.log", maxBytes=10*1024*1024, backupCount=5)
handler.setFormatter(logging.Formatter(
"%(asctime)s %(levelname)s: %(message)s [in %(pathname)s:%(lineno)d]"
))
handler.setLevel(logging.INFO)
app.logger.addHandler(handler)
app.logger.setLevel(logging.INFO)
# In a view
@app.route("/")
def index():
app.logger.info("Index page accessed")
return "Hello"
# Flask's logger is a standard logging.LoggerSnippets Flask associés
Copy-paste ready code for common tasks.
Routing
Define routes with methods and dynamic parameters.
Request and Response
Access request data and build custom responses.
Jinja2 Templates
Render templates with context and template inheritance.
Blueprints
Organize an app into modular blueprints.
Session
Store per-user data in signed session cookies.
Error Handling
Register custom error handlers for HTTP exceptions.
Flask-SQLAlchemy
Define models and query them with Flask-SQLAlchemy.
Custom Decorators
Build decorators to gate or augment view functions.
Was this helpful?