Einstieg
Erste Anwendung
Flask ist ein Microframework — es liefert das Nötigste und lässt dich ergänzen, was du brauchst. debug=True aktiviert Auto-Reload und detaillierte Fehlerseiten.
# 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)Entwicklungsserver starten
Den eingebauten Server niemals in Produktion verwenden. FLASK_APP zeigt auf das Modul mit der App-Instanz. Mit --host=0.0.0.0 im Netzwerk erreichbar machen.
# 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.pyVirtuelle Umgebung
Eine virtuelle Umgebung isoliert Projekt-Abhängigkeiten vom System-Python. requirements.txt hält exakte Versionen fest, sodass andere die Umgebung mit pip install -r requirements.txt reproduzieren können.
# 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.txtProjektstruktur
Flask erzwingt kein Layout, aber die Trennung von statischen Dateien, Templates und Konfiguration ist Konvention. Der instance/-Ordner hält deployment-spezifische Secrets, die nicht in die Versionskontrolle gehören.
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 handlersApplication-Factory-Pattern
Das Factory-Pattern schiebt die App-Erzeugung auf den Aufruf einer Funktion — essenziell für mehrere Instanzen, Tests und Extensions. Flasks --app-Option akzeptiert eine Callable, die eine App zurückgibt.
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_appAnatomie einer Minimal-App
__name__ zu übergeben sagt Flask, wo es statische Dateien und Templates findet. Ordnerorte lassen sich mit Konstruktor-Argumenten überschreiben, wenn dein Layout von den Defaults abweicht.
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!"Routing
Variable Rules
Mit <converter:varname> markierte Abschnitte fangen URL-Segmente ab. Eingebaute Konverter: string (Standard), int, float, path (akzeptiert Schrägstriche), uuid. Der Wert wird als Funktionsargument übergeben.
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}"URL-Konverter
Konverter validieren und wandeln URL-Variablen. Eine eigene BaseConverter-Unterklasse auf app.url_map.converters registrieren, um ein Regex-Muster zu erzwingen, etwa für Produktcodes.
@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 codeEindeutige URLs und Umleitung
Abschließende Schrägstriche zählen. Eine Route, die auf '/' endet, leitet die Form ohne Schrägstrich um; eine Route ohne '/' gibt für die Form mit Schrägstrich 404. Pro Route eine Konvention wählen und konsistent bleiben.
@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 FoundHTTP-Methoden
Mit dem methods-Argument mehrere Verben akzeptieren, oder die @app.get / @app.post-Kurzbefehle (Flask 2.0+) für Routen mit einer Methode. GET ist der Standard.
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()URL-Erzeugung mit url_for
url_for erzeugt URLs aus dem Endpunkt-Namen (standardmäßig der Name der View-Funktion). Es überlebt URL-Änderungen und erzeugt mit _external=True absolute URLs.
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/bobMehrere Regeln für eine View
add_url_rule registriert eine URL ohne Decorator. Wenn jede Regel einen eigenen Endpunkt, aber dieselbe View-Funktion mit defaults bekommt, bedient ein Handler mehrere URL-Formen.
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.Request und Response
Das Request-Objekt
request ist ein thread-lokaler Proxy, der an den aktuellen Request-Kontext gebunden ist. Er exponiert URL, Methode, Header, Body und Client-Infos, ohne explizit übergeben zu werden.
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),
}Eine Antwort bauen
make_response gibt volle Kontrolle über Status, Header und Body. Für einfache Fälle: einen String, ein Dict (JSON) oder ein Tupel (body, status, headers) zurückgeben.
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"}Response-Objekte
Response verwenden, wenn ein eigener mimetype nötig ist (z. B. XML, CSV) oder Header. Content-Disposition auf attachment zwingt den Browser zum Download.
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)Eigener Status und Header
Ein (body, status, headers)-Tupel für knappe eigene Antworten. 204 No Content für erfolgreiche Antworten ohne Body, und Standard-HTTP-Statuscodes für Semantik.
@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", 418Streaming-Antworten
Ein Generator als Rückgabewert streamt Daten zum Client. Nützlich für große Dateien (vermeidet das Laden der ganzen Datei in den Speicher) und Server-Sent Events. Einen passenden mimetype setzen.
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 in der Response
set_cookie schreibt einen Set-Cookie-Header; delete_cookie lässt ihn ablaufen. Aus Sicherheitsgründen immer httponly und samesite setzen. Cookies gehören zur Antwort, nicht zum Request-Body.
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 respRequest-Objekt (form/args/files)
Query-Parameter (args)
request.args ist ein MultiDict der Query-String-Werte. get mit Default und Typkonvertierung verwenden, getlist für wiederholte Keys. Niemals direkt indexieren — fehlende Keys werfen 400.
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}Formular-Daten
request.form hält gesendete application/x-www-form-urlencoded- oder multipart-Daten. .get() verwenden, um KeyError bei optionalen Feldern zu vermeiden. GET-Anfragen haben ein leeres form.
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")Datei-Uploads
request.files ist ein MultiDict von FileStorage-Objekten. Nutzergelieferte Dateinamen immer durch secure_filename schicken, um Pfad-Trenner und gefährliche Zeichen zu entfernen, bevor gespeichert wird.
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"JSON-Body
get_json() parst den Body als JSON nur, wenn der Content-Type application/json ist. force=True ignoriert den Header (vorsichtig verwenden). silent=True unterdrückt Parse-Fehler.
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 dataHeader und Cookies
request.headers ist ein dict-artiges EnvironHeaders-Objekt; request.cookies hält die vom Client gesendeten Cookies. Beide sind schreibgeschützt — Response-Header/Cookies auf der Antwort setzen.
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,
}Request-Methoden und Properties
request exponiert Metadaten über Verbindung und Body. is_json prüft den Content-Type, is_secure prüft HTTPS, und query_string ist der rohe Teil nach '?'.
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(),
}Jinja2-Templates
Templates rendern
render_template lädt eine Jinja2-Datei aus dem templates/-Ordner und injiziert Keyword-Argumente als Variablen. Die {{ }}-Syntax gibt einen Ausdruck aus; Flask escapet HTML automatisch zur Sicherheit.
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>Template-Variablen
Jinja2 unterstützt Attribut- (user.name) und Element- (user['age']) Zugriff. Der safe-Filter markiert einen String als vertrauenswürdig, damit er nicht escapet wird — nur auf Inhalte anwenden, die du voll kontrollierst.
# 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>Kontrollstrukturen
Jinja2 unterstützt {% if %}, {% for %} und {% block %}. Innerhalb von Schleifen liefert die besondere loop-Variable index, index0, first, last, length und revindex. for-else läuft, wenn das Iterable leer ist.
{# 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>Template-Vererbung
extends zieht ein Basis-Template herein, und Kinder-Template überschreiben benannte Blocks. So bleibt gemeinsames Layout (Navigation, Skripte) an einem Ort. super() rendert den Inhalt des Eltern-Blocks.
{# 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 %}Filter
Filter transformieren Werte über die Pipe (|)-Syntax und nehmen Argumente. Eigene Filter auf app.jinja_env.filters registrieren, um Logik über Templates hinweg wiederzuverwenden.
{{ 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
Macros sind wiederverwendbare Template-Schnipsel, wie Funktionen. Mit {% from %} oder {% import %} einbinden. Sie halten repetitive HTML-Teile (Formularfelder, Cards) DRY.
{# 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>Statische Dateien
Statische Dateien ausliefern
Flask registriert automatisch eine /static/<path:filename>-Route für den static-Ordner. URLs immer mit url_for bauen, damit Pfade korrekt bleiben, selbst wenn static_url_path sich ändert.
# 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 für statische Assets
url_for('static', filename=...) löst einen Pfad zu einer statischen Datei auf. _external=True für eine absolute URL (praktisch in E-Mails oder Feeds) und Query-Argumente für Cache-Busting.
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.jsEigener statischer Ordner
static_folder (Plattenort) und static_url_path (URL-Präfix) an die Projekt-Konventionen anpassen. Der Standard ist Ordner 'static' gemappt auf /static.
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.cssFavicon
Browser fragen /favicon.ico am Root an, standardmäßig. Eine explizite Route ergänzen oder das Icon über ein <link>-Tag verknüpfen. send_from_directory liefert eine Datei aus einem Verzeichnis sicher aus.
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
Browser cachen statische Assets nach URL. Ein angehängter Versions-Hash zwingt Clients, nach einer Dateiänderung neue Kopien zu laden. Ein Build-Tool (Vite, Flask-Assets) automatisiert das in größeren Projekten.
# 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 }}">Blueprints
Ein Blueprint anlegen
Ein Blueprint gruppiert zugehörige Routen, Templates und statische Dateien zu einem Modul. Das erste Argument ist der Blueprint-Name; url_prefix stellt jedem seiner Routen einen Pfad voran.
# 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")Blueprints registrieren
register_blueprint hängt einen Blueprint an die App. url_prefix lässt sich bei der Registrierung überschreiben, sodass derselbe Blueprint in verschiedenen Apps unter verschiedenen Pfaden montiert werden kann.
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 mit URL-Präfix
url_prefix am Blueprint oder bei der Registrierung definieren. Den API-Pfad zu versionieren (/api/v1) erlaubt später /api/v2, ohne bestehende Clients zu brechen.
# 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...Blueprint-Ressourcen
Ein Blueprint kann eigene templates- und static-Ordner tragen. Die Template-Auflösung prüft zuerst den Blueprint, dann die App, sodass blueprint-lokale Dateien app-weite mit gleichem Namen überdecken.
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')Blueprint-Error-Handler
Blueprint-Ebene-Error-Handler fangen nur Fehler, die von Routen dieses Blueprints geworfen werden — so gibt es abschnittsspezifische Fehlerseiten. App-Ebene-Handler fangen alles Ungefangene.
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"), 403Verschachtelte Blueprints
Flask 2.0+ unterstützt verschachtelte Blueprints. Einen Kind-Blueprint mit register_blueprint auf einem Eltern registrieren; die url_prefixes verketten sich, sodass große Apps aus kleinen Modulen komponiert werden können.
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/infoKontexte (g / session)
Application-Kontext
Der Application-Kontext macht current_app und g außerhalb einer Anfrage verfügbar (z. B. in CLI-Befehlen oder Hintergrund-Tasks). Mit app.app_context() pushen, wenn außerhalb einer Anfrage gearbeitet wird.
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"])Das g-Objekt
g ist ein Namensraum pro Anfrage für gemeinsame Ressourcen wie DB-Verbindungen. Er wird bei jeder Anfrage zurückgesetzt und in einem teardown_appcontext-Handler aufgeräumt.
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()Request-Kontext
Der Request-Kontext bindet request, session und url_for an einen Thread. In Tests und Skripten test_request_context verwenden, um eine Anfrage ohne HTTP-Server zu simulieren.
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)current_app- und request-Proxys
current_app, request, session und g sind LocalProxy-Objekte, die Attribut-Zugriff an den aktiven Kontext weiterreichen. Niemals in einer globalen Variablen ablegen — immer zum Aufrufzeitpunkt zugreifen.
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.Session-Objekt
session ist ein Dict auf Basis eines signierten Cookies. app.secret_key setzen, damit Flask signieren kann. Werte liegen clientseitig und sind vom Nutzer lesbar (aber nicht manipulierbar) — niemals Secrets dort speichern.
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"Kontext-Lebenszyklus
Den Lebenszyklus zu verstehen ist der Schlüssel zur richtigen Nutzung der Hooks. teardown_*-Handler laufen immer, auch bei Fehlern — der richtige Ort, um DB-Verbindungen zu schließen und Ressourcen freizugeben.
# 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)SQLAlchemy-Integration
Flask-SQLAlchemy einrichten
Flask-SQLAlchemy umwickelt SQLAlchemy und integriert es in Flasks App-Kontext. SQLALCHEMY_DATABASE_URI auf den Verbindungsstring setzen und track modifications deaktivieren, um Speicher zu sparen.
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)Models definieren
Models erben von db.Model; Spalten sind db.Column-Instanzen. Häufige Typen: Integer, String, Text, DateTime, Boolean. unique=True und nullable=False für Constraints.
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"))Daten abfragen
Model.query ist eine bequeme Abfrageschnittstelle. filter_by(keyword=value) ist simpel; filter(expression) unterstützt Operatoren wie >, <, like, in_. paginate() liefert items plus Seiten-Metadaten.
# 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()Hinzufügen und Aktualisieren
Alle Änderungen passieren in einer Transaktion über db.session. add stützt ein neues Objekt; commit schreibt es. Bei Fehler mit db.session.rollback() zurückrollen, damit die Session nutzbar bleibt.
# 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()Beziehungen
db.relationship definiert die Verbindung zwischen Models. backref ergänzt ein rückwärtiges Attribut. lazy='dynamic' gibt ein Query-Objekt statt einer Liste zurück — nützlich bei großen Sammlungen, die weiter gefiltert werden sollen.
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 userMigrationen mit Flask-Migrate
Flask-Migrate umwickelt Alembic, um das Schema versionskontrolliert zu halten. migrate generiert ein Skript aus Modell-Änderungen, upgrade wendet es an. Autogenerierte Skripte vor dem Commit immer prüfen.
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 revisionWTForms (Flask-WTF)
Flask-WTF installieren
Flask-WTF integriert WTForms in Flask und ergänzt automatisch CSRF-Schutz. Eine SECRET_KEY ist nötig, damit das CSRF-Token signiert werden kann. CSRF nur bei öffentlichen API-Endpunkten abschalten.
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.Ein Formular definieren
Formulare erben von FlaskForm. Jedes Feld nimmt ein label und eine Liste von validators, die bei validate() laufen. Validatoren erzwingen Pflichtangaben, Länge, E-Mail-Format und mehr.
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")Formular im Template rendern
form.hidden_tag() rendert das CSRF-Token und alle versteckten Felder. Jedes Feld kann label, input und errors einzeln rendern. Für schnelle Ausgabe rendert {{ form.field() }} das HTML-Input.
{# 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>Formular validieren
validate_on_submit() gibt nur für eine POST-Anfrage true zurück, bei der alle Validatoren passen. Bei Erfolg Feldwerte aus form.field.data lesen. Bei Fehlschlag das Template erneut rendern, um Fehler zu zeigen.
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 POSTEingebaute Validatoren
Validatoren sind Callables, die bei Fehlschlag ValidationError werfen. EqualTo ist üblich für Passwort-Bestätigung. In einer Liste verketten; sie laufen der Reihe nach, bis einer scheitert.
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
FileField aus flask_wtf.file mit FileRequired und FileAllowed verwenden, um Uploads zu validieren. Die hochgeladene Datei ist ein FileStorage-Objekt unter form.field.data. Das form-Tag muss enctype=multipart/form-data enthalten.
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)Flask-Login-Authentifizierung
Flask-Login einrichten
Flask-Login verwaltet Nutzer-Sessions: Anmelden, Abmelden und Erinnern von Nutzern. login_view setzen, damit unauthentifizierte Nutzer dorthin umgeleitet werden. login_message blitzt bei dieser Umleitung auf.
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."User-Model
Das User-Model muss UserMixin einmischen (liefert is_authenticated, is_active, get_id usw.) und einen user_loader-Callback implementieren, der einen Nutzer per ID zurückgibt. Passwörter nie im Klartext speichern — hashen.
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))Login-View
login_user lädt den Nutzer in die Session. remember=True für persistente Cookies. Vor dem Anmelden das Passwort immer mit Hash-Check prüfen und bei Fehlschlag eine generische Fehlermeldung blitzen.
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)Routen schützen
Der @login_required-Decorator weist anonyme Nutzer ab und leitet sie zu login_view um. current_user ist ein Proxy auf den angemeldeten Nutzer (oder AnonymousUserMixin), verfügbar in Views und Templates.
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 decoratorLogout
logout_user entfernt den Nutzer aus der Session. Die Route mit @login_required schützen, damit nur angemeldete Nutzer sich abmelden können. Danach auf eine öffentliche Seite (index oder login) umleiten.
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 cookiesRemember me und current_user
remember=True setzt ein separates Cookie, damit Nutzer nach dem Schließen des Browsers angemeldet bleiben. current_user funktioniert in Views wie Templates — so lässt sich UI je nach Auth-Status bedingt rendern.
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 %}Fehlerbehandlung
abort()
abort() stoppt die View sofort und gibt einen HTTP-Fehler zurück. Statuscode und optionale Meldung übergeben. Es wirft eine HTTPException, die Flask in die passende Fehlerantwort umwandelt.
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 ErrorEigene Fehlerseiten
Handler mit @app.errorhandler(code) registrieren. Ein Tupel (template, status_code) zurückgeben. Diese Handler fangen sowohl abort()-Aufrufe als auch Ausnahmen, die zu diesem Status mappen.
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"), 500Error-Handler für Ausnahmen
Handler lassen sich auch für eigene Ausnahme-Klassen registrieren, nicht nur HTTP-Codes. Werft irgendeine View die Ausnahme, greift der Handler — so werden Fehlerantworten für Domänen-Fehler zentralisiert.
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)Catch-All-404-Handler
Ein generischer Exception-Handler ist die letzte Rettung für 500er. HTTPException erneut werfen, damit eingebaute Seiten weiter funktionieren, und den Traceback loggen. Achtung: Stack-Traces nicht an Nutzer durchsickern lassen.
@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"), 500Fehler loggen
Fehler mit exc_info=True loggen, um den vollen Traceback zu erfassen. Ein RotatingFileHandler verhindert unbegrenztes Log-Wachstum. In Produktion Logs an einen zentralen Dienst leiten.
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", 500HTTP-Exception-Behandlung
HTTPException ist die Basisklasse aller Werkzeug-HTTP-Fehler. Ein Handler für HTTPException fängt alle auf einmal, während ein handler für eine Unterklasse (NotFound) für diesen Code Vorrang hat.
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", 404JSON und API
jsonify
jsonify wandelt Python-Dicts/Listen in eine JSON-Antwort mit korrektem Content-Type und ASCII-sicherem Escaping. Seit Flask 2.1+ kann man direkt eine Liste übergeben; ältere Versionen verlangen ein Dict.
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 escapingJSON zurückgeben
Ein Dict oder eine Liste direkt zurückzugeben ist der einfachste Weg, JSON zu senden. Für eigene Statuscodes oder Header ein Tupel zurückgeben. Response + json.dumps nur, wenn die Serialisierung voll kontrolliert werden soll.
# 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")JSON empfangen
get_json() parst den Body als JSON, wenn der Content-Type application/json ist. Die geparste Struktur vor der Verwendung immer validieren — Client-Input nie vertrauen. 400/422 für malformed Payloads zurückgeben.
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"]}), 201API-Blueprint
API-Routen in einem Blueprint mit versioniertem url_prefix gruppieren (/api/v1). Das trennt API-Logik von Seiten-Routen und macht Versionierung explizit — bei Breaking Changes auf /api/v2 heben.
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 ergänzt den Access-Control-Allow-Origin-Header, damit Browser Cross-Origin-Anfragen erlauben. In Produktion Ursprünge auf vertrauenswürdige Domains beschränken statt des Wildcards '*'.
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"}API-Fehlerantworten
Eine Helferfunktion hält Fehlerantworten über Endpunkte hinweg einheitlich — gleiche Form, gleiche Key-Namen. Konsistente Fehler-Bodies machen clientseitige Fehlerbehandlung deutlich einfacher. Details aufnehmen, die beim Debuggen helfen, ohne Secrets preiszugeben.
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}Datei-Upload
Einfacher Upload
Das form-Tag braucht enctype=multipart/form-data für Datei-Uploads. MAX_CONTENT_LENGTH setzen, um übergroße Uploads mit 413 abzulehnen, bevor der Body komplett gelesen wird — das schützt den Server.
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>Sicherer Dateiname
secure_filename entfernt Directory-Traversal und unsichere Zeichen aus nutzergelieferten Dateinamen. Einzigartigkeit garantiert es nicht — UUID anhängen oder Kollisionen prüfen, wenn Überschreiben ein Risiko ist.
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}"Mehrere Dateien
request.files.getlist('files') mit einem input mit multiple-Attribut verwenden, um mehrere Dateien auf einmal zu akzeptieren. Vor dem Speichern Extension und Größe jeder Datei prüfen.
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 mit WTForms
Flask-WTFs FileField validiert Extension und Vorhandensein des Uploads. Das form-Tag muss enctype=multipart/form-data enthalten. Die hochgeladene Datei liegt unter form.photo.data.
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)Dateityp und -größe validieren
Vor dem Speichern Extension und Inhaltslänge prüfen. MAX_CONTENT_LENGTH lehnt riesige Anfragen früh ab, aber Checks pro Datei geben feinere Kontrolle. Für mehr Sicherheit die Magic Bytes der Datei prüfen, nicht nur die Extension.
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"Before/After-Request-Hooks
before_request
before_request-Handler laufen vor jeder View. Für Auth-Checks, Wartungsmodus oder das Laden gemeinsamen Zustands auf g verwenden. Ein Rückgabewert überspringt die View und nutzt die Antwort direkt.
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 requestafter_request
after_request-Handler laufen nach der View, empfangen und geben die Antwort zurück. Ideal für Header, Logging oder Caching. Bei einer unbehandelten Ausnahme wird after_request übersprungen.
@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 objectteardown_request
teardown_request läuft am Ende jeder Anfrage, auch bei Fehlern — anders als after_request. Es erhält die Ausnahme (oder None) und ist der richtige Ort, um Ressourcen wie DB-Verbindungen oder Datei-Handles freizugeben.
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 raisedbefore_first_request (deprecated)
before_first_request wurde in Flask 2.3 entfernt, weil es mit modernen Async-Servern und Multi-Prozess-Setups bricht. Einmal-Setup innerhalb eines App-Kontexts beim Import oder in einem CLI-Befehl ausführen.
# 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()Response modifizieren
Mehrere after_request-Handler verketten sich in umgekehrter Registrierungs-Reihenfolge. Jeder muss eine Antwort zurückgeben. Nützlich für Security-Header, Caching-Direktiven und Tracing-IDs.
@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.Datenbank-Verbindungsmuster
Ein verbreitetes Muster: eine Verbindung bei Bedarf in get_db öffnen (auf g abgelegt) und in teardown_appcontext schließen. So bekommt jede Anfrage ihre eigene Verbindung, und Aufräumen ist auch bei Fehlern garantiert.
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]}CLI-Befehle
Eigene Befehle
@app.cli.command registriert einen CLI-Befehl, dekoriert mit click-Argumenten und Optionen. Der Docstring wird zum Hilfetext. flask --help listet alle verfügbaren Befehle.
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 --adminflask run
flask run startet den Werkzeug-Dev-Server. --debug aktiviert Reloader und interaktiven Debugger. --app erlaubt das Zeigen auf ein Modul oder eine Factory. Diesen Server nie in Produktion verwenden — single-threaded und unsicher.
# 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.pemShell-Kontext
shell_context_processor injiziert Namen in die flask shell, sodass man ohne Imports experimentieren kann. Unbezahlbar, um Models zu debuggen und Ad-hoc-Queries gegen die App zu fahren.
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"))Application-Factory mit CLI
Beim Factory-Pattern CLI-Befehle innerhalb von create_app registrieren, damit sie Zugriff auf die konfigurierte App haben. Flasks --app-Option erkennt die Factory und ruft sie automatisch auf.
# 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.CLI-Gruppen
Zusammengehörige Befehle mit @app.cli.group unter einem Eltern gruppieren. Subcommands werden auf der Gruppe registriert und halten die CLI geordnet: flask db init, flask db migrate usw.
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 dropUmgebungsvariablen
FLASK_APP und FLASK_DEBUG konfigurieren die CLI. .flaskenv für geteilte Dev-Einstellungen und .env für Secrets (beide werden automatisch geladen, wenn python-dotenv installiert ist). Secrets nicht in .flaskenv, da sie typischerweise committed wird.
# 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.Testen
Test-Client-Grundlagen
test_client() gibt einen Client zurück, der Anfragen ohne Netzwerk macht. TESTING=True für bessere Fehlermeldungen und deaktiviertes Fehlerfangen. Ein Fixture verwenden, damit jeder Test eine frische App bekommt.
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.dataAnfragen in Tests stellen
Der Test-Client imitiert einen Browser: get/post/put/delete mit data (Formular), json, query_string und headers. resp.get_json() zum Parsen einer JSON-Antwort, resp.headers zum Inspektieren.
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"})JSON-API testen
json=... übergeben, um einen JSON-Body mit richtigem Content-Type zu senden. Auf Status, geparsten JSON-Body und Header wie Location assertionen. Erfolgs- und Fehlerpfade beide zu testen stellt konsistentes API-Verhalten sicher.
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 mit pytest
Fixtures liefern wiederverwendbares Setup: eine In-Memory-Datenbank, einen Test-Client und einen CLI-Runner. Ressource yielden und danach aufräumen. test_cli_runner() ruft CLI-Befehle in Tests auf und prüft Ausgabe und Exit-Code.
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 == 0Test-Datenbank
Eine In-Memory-SQLite-Datenbank für schnelle, isolierte Tests. Tabellen und Seed-Daten im Fixture anlegen, danach alles droppen. Jeder Test startet mit leerer Bühne und verhindert Kontamination zwischen Tests.
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() == 1Mocking
patch ersetzt externe Aufrufe (HTTP, E-Mail, Queues) durch Mocks, damit Tests schnell und deterministisch bleiben. Assertionen, dass der Mock mit den erwarteten Argumenten aufgerufen wurde. Immer dort patchen, wo der Name gesucht wird, nicht wo er definiert ist.
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!")Deployment
Warnung: Produktionsserver
Der Werkzeug-Dev-Server ist single-threaded und unsicher — niemals ins Internet exponieren. Einen Produktions-WSGI-Server (Gunicorn, uWSGI, Waitress) hinter einem Reverse-Proxy verwenden. Der Debug-Debugger ist ein Risiko für Remote Code Execution.
# 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 ist der populärste WSGI-Server für Linux/macOS. Die Formel (2 × CPU + 1) worker ist ein guter Startpunkt. Hinter Nginx auf 127.0.0.1 binden und dem Proxy TLS und statische Dateien überlassen.
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 ist ein hochperformanter, sehr konfigurierbarer WSGI-Server. Der master process verwaltet worker; vacuum räumt beim Beenden auf. Mit Nginx über das uwsgi-Protokoll paaren für besten Durchsatz.
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.iniReverse-Proxy (Nginx)
Nginx sitzt vor Gunicorn: es liefert statische Dateien direkt aus (schneller), terminiert TLS und leitet Anfragen an den WSGI-Server weiter. Die X-Forwarded-*-Header lassen Flask die echte Client-IP und das Schema sehen — ProxyFix setzen, um ihnen zu vertrauen.
# /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
Ein schlankes Python-Basis-Image hält das Image klein. Abhängigkeiten vor dem Kopieren des Codes installieren, um Docker's Layer-Cache zu nutzen. Secrets über Umgebungsvariablen (--env-file) übergeben, niemals ins Image bäcken.
# 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 myappUmgebungs-Konfiguration
Konfiguration schichten: Defaults im Code, umgebungsspezifische Overrides und Instanz-Secrets aus Env-Variablen. So bleiben Secrets aus der Quellkontrolle draußen und eine Codebasis läuft in Dev, Staging und Produktion.
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()Konfiguration
Config-Objekt
Konfiguration als Klassen definieren, die von einem Basis-Config erben. Nur überschreiben, was sich je Umgebung ändert. from_object kopiert großgeschriebene Attribute auf app.config — kleingeschriebene Helfer werden ignoriert.
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)Umgebungsvariablen
os.environ für Secrets verwenden, damit sie nie im Code liegen. from_envvar lädt eine Python-Datei, auf die eine Env-Variable zeigt — nützlich für deployment-spezifische Overrides. python-dotenv lädt eine .env-Datei für lokale Entwicklung.
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()Instance-Ordner
Der instance-Ordner hält deployment-spezifische Dateien (Secrets, Konfiguration) außerhalb der Versionskontrolle. instance_relative_config=True setzen und mit from_pyfile laden. Das trennt Code und Umgebungskonfiguration sauber.
# 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/instanceConfig aus Datei
from_object importiert einen Modul- oder Objektpfad; from_pyfile lädt eine absolute Datei; from_file (Flask 2.0+) nutzt eine Loader-Funktion und unterstützt JSON, TOML oder YAML. Ein Format wählen und konsistent bleiben.
# 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" }Entwicklung vs. Produktion
Configs über eine Umgebungsvariable umschalten, sodass derselbe Code überall läuft. Produktion muss debug deaktivieren (der Debugger ist ein Sicherheitsloch) und eine echte Datenbank verwenden. Bei debug in Produktion eine Warnung loggen.
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!")Logging-Konfiguration
Logging nur konfigurieren, wenn nicht im Debug-Modus (Flask loggt im Debug standardmäßig nach stderr). RotatingFileHandler verhindert unbegrenztes Log-Wachstum. In Produktion strukturiertes JSON-Logging für Aggregationsdienste erwägen.
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.LoggerVerwandte Flask-Snippets
Copy-paste ready code for common tasks.
Routing
Define routes with methods and dynamic parameters.
Request and Response
Access request data and build custom responses.
Jinja2 Templates
Render templates with context and template inheritance.
Blueprints
Organize an app into modular blueprints.
Session
Store per-user data in signed session cookies.
Error Handling
Register custom error handlers for HTTP exceptions.
Flask-SQLAlchemy
Define models and query them with Flask-SQLAlchemy.
Custom Decorators
Build decorators to gate or augment view functions.
Was this helpful?