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/ |
| 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
# 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 !")