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