Flask-Anwendungsobjekt-API

Die Flask-Klasse ist der Kern des gesamten Frameworks. Sie läuft als WSGI-Anwendung und verwaltet zentral alle Funktionen wie Routing, Vorlagen, Konfiguration, Hooks und mehr.

Erstellungsmethode:

app = Flask(__name__)

Konstruktorparameter

Die folgenden sind alle Parameter, die beim Erstellen einer Flask-Instanz übergeben werden können:

Parameter Type Standardwert Beschreibung
import_name str Erforderlich Anwendungsmodul-/Paketname. Flask verwendet ihn, um Vorlagen und statische Dateien zu finden. Wird als einzelne Datei übergeben.__name__, den Paketnamen übergeben
static_url_path str Keine Der URL-Pfad, der für statische Dateien bereitgestellt wird. Wenn er nicht festgelegt ist, wird der Ordnername von static_folder verwendet, z. B. /static.
static_folder str "static" Der Ordnerpfad für statische Dateien (CSS, JS, Bilder), relativ zu root_path oder ein absoluter Pfad.
static_host str Keine Der Hostname für die Route der statischen Datei. Nur erforderlich, wenn host_matching=True.
host_matching bool False Ob Routen anhand des Host-Headers abgeglichen werden
subdomain_matching bool False Ob der Abgleich von Subdomain-Routen aktiviert werden soll
template_folder str "templates" Der Ordnerpfad für Jinja2-Vorlagendateien.
instance_path str None (automatische Erkennung) Der Pfad des Instanzordners, der verwendet wird, um Dateien zu speichern, die zur Laufzeit nicht in die Versionsverwaltung übernommen werden. Auf einen absoluten Pfad setzen
instance_relative_config bool False Wenn True, basieren relative Pfade in der Konfigurationsdatei auf instance_path statt auf root_path
root_path str None (automatische Erkennung) Der Anwendungs-Stammpfad, normalerweise automatisch erkannt. Nur Namespace-Pakete müssen ihn manuell festlegen.

Kernattribute

Eigenschaft Type Beschreibung
name str Der Anwendungsname. Wenn import_name __main__ ist, wird der Dateiname des Hauptmoduls verwendet.
config Config Konfigurations-Dictionary-Objekt, das alle Konfigurationselemente speichert
debug bool Gibt an, ob der Debug-Modus aktiviert ist. Entspricht config["DEBUG"]
testing bool Gibt an, ob der Testing-Modus aktiviert ist. Entspricht config["TESTING"]
secret_key str Geheimer Schlüssel, der für die Session-Signierung verwendet wird. Entspricht config["SECRET_KEY"]
permanent_session_lifetime timedelta Die Lebensdauer permanenter Sessions, Standard 31 Tage.
url_map Map Die Werkzeug-URL-Map, die alle Routing-Regeln speichert.
view_functions dict Mapping-Dictionary von Endpunkt → View-Funktion.
blueprints dict Zuordnung von registrierten Blueprint-Namen → Blueprint-Instanzen
extensions dict Wörterbuch zur Speicherung von Erweiterungen. Erweiterungen speichern ihren eigenen Zustand unter dem Modulnamen.
logger Logger Python-Standard logging.Logger, wobei der App-Name als Logger-Name verwendet wird
jinja_env Umgebung Jinja2-Umgebungsinstanz, die steuert, wie Templates geladen werden
json JSONProvider JSON-Handler-Provider-Instanz, ersetzbar durch eine benutzerdefinierte JSON-Bibliothek
aborter Aborter HTTP-Ausnahmeauslöser, wird von der Funktion abort() aufgerufen.
cli AppGroup Click-Befehlsgruppe zum Hinzufügen benutzerdefinierter CLI-Befehle.
instance_path str Absoluter Pfad zum Instanzordner.
root_path str Absoluter Pfad des Anwendungsstammverzeichnisses

Überschreibbare Klassenattribute

Die folgenden Attribute können in Unterklassen überschrieben werden, um das Verhalten des Frameworks anzupassen:

Eigenschaft Standardwert Beschreibung
request_class Anfrage Klasse zum Erstellen von Request-Objekten
response_class Response Klasse zum Erstellen von Response-Objekten
session_interface SecureCookieSessionInterface() Session-Backend-Schnittstelle, ersetzbar durch Redis-/Datenbank-Sessions
jinja_environment Umgebung Jinja2-Umgebungsklasse
app_ctx_globals_class _AppCtxGlobals Klasse des g-Objekts
config_class Config Klasse des Konfigurationsobjekts
aborter_class Aborter Klasse des Ausnahmeauslösers
json_provider_class DefaultJSONProvider Klasse des JSON-Handlers
url_rule_class Regel Klasse für URL-Regeln (Werkzeug)
url_map_class Map URL-Map-Klasse (Werkzeug)
test_client_class None (Standard FlaskClient) Testclient-Klasse
test_cli_runner_class None (Standard FlaskCliRunner) CLI-Testrunner-Klasse
jinja_options {} Zusätzliche Optionen, die an die Jinja2-Umgebung übergeben werden.

URL-Routing-Methode

Methoden Signatur Beschreibung
route (rule, **options) Dekorator, der eine URL-Regel an eine View-Funktion bindet.
get (rule, **options) Dekorator, der nur die GET-Methode bindet (entspricht methods=["GET"])
post (rule, **options) Dekorator, der nur die POST-Methode bindet.
put (rule, **options) Dekorator, der nur die PUT-Methode bindet
Löschen (rule, **options) Dekorator, der nur die DELETE-Methode bindet.
patch (rule, **options) Dekorator, der nur die PATCH-Methode bindet.
add_url_rule (rule, endpoint, view_func, provide_automatic_options, **options) Fügt URL-Regeln programmatisch hinzu. Der route-Dekorator ruft diese Methode intern auf.
url_for (endpoint, *, _anchor, _method, _scheme, _external, **values) Erzeugt eine URL aus einem Endpunkt und Parametern. In Blueprints muss der Endpunkt mit dem Blueprint-Namen präfixiert werden.
register_blueprint (blueprint, **options) Registriert ein Blueprint mit Parametern zum Überschreiben wie url_prefix, subdomain usw.
iter_blueprints () Über alle Blueprints in Registrierungsreihenfolge iterieren

Vom route-Dekorator unterstützte Optionen umfassen:methods(HTTP-Methodenliste),endpoint(benutzerdefinierter Endpunktname),defaults(Standardparameter),subdomain(Subdomain), usw.


Request-Lebenszyklus-Hooks (Dekoratoren)

Die folgenden Methoden können alle als Dekoratoren verwendet werden, um benutzerdefinierte Logik an verschiedenen Phasen des Requests einzufügen:

Methoden Ausführungszeitpunkt Verhalten bei Rückgabe von non-None Typische Verwendung
before_request Vor dem Route-Dispatching Rückgabewert wird als endgültige Antwort verwendet, wobei die View-Funktion übersprungen wird. Login-Prüfungen, Berechtigungsüberprüfung
after_request Nachdem die Antwort erstellt wurde, bevor sie gesendet wird Muss ein Response-Objekt akzeptieren und zurückgeben. Sicherheits-Header, CORS-Header hinzufügen
teardown_request Wenn der Request-Kontext entfernt wird Rückgabewert wird ignoriert Request-Level-Ressourcen freigeben
teardown_appcontext Wenn der App-Kontext entfernt wird Rückgabewert wird ignoriert Datenbankverbindung schließen
errorhandler Wenn ein bestimmter Statuscode oder eine Ausnahme auftritt Der Rückgabewert wird als Antwort für die Fehlerseite verwendet Benutzerdefinierte 404/500-Seiten
url_value_preprocessor Nachdem URL-Variablen extrahiert wurden, bevor die View aufgerufen wird. Rückgabewert wird ignoriert URL-Parameter vorverarbeiten
url_defaults Beim Erstellen von URLs mit url_for Ändert das übergebene values-Dictionary. Fügt Standardparameter zu url_for hinzu.
template_filter — (Art der Registrierung) — Jinja2-Template-Filter registrieren
template_test — (Art der Registrierung) — Jinja2-Template-Test registrieren
template_global — (Art der Registrierung) — Globale Jinja2-Funktion registrieren
shell_context_processor Wenn flask shell startet Gibt ein dict zurück, das in den Shell-Kontext eingefügt wird. Importiert häufig verwendete Objekte vorab in flask shell.

Methode zur Request-Behandlung

Die folgenden Methoden werden intern während der Request-Verarbeitung aufgerufen und können in Unterklassen überschrieben werden:

Methoden Beschreibung
preprocess_request(ctx) Request-Vorverarbeitung: führt before_request-Funktionen und URL-Präprozessoren aus.
dispatch_request(ctx) Kern-Dispatch: gleicht die URL ab und ruft die entsprechende View-Funktion auf.
make_response(rv) Konvertiert den Rückgabewert der View-Funktion in ein Response-Objekt.
finalize_request(ctx, rv) Finalisierung: ruft make_response und after_request-Hooks auf
process_response(ctx, response) Nachverarbeitung der Antwort: führt after_request-Funktionen aus und speichert die Session
full_dispatch_request(ctx) Vollständiger Einstiegspunkt für das Anfrage-Dispatching: preprocess → dispatch → finalize
handle_http_exception(ctx, e) Behandelt HTTP-Ausnahmen, sucht den entsprechenden errorhandler
handle_user_exception(ctx, e) Behandelt Ausnahmen aus Benutzercode und unterscheidet zwischen HTTP-Ausnahmen und normalen Ausnahmen.
handle_exception(ctx, e) Abschließende Ausnahmebehandlung, gibt eine 500-Antwort zurück.
ensure_sync(func) Stellt sicher, dass die Funktion synchron ausgeführt wird. Async-Funktionen werden umhüllt, um synchron zu sein.
make_default_options_response(ctx) Erzeugt automatische OPTIONS-Antworten.
raise_routing_exception(request) Behandelt Routing-Ausnahmen (z. B. Weiterleitungen bei abschließendem Schrägstrich).

Vorlagen und statische Dateien

Methoden Beschreibung
create_jinja_environment() Erstellt und konfiguriert die Jinja2-Umgebung. Wird automatisch beim ersten Zugriff auf jinja_env aufgerufen.
create_global_jinja_loader() Erstellt den Jinja2-Loader, der die Vorlagen-Weiterleitung zwischen der App und Blueprints unterstützt.
select_jinja_autoescape(filename) Bestimmt, ob eine gegebene Datei automatisches Escaping erfordert. Gibt standardmäßig True für .html/.htm/.xml/.xhtml/.svg zurück.
update_template_context(ctx, context) Injiziert integrierte Variablen wie request, session, g, config in den Template-Kontext
send_static_file(filename) Sendet Dateien aus static_folder, automatisch als /static/ registriert.Routing
get_send_file_max_age(filename) Ruft die Cache-Zeit für statische Dateien ab. Standardmäßig wird die Konfiguration SEND_FILE_MAX_AGE_DEFAULT verwendet.
open_resource(resource, mode="rb") Öffnet Ressourcendateien unter root_path im Binärmodus.
open_instance_resource(resource, mode="rb") Öffnet Ressourcendateien unter instance_path und unterstützt den Schreibmodus.

Kontextverwaltung

Methoden Beschreibung
app_context() Erstellt den App-Kontext, der manuell mit einer with-Anweisung gepusht wird. Stellt current_app und g bereit.
request_context(environ) Erstellt den Request-Kontext aus der WSGI-Umgebung.
test_request_context(*args, **kwargs) Erzeugt einen Mock-Request-Kontext zum Testen. Akzeptiert path, method, data, json und weitere Parameter.
wsgi_app(environ, start_response) Kern-WSGI-Anwendungsmethode. Kann Middleware über app.wsgi_app = Middleware(app.wsgi_app) umhüllen.

Test- und Entwicklungswerkzeuge

Methoden Beschreibung
test_client(use_cookies=True, **kwargs) Erstellt einen Testclient zum Simulieren von Browser-Anfragen. Gibt eine FlaskClient-Instanz zurück.
test_cli_runner(**kwargs) Erstellt einen CLI-Test-Runner zum Testen benutzerdefinierter Befehle. Gibt eine FlaskCliRunner-Instanz zurück.
run(host, port, debug, load_dotenv, **options) Startet den Entwicklungsserver. Verwenden Sie Gunicorn/Waitress in der Produktion.
make_shell_context() Erstellt das Kontextwörterbuch für die Flask-Shell. Führt alle shell_context_processor aus.
log_exception(ctx, exc_info) Protokolliert Ausnahmen im Logger und übergibt dabei das exc_info-Tupel

Hilfsmethoden

Methoden Beschreibung
redirect(location, code=303) Erstellt ein Redirect-Antwortobjekt
async_to_sync(func) Konvertiert asynchrone Coroutine-Funktionen in synchrone Funktionen
create_url_adapter(request) Erstellt einen URL-Adapter aus der Anfrage oder Konfiguration, der für den Aufbau von URLs verwendet wird.
inject_url_defaults(endpoint, values) Fügt Standardparameter in den Prozess zur URL-Erstellung ein.
handle_url_build_error(error, endpoint, values) Behandelt url_for-Build-Fehler und kann eine Fallback-URL zurückgeben.
make_config(instance_relative) Erstellt eine Config-Instanz, die von Unterklassen überschrieben werden kann, um die Konfiguration anzupassen
make_aborter() Erstellt eine Aborter-Instanz
trap_http_exception(e) Bestimmt, ob HTTP-Ausnahmen als normale Ausnahmen ausgelöst werden.
auto_find_instance_path() Ermittelt automatisch den Pfad des Instanzordners.

Codebeispiele

Beispiel

from flask import Flask

# Die App erstellen, Template- und Static-Ordner angeben
app = Flask(__name__,
           template_folder="templates",
           static_folder="static",
           instance_relative_config=True)

# Geheimen Schlüssel festlegen
app.secret_key = "your-secret-key"

# Routen registrieren
@app.route("/")
def index():
    return "<h1>Hallo, EXAMPLE!</h1>"

# before_request-Hook registrieren
@app.before_request
def check_auth():
    # Authentifizierungsstatus des Benutzers hier prüfen
    pass

# after_request-Hook registrieren
@app.after_request
def add_header(response):
    # Benutzerdefinierte Header zu jeder Antwort hinzufügen
    response.headers["X-Custom-Header"] = "EXAMPLE"
    return response

# Fehlerbehandler registrieren
@app.errorhandler(404)
def not_found(error):
    return "<h1>Seite nicht gefunden</h1>", 404

# Benutzerdefinierten CLI-Befehl registrieren
@app.cli.command("hello")
def hello_command():
    """Begrüßung ausgeben"""
    print("Hallo von EXAMPLE Flask App!")

Verwandte Dokumentation

Weitere Erweiterungen