API de l'objet Application de Flask

La classe Flask est le cœur de l'ensemble du framework. Elle s'exécute comme une application WSGI et gère centralement toutes les fonctionnalités telles que le routage, les templates, la configuration, les hooks, etc.

Méthode de création :

app = Flask(__name__)

Paramètres du constructeur

Voici tous les paramètres qui peuvent être passés lors de la création d'une instance Flask :

Paramètre Type Valeur par défaut Description
import str Requis Nom du module/package de l'application. Flask l'utilise pour localiser les templates et les fichiers statiques. Passé sous forme d'un fichier unique.⟦⟧__name____name__, passez le nom du package
static_url_path str Aucune Le chemin d'URL exposé pour les fichiers statiques. S'il n'est pas défini, utilise le nom du dossier de static_folder, par ex. /static.
static_folder str "static" Le chemin du dossier pour les fichiers statiques (CSS, JS, images), relatif à root_path ou un chemin absolu.
static_host str Aucune Le nom d'hôte pour la route des fichiers statiques. Nécessaire uniquement lorsque host_matching=True.
host_matching bool False Indique si les routes doivent être mises en correspondance selon l'en-tête Host
subdomain_matching bool False Indique s'il faut activer la correspondance des routes de sous-domaine
template_folder str "templates" Le chemin du dossier pour les fichiers de modèle Jinja2.
instance_path str None (découverte automatique) Le chemin du dossier d'instance, utilisé pour stocker les fichiers qui ne sont pas soumis au contrôle de version à l'exécution. Défini sur un chemin absolu
instance_relative_config bool False Lorsque True, les chemins relatifs dans le fichier de configuration sont basés sur instance_path plutôt que sur root_path
root_path str None (découverte automatique) Le chemin racine de l'application, généralement auto-détecté. Ne doit être défini manuellement que pour les applications.

Attributs principaux

Propriété Type Description
name str Le nom de l'application. Si import_name est __main__, le nom du fichier du module principal est utilisé.
config Config Objet dictionnaire de configuration, stockant tous les éléments de configuration
debug bool Indique si le mode débogage est activé. Équivalent à config["DEBUG"].
testing bool Indique si le mode de test est activé. Équivalent à config["TESTING"].
secret_key str Clé secrète utilisée pour la signature de session. Équivalent à config["SECRET_KEY"]
permanent_session_lifetime timedelta Durée de vie des sessions permanentes, par défaut 31 jours.
url_map Map La carte d'URL de Werkzeug, stockant toutes les règles de routage.
view_functions dict Dictionnaire de correspondance des points de terminaison → fonctions de vue.
blueprints dict Mappage nom de blueprint enregistré → instance Blueprint
extensions dict Dictionnaire de stockage des extensions. Les extensions stockent leur propre état par nom de module.
logger Logger logging.Logger standard de Python, avec le nom de l’application comme nom du logger
jinja_env Environnement Instance d’environnement Jinja2, contrôlant la façon dont les templates sont chargés
json JSONProvider Instance de fournisseur de gestionnaire JSON, remplaçable par une bibliothèque JSON personnalisée
aborter Aborter Déclencheur d'exception HTTP, appelé par la fonction abort().
cli AppGroup Groupe de commandes Click pour ajouter des commandes CLI personnalisées.
instance_path str Chemin absolu vers le dossier d'instance.
root_path str Chemin absolu du répertoire racine de l'application

Attributs de classe surchargeables

Les attributs suivants peuvent être redéfinis dans les sous-classes pour personnaliser le comportement du framework :

Propriété Valeur par défaut Description
request_class Demande Classe utilisée pour créer des objets de requête
response_class Response Classe utilisée pour créer des objets de réponse
session_interface SecureCookieSessionInterface() Interface backend de session, remplaçable par des sessions Redis/base de données
jinja_environment Environnement Classe d'environnement Jinja2
app_ctx_globals_class _AppCtxGlobals Classe de l'objet g
config_class Config Classe de l'objet de configuration
aborter_class Aborter Classe du lanceur d'exceptions
json_provider_class DefaultJSONProvider Classe du gestionnaire JSON
url_rule_class Règle Classe pour les règles d'URL (Werkzeug)
url_map_class Map Classe de mappage d'URL (Werkzeug)
test_client_class None (FlaskClient par défaut) Classe de client de test
test_cli_runner_class None (FlaskCliRunner par défaut) Classe d'exécuteur de tests CLI
jinja_options {} Options supplémentaires transmises à l'environnement Jinja2.

Méthode de routage d'URL

Méthodes Signature Description
route (rule, **options) Décorateur qui lie une règle d'URL à une fonction de vue.
get (rule, **options) Décorateur qui lie uniquement la méthode GET (équivalent à methods=["GET"])
post (rule, **options) Décorateur qui ne lie que la méthode POST.
put (rule, **options) Décorateur qui associe uniquement la méthode PUT
effacement (rule, **options) Décorateur qui associe uniquement la méthode DELETE.
patch (rule, **options) Décorateur qui associe uniquement la méthode PATCH.
add_url_rule (rule, endpoint, view_func, provide_automatic_options, **options) Ajoute des règles d'URL par programmation. Le décorateur de route appelle cette méthode sous le capot.
url_for (endpoint, *, _anchor, _method, _scheme, _external, **values) Génère une URL à partir d'un endpoint et de paramètres. Dans les blueprints, l'endpoint doit être préfixé par le nom du blueprint.
register_blueprint (blueprint, **options) Enregistrer un blueprint, avec des paramètres de remplacement tels que url_prefix, subdomain, etc.
iter_blueprints () Itérer sur tous les blueprints dans l'ordre d'enregistrement

Les options prises en charge par le décorateur route incluent :methods(liste des méthodes HTTP),endpoint(nom d'endpoint personnalisé),defaults(paramètres par défaut),subdomain(sous-domaine), etc.


Hooks du cycle de vie des requêtes (décorateurs)

Les méthodes suivantes peuvent toutes être utilisées comme décorateurs pour insérer une logique personnalisée à différentes étapes de la requête :

Méthodes Moment d'exécution Comportement en cas de retour non-None Utilisation typique
before_request Avant la distribution des routes Valeur de retour utilisée comme réponse finale, en ignorant la fonction de vue. Vérifications de connexion, vérification des permissions
after_request Après la construction de la réponse, avant son envoi Doit accepter et renvoyer un objet Response. Ajouter des en-têtes de sécurité, des en-têtes CORS
teardown_request Lorsque le contexte de requête est dépilé La valeur de retour est ignorée Libérer les ressources au niveau de la requête
teardown_appcontext Lorsque le contexte d'application est dépilé La valeur de retour est ignorée Fermer la connexion à la base de données
errorhandler Lorsqu'un code d'état ou une exception spécifiés se produit La valeur de retour est utilisée comme réponse pour la page d'erreur Pages 404/500 personnalisées
url_value_preprocessor Après l'extraction des variables d'URL, avant l'appel de la vue. La valeur de retour est ignorée Prétraiter les paramètres d'URL
url_defaults Lors de la construction d'URL avec url_for Modifie le dictionnaire de valeurs transmis. Ajoute des paramètres par défaut à url_for.
template_filter — (nature de l'enregistrement) — Enregistrer un filtre de template Jinja2
template_test — (nature de l'enregistrement) — Enregistrer un test de template Jinja2
template_global — (nature de l'enregistrement) — Enregistrer une fonction globale Jinja2
shell_context_processor Lorsque flask shell démarre Renvoie un dict qui est fusionné dans le contexte du shell. Pré-importe les objets couramment utilisés dans flask shell.

Méthode de gestion des requêtes

Les méthodes suivantes sont appelées en interne pendant le traitement des requêtes et peuvent être redéfinies dans les sous-classes :

Méthodes Description
preprocess_request(ctx) Prétraitement de la requête : exécute les fonctions before_request et les préprocesseurs d’URL.
dispatch_request(ctx) Répartition principale : fait correspondre l’URL et appelle la fonction de vue correspondante.
make_response(rv) Convertit la valeur de retour de la fonction de vue en un objet Response.
finalize_request(ctx, rv) Finalisation : appelle make_response et les hooks after_request
process_response(ctx, response) Traitement après réponse : exécute les fonctions after_request et la sauvegarde de session
full_dispatch_request(ctx) Point d'entrée de la répartition complète des requêtes : prétraitement → répartition → finalisation
handle_http_exception(ctx, e) Gère les exceptions HTTP, recherche l'errorhandler correspondant
handle_user_exception(ctx, e) Gère les exceptions provenant du code utilisateur, en distinguant les exceptions HTTP des exceptions normales.
handle_exception(ctx, e) Gestion finale des exceptions, renvoie une réponse 500.
ensure_sync(func) Garantit que la fonction s'exécute de manière synchrone. Les fonctions asynchrones sont encapsulées pour être synchrones.
make_default_options_response(ctx) Génère des réponses OPTIONS automatiques.
raise_routing_exception(request) Gère les exceptions de routage (par ex., redirections avec barre oblique finale).

Modèles et fichiers statiques

Méthodes Description
create_jinja_environment() Crée et configure l'environnement Jinja2. Appelé automatiquement lors du premier accès à jinja_env.
create_global_jinja_loader() Crée le chargeur Jinja2 global, prenant en charge la répartition des modèles entre l'application et les blueprints.
select_jinja_autoescape(filename) Détermine si un fichier donné nécessite un échappement automatique. Renvoie True par défaut pour .html/.htm/.xml/.xhtml/.svg
update_template_context(ctx, context) Injecte des variables intégrées telles que request, session, g, config dans le contexte de modèle
send_static_file(filename) Envoie des fichiers depuis static_folder, automatiquement enregistré comme /static/Routage
get_send_file_max_age(filename) Obtient la durée de mise en cache pour les fichiers statiques. La valeur par défaut est la configuration SEND_FILE_MAX_AGE_DEFAULT.
open_resource(resource, mode="rb") Ouvre les fichiers de ressources sous root_path en mode binaire.
open_instance_resource(resource, mode="rb") Ouvre les fichiers de ressources sous instance_path, en prenant en charge le mode écriture.

Gestion du contexte

Méthodes Description
app_context() Crée le contexte d'application, poussé manuellement à l'aide d'une instruction with. Rend current_app et g disponibles.
request_context(environ) Crée le contexte de requête à partir de l'environnement WSGI.
test_request_context(*args, **kwargs) Crée un contexte de requête simulé pour les tests. Accepte path, method, data, json et d'autres paramètres.
wsgi_app(environ, start_response) Méthode principale de l'application WSGI. Peut envelopper un middleware via app.wsgi_app = Middleware(app.wsgi_app)

Outils de test et de développement

Méthodes Description
test_client(use_cookies=True, **kwargs) Crée un client de test pour simuler des requêtes de navigateur. Renvoie une instance FlaskClient
test_cli_runner(**kwargs) Crée un exécuteur de test CLI pour tester des commandes personnalisées. Renvoie une instance FlaskCliRunner
run(host, port, debug, load_dotenv, **options) Démarre le serveur de développement. Utilisez Gunicorn/Waitress en production.
make_shell_context() Construit le dictionnaire de contexte pour le shell flask. Exécute tous les shell_context_processor
log_exception(ctx, exc_info) Journalise les exceptions dans le logger, en passant le tuple exc_info

Méthodes utilitaires

Méthodes Description
redirect(location, code=303) Créer un objet de réponse de redirection
async_to_sync(func) Convertir les fonctions de coroutine asynchrones en fonctions synchrones
create_url_adapter(request) Crée un adaptateur d'URL à partir de la requête ou de la configuration, utilisé pour la construction d'URL.
inject_url_defaults(endpoint, values) Injecte les paramètres par défaut dans le processus de construction d'URL.
handle_url_build_error(error, endpoint, values) Gère les échecs de construction de url_for et peut renvoyer une URL de secours.
make_config(instance_relative) Créez une instance Config, qui peut être surchargée par des sous-classes pour personnaliser la configuration
make_aborter() Créez une instance Aborter
trap_http_exception(e) Détermine s'il faut lever les exceptions HTTP comme des exceptions normales.
auto_find_instance_path() Trouve automatiquement le chemin du dossier d'instance.

Exemples de code

Exemple

from flask import Flask

# Créez l'application, spécifiez les dossiers de modèles et de fichiers statiques
app = Flask(__name__,
           template_folder="templates",
           static_folder="static",
           instance_relative_config=True)

# Définir la clé secrète
app.secret_key = "your-secret-key"

# Enregistrer les routes
@app.route("/")
def index():
    return "<h1>Bonjour, EXAMPLE !</h1>"

# Enregistrer le hook before_request
@app.before_request
def check_auth():
    # Vérifier l'état d'authentification de l'utilisateur ici
    pass

# Enregistrer le hook after_request
@app.after_request
def add_header(response):
    # Ajouter des en-têtes personnalisés à chaque réponse
    response.headers["X-Custom-Header"] = "EXAMPLE"
    return response

# Enregistrer les gestionnaires d'erreurs
@app.errorhandler(404)
def not_found(error):
    return "<h1>Page introuvable</h1>", 404

# Enregistrer une commande CLI personnalisée
@app.cli.command("hello")
def hello_command():
    """Afficher un message d'accueil"""
    print("Bonjour depuis EXAMPLE Flask App !")

Documentation connexe

autres extensions