Skip to content

Flask Aide-mémoire

Framework web Python léger (microframework).

01

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.

flask
# 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.

flask
# 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.py

Environnement 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.

flask
# 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.txt

Structure 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.

flask
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 handlers

Pattern 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.

flask
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_app

Anatomie 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.

flask
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!"
02

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.

flask
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.

flask
@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 code

URLs 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.

flask
@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 Found

Mé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.

flask
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.

flask
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/bob

Plusieurs 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.

flask
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.
03

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.

flask
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).

flask
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.

flask
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.

flask
@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", 418

Ré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é.

flask
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.

flask
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 resp
04

Objet 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.

flask
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.

flask
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.

flask
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.

flask
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 data

En-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.

flask
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 '?'.

flask
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(),
    }
05

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é.

flask
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.

flask
# 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.

flask
{# 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.

flask
{# 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.

flask
{{ 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.

flask
{# 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>
06

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.

flask
# 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.

flask
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.js

Dossier 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.

flask
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.css

Favicon

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é.

flask
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.

flask
# 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 }}">
07

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.

flask
# 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.

flask
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.

flask
# 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.

flask
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é.

flask
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"), 403

Blueprints 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.

flask
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/info
08

Contexte (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.

flask
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.

flask
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.

flask
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.

flask
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.

flask
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.

flask
# 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)
09

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.

flask
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.

flask
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.

flask
# 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.

flask
# 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.

flask
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 user

Migrations 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.

flask
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 revision
10

WTForms (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.

flask
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.

flask
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.

flask
{# 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.

flask
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 POST

Validateurs 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.

flask
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.

flask
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)
11

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.

flask
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.

flask
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.

flask
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.

flask
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 decorator

Dé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).

flask
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 cookies

Remember 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.

flask
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 %}
12

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.

flask
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 Error

Pages 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.

flask
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"), 500

Handlers 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.

flask
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.

flask
@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"), 500

Journaliser 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é.

flask
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", 500

Gestion 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.

flask
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", 404
13

JSON 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.

flask
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 escaping

Renvoyer 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.

flask
# 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.

flask
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"]}), 201

Blueprint 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.

flask
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 '*'.

flask
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.

flask
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}
14

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.

flask
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.

flask
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.

flask
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.

flask
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.

flask
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"
15

Cookies et sessions

Définir des cookies

Les cookies se règlent sur l'objet réponse via set_cookie. Mettez httponly=True pour empêcher JavaScript de les lire (défense XSS), secure=True pour HTTPS uniquement, et samesite='Lax' ou 'Strict' pour la défense CSRF.

flask
from flask import make_response

@app.route("/set-cookie")
def set_cookie():
    resp = make_response("cookie set")
    resp.set_cookie("user", "alice", max_age=3600, httponly=True)
    resp.set_cookie("theme", "dark", path="/", secure=True, samesite="Lax")
    return resp

# max_age in seconds; expires sets a datetime
# httponly blocks JS access; secure requires HTTPS
# samesite: "Lax" (default), "Strict", or "None"

Lire les cookies

request.cookies est un ImmutableMultiDict en lecture seule des cookies envoyés par le navigateur. Utilisez .get() avec un défaut plutôt que l'indexation, car un cookie peut ne pas exister. La modification des cookies se fait sur la réponse.

flask
from flask import request

@app.route("/show-cookies")
def show_cookies():
    user = request.cookies.get("user", "guest")
    theme = request.cookies.get("theme", "light")
    all_cookies = request.cookies.to_dict()
    return f"user={user}, theme={theme}"

# request.cookies is a read-only dict
# use .get() with a default to avoid KeyError

Objet session

session est un cookie signé stockant un dict sérialisé. Comme il est signé avec secret_key, les utilisateurs ne peuvent pas le falsifier, mais ils PEUVENT le lire — n'y stockez donc jamais de mots de passe ni de secrets.

flask
from flask import session

app.secret_key = "a-very-secret-string"

@app.route("/login")
def login():
    session["user_id"] = 1
    session["role"] = "admin"
    return "logged in"

@app.route("/dashboard")
def dashboard():
    if "user_id" not in session:
        return "please log in", 401
    return f"user {session['user_id']}"

@app.route("/logout")
def logout():
    session.pop("user_id", None)
    return "logged out"

Clé secrète

secret_key signe les cookies de session et les tokens CSRF. Utilisez une valeur longue et aléatoire, et chargez-la depuis l'environnement pour ne pas la commiter. Toutes les instances de l'app doivent partager la même clé.

flask
import os
from flask import Flask

app = Flask(__name__)

# Generate a strong random key
app.secret_key = os.urandom(32)

# Or load from environment (recommended for production)
app.secret_key = os.environ.get("SECRET_KEY")

# For multiple workers, all must share the same key
# so sessions survive being routed to different processes.
# A key of at least 32 random bytes is recommended.

Messages flash

flash stocke un message dans la session qui survit à une redirection et s'affiche à la requête suivante. Appelez get_flashed_messages dans le template pour les récupérer et les effacer. with_categories permet de styler par type.

flask
from flask import flash, redirect, url_for, render_template

app.secret_key = "secret"   # flash uses the session

@app.route("/save", methods=["POST"])
def save():
    flash("Saved successfully!", "success")
    return redirect(url_for("index"))

# In the template:
# {% with messages = get_flashed_messages(with_categories=true) %}
#   {% for category, message in messages %}
#     <div class="alert alert-{{ category }}">{{ message }}</div>
#   {% endfor %}
# {% endwith %}

Configuration de session

Par défaut, les sessions sont basées sur cookies et expirent à la fermeture du navigateur. Réglez session.permanent=True et PERMANENT_SESSION_LIFETIME pour les étendre. Flask-Session déplace le stockage côté serveur (Redis, système de fichiers) pour des sessions plus grandes ou plus sûres.

flask
app.config.update(
    SECRET_KEY="secret",
    SESSION_COOKIE_NAME="sid",
    SESSION_COOKIE_HTTPONLY=True,
    SESSION_COOKIE_SECURE=True,     # HTTPS only
    SESSION_COOKIE_SAMESITE="Lax",
    PERMANENT_SESSION_LIFETIME=3600,  # seconds
    SESSION_TYPE="redis",            # needs Flask-Session
)

# Mark a session as permanent
from flask import session
from datetime import timedelta

@app.route("/remember")
def remember():
    session.permanent = True
    session["user"] = "alice"
    return "remembered for 1 hour"
16

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.

flask
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 request

after_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é.

flask
@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 object

teardown_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.

flask
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 raised

before_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
# 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.

flask
@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.

flask
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]}
17

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.

flask
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 --admin

flask 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.

flask
# 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.pem

Contexte 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.

flask
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.

flask
# 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.

flask
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 drop

Variables 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
# 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.
18

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.

flask
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.data

Faire 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.

flask
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.

flask
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.

flask
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 == 0

Base 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.

flask
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() == 1

Mocking

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.

flask
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!")
19

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.

flask
# 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.

flask
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.

flask
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.ini

Reverse 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.

flask
# /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.

flask
# 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 myapp

Configuration 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.

flask
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()
20

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.

flask
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.

flask
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.

flask
# 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/instance

Config 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.

flask
# 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.

flask
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.

flask
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.Logger

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.