Skip to content

3. Das Modell einer Aktion

Eine Aktion benötigt Informationen, die der Browser sendet: die Parameter der URL ([?name=martin&age=42]), Formularfelder, den JSON-Rumpf der Anfrage und manchmal einen HTTP-Anfrage-Header. Der ursprüngliche Kurs bezeichnet alle diese Informationen als das Modell der Aktion. Dieses Kapitel zeigt, wie eine Aktion diese Informationen abruft, in den richtigen Typ umwandelt und validiert. Dieser Vorgang heißt Data-Binding.

[Flask] ist hier viel minimalistischer als andere Frameworks: Es stellt den Zugriff auf die Anfrageinformationen in Form von Zeichenketten bereit und hört dort auf. Das Umwandeln von ["42"] in die Ganzzahl 42, das Prüfen, dass ein Name mindestens zwei Zeichen hat, und das Zusammenfügen der Felder zu einem Objekt – all das ist Aufgabe der Anwendung. Wir tun dies zuerst von Hand (Beispiel 07) und dann mit der Bibliothek [Pydantic] (Beispiele 08–12), die ein Modell durch eine Klasse beschreibt, in der jedes Feld seinen Typ und seine Einschränkungen angibt. Im nächsten Kapitel werden die HTML-Formulare von einer anderen Bibliothek behandelt, [WTForms], die eigens dafür entworfen wurde; [Pydantic] bleibt das natürliche Werkzeug für die Parameter einer URL und für die JSON-Rümpfe der API.

Hinweis zur Terminologie: Im folgenden Kapitel bezeichnet das Wort „Modell“ in erster Linie die Daten, die eine Aktion an ihre View übergibt. Das Modell einer Aktion im Sinne dieses Kapitels ist das, was sie empfängt.

Die Beispiele 07 bis 12 werden auf dieselbe Weise ausgeführt wie die des vorherigen Kapitels: Öffnen Sie ein Terminal im Beispielverzeichnis, bei aktivierter virtueller Umgebung ([python app.py]); [Ctrl-C] beendet den Server. Ihre [app.py]-Dateien sind einander alle ähnlich: eine Factory [create_app] , die die Anwendung erstellt, den JSON-Provider konfiguriert (Akzente erhalten, Schlüssel in ihrer ursprünglichen Reihenfolge; siehe Beispiel 03) und einen Blueprint registriert. Wir kommentieren sie nur, wenn sie etwas Neues einführen.

3.1. Beispiel 07: Die Parameter der URL

Die Parameter der URL sind der Teil, der auf [?] folgt: [?name=martin&age=42]. Dieser Teil heißt Query-String (*query string*). Jeder Parameter ist ein Paar der Form [name=value]; die Paare sind durch [&] getrennt. Die Datei [controllers/parameters.py]:

# controllers/parameters.py: die Parameter der URL (der "Query-String")
from flask import Blueprint, abort, request

parameters = Blueprint("parameters", __name__, url_prefix="/parameters")


# /parameters/action01?name=martin: request.args enthält die Parameter der
# URL; get liefert den Wert des Parameters oder None, wenn er fehlt
@parameters.get("/action01")
def action01():
    name = request.args.get("name")
    return f"name = [{name}], of type {type(name).__name__}"


# /parameters/action02?age=42: type=int KONVERTIERT den Wert (einen String) in
# eine Ganzzahl; ein fehlender Parameter oder einer, der keine Ganzzahl ist, ergibt None
@parameters.get("/action02")
def action02():
    age = request.args.get("age", type=int)
    return f"age = [{age}], of type {type(age).__name__}"


# /parameters/action03?age=42: ein ERFORDERLICHER Parameter; sein Fehlen oder ein
# Wert, der keine Ganzzahl ist, beendet die Action mit einer 400-Antwort (Bad Request)
@parameters.get("/action03")
def action03():
    text = request.args.get("age")
    if text is None:
        # abort löst eine Exception aus, die Flask in eine Fehlerantwort umwandelt
        abort(400, "the [age] parameter is required")
    # die Konvertierung liegt bei uns
    try:
        age = int(text)
    except ValueError:
        abort(400, f"[{text}] is not an integer")
    return f"age = [{age}], of type {type(age).__name__}"


# /parameters/action04?page=2: ein Standardwert, wenn der Parameter fehlt
@parameters.get("/action04")
def action04():
    page = request.args.get("page", default=1, type=int)
    return f"page = [{page}]"


# /parameters/action05?q=flask: der Name des URL-Parameters ist nicht unbedingt
# der der Python-Variablen
@parameters.get("/action05")
def action05():
    search = request.args.get("q")
    return f"search = [{search}]"


# /parameters/action06?name=martin&age=42: alle Parameter auf einmal, als Dictionary
@parameters.get("/action06")
def action06():
    return request.args.to_dict()
  • Zeile 11: [request.args] enthält die Parameter der URL, die bereits von [Werkzeug] decodiert wurden. Dies ist ein spezielles Dictionary, ein [MultiDict], das, wie wir in Beispiel 10 sehen werden, mehrere Werte pro Schlüssel akzeptiert. Seine Methode [get] gibt den Wert eines Parameters zurück oder [None] , falls er fehlt. Anders als [request.args["name"]], das bei einem fehlenden Parameter eine Ausnahme auslösen würde, verursacht [get] nie einen Fehler;
  • Zeile 12: Die Aktion zeigt den Wert und seinen Typ an: [type(x)] ist die Klasse von [x], und [__name__] ist der Name dieser Klasse. Ein aus der URL abgerufener Wert ist immer eine Zeichenkette ([str]);
  • Zeile 19: Der Parameter [type] von [get] gibt eine Konvertierungsfunktion an, die auf die Zeichenkette angewendet wird: hier [int], die Klasse der Ganzzahlen, deren Aufruf [int("42")] den Wert 42 zurückgibt. Bei einer fehlgeschlagenen Konvertierung ([int("abc")] löst einen [ValueError] aus) liefert [get] den Wert [None], ganz wie bei einem fehlenden Parameter: Die Aktion kann die beiden Fälle nicht unterscheiden, und der Eingabefehler bleibt unbemerkt;
  • Zeilen 26–35: ein obligatorischer Parameter und eine manuelle Konvertierung, die die beiden möglichen Fehler unterscheidet. [abort(400, message)] beendet die Action mit einer Antwort 400 (*Bad Request* – die Anfrage ist ungültig) samt der Meldung (siehe Beispiel 03). Die Anweisung [try] / [except ValueError] fängt die Ausnahme ab, die von [int] ausgelöst wird;
  • Zeile 42: ein Standardwert, der verwendet wird, wenn der Parameter fehlt (oder wenn seine Konvertierung fehlschlägt). Das ist ein typischer Fall für eine Seitennummer in einer Liste;
  • Zeile 50: Die [Python]-Variable muss nicht denselben Namen tragen wie der URL-Parameter. Suchmaschinen verwenden oft einen kurzen Parameter, [q] (*query*);
  • Zeile 57: [to_dict()] wandelt [MultiDict] in ein gewöhnliches [Python]-Dictionary um (wobei nur der erste Wert jedes Parameters beibehalten wird), das die Action zurückgibt: [Flask] wandelt es in JSON um (siehe Beispiel 03).

Testen wir jede Action mit [curl]. Zuerst ist ein Parameter vorhanden, dann fehlt er:

curl -i "http://localhost:5000/parameters/action01?name=martin"
curl http://localhost:5000/parameters/action01
1
2
3
4
5
6
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Content-Length: 28

name = [martin], of type str
name = [None], of type NoneType

Die Anführungszeichen um die URL sind in einem Terminal notwendig: Ohne sie würde die Shell [&] (das unter [Linux] einen Befehl im Hintergrund ausführt) und [?] interpretieren. Ein Wert mit Leerzeichen oder Sonderzeichen muss in der URL codiert werden: Ein Leerzeichen wird zu [%20], und [&] wird zu [%26] (sonst würde es zwei Parameter trennen). Der Browser erledigt das automatisch; mit [curl] müssen Sie es selbst ausschreiben. [Werkzeug] decodiert den Wert, bevor er in [request.args] gespeichert wird:

curl "http://localhost:5000/parameters/action01?name=jean%20dupont%20%26%20sons"
name = [jean dupont & sons], of type str

Die Konvertierung mit [type=int], die zunächst gelang und dann fehlschlug:

curl "http://localhost:5000/parameters/action02?age=42"
curl "http://localhost:5000/parameters/action02?age=abc"
age = [42], of type int
age = [None], of type NoneType

Der obligatorische Parameter der Action 03, zunächst fehlend und dann ungültig:

curl -i http://localhost:5000/parameters/action03
curl "http://localhost:5000/parameters/action03?age=abc"
HTTP/1.1 400 BAD REQUEST
Content-Type: text/html; charset=utf-8
Content-Length: 122

<!doctype html>
<html lang=en>
<title>400 Bad Request</title>
<h1>Bad Request</h1>
<p>the [age] parameter is required</p>
<!doctype html>
<html lang=en>
<title>400 Bad Request</title>
<h1>Bad Request</h1>
<p>[abc] is not an integer</p>

Der Standardwert und der umbenannte Parameter:

1
2
3
curl http://localhost:5000/parameters/action04
curl "http://localhost:5000/parameters/action04?page=3"
curl "http://localhost:5000/parameters/action05?q=flask"
1
2
3
page = [1]
page = [3]
search = [flask]

Schließlich alle Parameter auf einmal. Der Parameter [name] erscheint zweimal: [to_dict()] behält nur den ersten Wert.

curl "http://localhost:5000/parameters/action06?name=martin&age=42&name=durand"
1
2
3
4
{
  "name": "martin",
  "age": "42"
}

Das Alter blieb ein String (["42"], in JSON in Anführungszeichen): Es wurde keine Konvertierung angefordert. In einem Browser (hier [Chromium]) erscheint JSON in einer einzigen Zeile: [Flask] rückt JSON nur im Debug-Modus ein, und der Screenshot wurde ohne diesen erstellt; das Kontrollkästchen „Pretty-print“ würde es eingerückt anzeigen. Übrigens zeigt die Adressleiste die Codierung von Umlauten und Akzentzeichen in der URL ([é] wird zu [%C3%A9], mit seinen zwei Bytes in [UTF-8]):

Image

Dieses erste Beispiel zeigt die Grenzen des manuellen Ansatzes: Für jeden Parameter müssen Sie das Lesen, die Konvertierung sowie die Behandlung fehlender Werte und von Fehlern selbst schreiben. Bei zehn Parametern würde der Code der Action von diesen Prüfungen überwuchert. Besser ist es, zu beschreiben, was erwartet wird, und die Überprüfung einer Bibliothek zu überlassen. Genau das ist der Zweck des folgenden Beispiels.

3.2. Beispiel 08: Ein durch eine Klasse beschriebenes Action-Modell

[Pydantic] ist die am häufigsten verwendete Bibliothek zur Datenvalidierung in [Python] (sie bildet den Kern des Frameworks [FastAPI]). Sie beschreibt die von einer Klasse erwarteten Daten: Jedes Attribut hat einen Typ und optional Einschränkungen. [Pydantic] übernimmt die Konvertierung der empfangenen Daten in diese Typen und die Validierung der Einschränkungen. Es ist in der virtuellen Umgebung des Beispiels installiert (Datei [requirements.txt]).

3.2.1. Das Modell: models/person.py

# models/person.py: das Modell der Action, eine Pydantic-Klasse, in der jedes
# Feld seinen Typ und seine Einschränkungen trägt
from typing import Annotated, Literal

from pydantic import BaseModel, ConfigDict, EmailStr, Field


class PersonModel(BaseModel):
    # von den empfangenen Strings werden die umgebenden Leerzeichen entfernt
    model_config = ConfigDict(str_strip_whitespace=True)

    # erforderlich (kein Standardwert), 2 bis 20 Zeichen
    name: Annotated[str, Field(min_length=2, max_length=20)]
    # eine Ganzzahl ("42" wird in 42 umgewandelt), zwischen 0 und 150
    age: Annotated[int, Field(ge=0, le=150)]
    # nur einer dieser drei Werte
    title: Literal["Mr", "Mme", "Melle"]
    # optional (standardmäßig None); falls vorhanden, eine gültige E-Mail-Adresse
    email: EmailStr | None = None
  • Zeile 8: Ein [Pydantic]-Modell ist eine Klasse, die von [BaseModel] erbt. Ihre Attribute werden auf Klassenebene zusammen mit ihren Typen deklariert, wie in einer [dataclass] (Beispiel 06);
  • Zeile 10: Die Konfiguration des Modells. [str_strip_whitespace=True] entfernt die Leerzeichen um die empfangenen Strings: Ein als [" martin "] eingegebener Name wird vor der Validierung zu ["martin"]. Das Attribut [model_config] ist kein Feld des Modells: [Pydantic] erkennt diesen reservierten Namen;
  • Zeile 13: das Feld [name]. [Annotated[str, Field(...)]] liest sich als „der Typ [str], annotiert mit [Field(...)]“. [Annotated] aus dem Standardmodul [typing] erlaubt es, einem Typ zusätzliche Informationen anzufügen – Informationen, die [Python] ignoriert, die aber die Bibliotheken auslesen: hier die Einschränkungen von [Pydantic], eine Länge von 2 bis 20 Zeichen ([min_length], [max_length]). Das Feld hat keinen Standardwert: Es ist obligatorisch;
  • Zeile 15: der Typ [int]: [Pydantic] konvertiert den String ["42"] in die Ganzzahl 42 und lehnt ["abc"] ab. Die Einschränkungen [ge] (*greater or equal*) und [le] (*less or equal*) begrenzen den Wert. Für strikte Ungleichungen gibt es außerdem [gt] und [lt];
  • Zeile 17: [Literal["Mr", "Mme", "Melle"]] ist der Typ der drei aufgeführten Werte, und nur dieser;
  • Zeile 19: [EmailStr] ist der Typ einer E-Mail-Adresse; [Pydantic] validiert ihre Syntax mithilfe der Bibliothek [email-validator] (die ebenfalls durch [requirements.txt] installiert wird). [EmailStr | None]: eine Adresse oder [None]. Der Standardwert [= None] macht das Feld optional.

Dieses Modell beschreibt die erwarteten Daten; es enthält keine Validierungsanweisungen. Man spricht von einem deklarativen Stil.

3.2.2. Die Action: controllers/persons.py

# controllers/persons.py: eine Action, deren Modell eine Pydantic-Klasse ist
from flask import Blueprint, request

from models.person import PersonModel

persons = Blueprint("persons", __name__, url_prefix="/persons")


# /persons/action01?name=martin&age=42&title=Mr
# model_validate: Pydantic erstellt das Objekt aus dem Dictionary der Parameter
# (BINDING: Umwandlung der Strings in den Typ jedes Feldes) und prüft dann
# die Einschränkungen (VALIDIERUNG). Ein ungültiges Modell löst eine ValidationError aus,
# die von app.py in eine 400-Antwort umgewandelt wird: die Action endet dort
@persons.get("/action01")
def action01():
    person = PersonModel.model_validate(request.args.to_dict())
    return {
        # model_dump: das Objekt als Dictionary (nach JSON serialisierbar)
        "person": person.model_dump(),
        "ageType": type(person.age).__name__,
    }
  • Zeile 16: Die Klassenmethode [model_validate] erzeugt aus einem Dictionary – hier demjenigen, das die URL-Parameter enthält – ein [PersonModel]-Objekt. Sie führt zwei Schritte in dieser Reihenfolge aus: - Binding: Jeder Wert des Dictionarys wird dem gleichnamigen Feld zugewiesen, nachdem er in den Typ des Feldes konvertiert wurde (["42"] → 42); - Validierung: Die Einschränkungen jedes Feldes werden geprüft (Länge, Grenzen, zulässige Werte usw.).
  • Schlägt einer der beiden Schritte fehl, löst [model_validate] eine [ValidationError]-Ausnahme aus, die eine Liste aller Fehler enthält (nicht nur des ersten). Die Action behandelt sie nicht: Sie bricht ab; wer sich darum kümmert, sehen wir gleich;
  • Zeile 19: [model_dump()] gibt das Objekt als Dictionary zurück, das [Flask] in JSON umwandeln kann;
  • Zeile 20: der Typ des Alters, um zu zeigen, dass die Konvertierung stattgefunden hat.

3.2.3. Fehlerbehandlung: app.py

# app.py: die Anwendung von Beispiel 08
from flask import Flask
from pydantic import ValidationError

from controllers.persons import persons


def create_app():
    app = Flask(__name__)
    # JSON: Akzente beibehalten, Schlüssel in ihrer ursprünglichen Reihenfolge (siehe Beispiel 03)
    app.json.ensure_ascii = False
    app.json.sort_keys = False
    app.register_blueprint(persons)

    # ein ungültiges Modell: die Exception ValidationError von Pydantic wird
    # für die GESAMTE Anwendung zu einer 400-Antwort, die die Fehler im Detail aufführt
    @app.errorhandler(ValidationError)
    def invalid_model(e: ValidationError):
        errors = [{"field": ".".join(str(x) for x in err["loc"]), "message": err["msg"]}
                  for err in e.errors()]
        return {"status": 400, "errors": errors}, 400

    return app


if __name__ == "__main__":
    create_app().run(port=5000, debug=True)
  • Zeilen 17–21: Der Dekorator [@app.errorhandler(ValidationError)] registriert einen Exception-Handler: Löst eine Action eine [ValidationError] (oder eine Ausnahme einer abgeleiteten Klasse) aus, ruft [Flask] diese Funktion auf, übergibt ihr die Ausnahme als Parameter und liefert ihren Rückgabewert als Antwort zurück. Auf Anwendungsebene deklariert, gilt der Handler für alle Actions: Jede Action, die ein Modell validiert, profitiert davon, ohne eine einzige Zeile Fehlerbehandlungscode schreiben zu müssen;
  • Zeile 19: [e.errors()] gibt die Liste der Fehler zurück. Jeder Fehler ist ein Dictionary; wir behalten zwei Informationen: [loc] (*location*), das betroffene Feld in Form eines Tupels ([("name",)]; ein längeres Tupel zeigt Beispiel 10), und [msg], die Meldung. Der Ausdruck [[... for err in e.errors()]] ist eine List Comprehension: Sie erzeugt eine Liste, indem der Ausdruck links auf jedes Element angewendet wird;
  • Zeile 21: ein Tupel [(body, code)] (siehe Beispiel 03): ein Dictionary, das in JSON umgewandelt wird, und der Code 400.

3.2.4. Ausführung

Ein gültiges Modell:

curl -i "http://localhost:5000/persons/action01?name=martin&age=42&title=Mr"
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 116

{
  "person": {
    "name": "martin",
    "age": 42,
    "title": "Mr",
    "email": null
  },
  "ageType": "int"
}

Das Alter ist tatsächlich eine Ganzzahl geworden (ohne Anführungszeichen in JSON), und die fehlende Adresse ist [None] ([null] in JSON). Ein von Leerzeichen umgebener Name ([%20]) und eine vorhandene Adresse:

curl "http://localhost:5000/persons/action01?name=%20%20martin%20&age=42&title=Mme&email=martin@example.com"
1
2
3
4
5
6
7
8
9
{
  "person": {
    "name": "martin",
    "age": 42,
    "title": "Mme",
    "email": "martin@example.com"
  },
  "ageType": "int"
}

Keine Parameter: Die drei obligatorischen Felder fehlen.

curl -i http://localhost:5000/persons/action01
HTTP/1.1 400 BAD REQUEST
Content-Type: application/json
Content-Length: 248

{
  "status": 400,
  "errors": [
    {
      "field": "name",
      "message": "Field required"
    },
    {
      "field": "age",
      "message": "Field required"
    },
    {
      "field": "title",
      "message": "Field required"
    }
  ]
}

Vier ungültige Felder auf einmal:

curl "http://localhost:5000/persons/action01?name=m&age=abc&title=Mlle&email=xx"
{
  "status": 400,
  "errors": [
    {
      "field": "name",
      "message": "String should have at least 2 characters"
    },
    {
      "field": "age",
      "message": "Input should be a valid integer, unable to parse string as an integer"
    },
    {
      "field": "title",
      "message": "Input should be 'Mr', 'Mme' or 'Melle'"
    },
    {
      "field": "email",
      "message": "value is not a valid email address: An email address must have an @-sign."
    }
  ]
}

Alle Fehler werden auf einmal gemeldet, sodass der Benutzer alles in einem Zug korrigieren kann. Die Meldungen sind auf Englisch: [Pydantic] wird nicht übersetzt. Das folgende Beispiel ersetzt sie durch eigene Meldungen.

3.3. Beispiel 09: Von der Action durchgeführte Validierung

In Beispiel 08 unterbricht ein ungültiges Formular die Action, und der Handler der Anwendung antwortet. Das ist praktisch für eine API, deren Clients Programme sind, die eine standardisierte Fehlerantwort erwarten. Eine Webseite zieht es jedoch oft vor, das Formular mit den Fehlermeldungen erneut anzuzeigen: In diesem Fall muss die Action entscheiden, wie ein ungültiges Modell behandelt wird. Das Modell [models/person.py] ist das aus Beispiel 08.

3.3.1. Benutzerdefinierte Meldungen: models/messages.py

# models/messages.py: die Meldungen der Validierungsfehler, auf Englisch.
# Jeder Pydantic-Fehler ist ein Dictionary: sein TYP ("missing",
# "string_too_short" ...), das betroffene Feld (loc), eine Meldung auf Englisch (msg)
# und der Kontext (ctx): die Werte der Einschränkungen ({"min_length": 2} ...)
MESSAGES = {
    "missing": "the field is required",
    "string_too_short": "{min_length} character(s) at least",
    "string_too_long": "{max_length} character(s) at most",
    "int_parsing": "an integer is expected",
    "greater_than_equal": "the value must be greater than or equal to {ge}",
    "less_than_equal": "the value must be less than or equal to {le}",
    "literal_error": "unknown value",
    "value_error": "invalid value",
    "too_short": "{min_length} item(s) at least",
}


# der Name des Feldes: loc ist ein Tupel, ("name",) oder ("color", 1) für das zweite
# Element einer Liste
def field(error: dict) -> str:
    return ".".join(str(x) for x in error["loc"])


# unsere eigene Meldung; bei einem unbekannten Fehlertyp bleibt die Meldung von Pydantic
def message_en(error: dict) -> str:
    template = MESSAGES.get(error["type"])
    if template is None:
        return error["msg"]
    # format ersetzt {min_length} ... durch die Werte des Kontexts
    return template.format(**error.get("ctx", {}))
  • Zeilen 5–14: Jeder Fehler in [Pydantic] hat einen Typ und eine eindeutige Kennung (["missing"] für ein fehlendes Feld, ["string_too_short"] für einen zu kurzen String usw.), unabhängig von der englischen Meldung. Das Dictionary [MESSAGES] ordnet jedem Typ eine eigene Meldung zu. Einige enthalten Platzhalter wie [{min_length}], [{ge}] ...: Die Dokumentation von [Pydantic] liefert für jeden Fehlertyp die Werte seines Kontexts;
  • Zeilen 20–21: der Name des Feldes, das den Fehler verursacht, entnommen aus dem Tupel [loc]. [".".join(...)] fügt die Elemente des Tupels – in Strings umgewandelt – zusammen und trennt sie durch Punkte;
  • Zeilen 25–30: unsere eigene Fehlermeldung. [MESSAGES.get(...)] gibt [None] für einen Fehlertyp zurück, der im Dictionary nicht gefunden wird; in diesem Fall wird die englische Meldung von [Pydantic] verwendet. Andernfalls [format] ersetzt es jedes Vorkommen von [{name}] in der Meldung durch den gleichnamigen Wert aus dem Kontext: ["{min_length} character(s) at least".format(min_length=2)] ergibt ["2 character(s) at least"]. Die Schreibweise [**dictionary] übergibt die Einträge des Dictionarys als benannte Parameter; [error.get("ctx", {})] gibt für einen Fehler ohne Kontext ein leeres Dictionary zurück.

Diese Technik (Übersetzen anhand des Fehlertyps) wird in der Fallstudie verwendet: Dort werden Meldungen durch Schlüssel identifiziert, die in die Sprache des Benutzers übersetzt werden.

3.3.2. Die Action: controllers/persons.py

# controllers/persons.py: die Action entscheidet, was bei einem ungültigen Modell zu tun ist
from flask import Blueprint, request
from markupsafe import escape
from pydantic import ValidationError

from models.messages import field, message_en
from models.person import PersonModel

persons = Blueprint("persons", __name__, url_prefix="/persons")


@persons.get("/action01")
def action01():
    try:
        person = PersonModel.model_validate(request.args.to_dict())
    except ValidationError as e:
        # die Fehler, Feld für Feld: e.errors() liefert ihre Liste
        items = "".join(f"<li>{field(error)}: {message_en(error)}</li>" for error in e.errors())
        return f"<p>The form contains errors:</p><ul>{items}</ul>"
    # escape: der eingegebene Name wird in HTML eingefügt; seine Zeichen < > & " '
    # werden durch &lt; &gt; ... ersetzt (andernfalls könnte eine Eingabe HTML einschleusen)
    return f"<p>Welcome {person.title} {escape(person.name)} ({person.age} years old)</p>"
  • Zeilen 14–19: Die Action selbst fängt die [ValidationError] in einem [try]/[except]-Block ab. Tritt ein Fehler auf, erzeugt sie eine HTML-Liste der Fehler ([<ul>], ein [<li>]-Tag pro Fehler);
  • Zeile 22: bei Erfolg eine Willkommensnachricht. Der Name wird durch die Funktion [escape] der Bibliothek [markupsafe] (installiert mit [Flask]) geleitet. [escape] ersetzt Zeichen, die in HTML eine Bedeutung haben ([<], [>], [&], ["], [']), durch ihre Entitäten ([&lt;], [&gt;] ...): Sie werden unverändert angezeigt, statt interpretiert zu werden. Ohne diese Vorsichtsmaßnahme könnte ein Benutzer einen „Namen“ eingeben, der HTML oder sogar [JavaScript] enthält und im Browser jedes Betrachters der Seite ausgeführt würde. Das ist die häufigste Sicherheitslücke im Web: die Skript-Injektion (*XSS*, *Cross-Site-Scripting*). Der Titel und das Alter benötigen diesen Schutz nicht: Ihre Werte wurden vom Modell validiert (einer von drei zulässigen Werten, eine Ganzzahl). Im nächsten Kapitel wird die [Jinja2]-View-Engine dieses Escaping automatisch für jeden in eine Seite eingefügten Wert übernehmen.

Eine gültige Eingabe, gefolgt von einer Eingabe mit vier Fehlern:

Image

Image

Die Rohantwort auf die zweite Anfrage und die Antwort für einen Namen, der HTML enthält:

curl "http://localhost:5000/persons/action01?name=m&age=abc&title=Mx&email=xx"
curl "http://localhost:5000/persons/action01?name=%3Cb%3Emartin%3C/b%3E&age=42&title=Mr"
<p>The form contains errors:</p><ul><li>name: 2 character(s) at least</li><li>age: an integer is expected</li><li>title: unknown value</li><li>email: invalid value</li></ul>
<p>Welcome Mr &lt;b&gt;martin&lt;/b&gt; (42 years old)</p>

Der Name [<b>martin</b>] (in der URL als [%3Cb%3E...] codiert) wird unverändert angezeigt, ohne fett dargestellt zu werden: Seine Tags wurden entschärft. Beachten Sie, dass die Antwort diesmal den Statuscode 200 hat: Die Action hat sich dafür entschieden, eine normale Seite zurückzugeben, die die Fehler enthält.

3.4. Beispiel 10: Mehrfache Parameter

Derselbe Parameter kann mehrfach in einer URL vorkommen: [?color=red&color=green]. Das sendet ein Browser für eine Gruppe von Kontrollkästchen mit demselben Namen oder für eine Mehrfachauswahlliste (siehe nächstes Kapitel). Die Datei [controllers/arrays.py]:

# controllers/arrays.py: ein Parameter, der mehrfach in der URL vorkommt
from flask import Blueprint, request
from pydantic import ValidationError

from models.choice import ChoiceModel
from models.messages import field, message_en

arrays = Blueprint("arrays", __name__, url_prefix="/arrays")


# /arrays/action01?color=red&color=green: get liefert nur den ERSTEN Wert
@arrays.get("/action01")
def action01():
    return {"color": request.args.get("color")}


# /arrays/action02?color=red&color=green: getlist liefert ALLE
# Werte in einer Liste (leer, wenn der Parameter fehlt)
@arrays.get("/action02")
def action02():
    colors = request.args.getlist("color")
    return {"color": colors, "count": len(colors)}


# /arrays/action03?color=red: eine Liste, von ChoiceModel validiert
@arrays.get("/action03")
def action03():
    colors = request.args.getlist("color")
    try:
        ChoiceModel(color=colors)
        errors = []
    except ValidationError as e:
        errors = [f"{field(error)}: {message_en(error)}" for error in e.errors()]
    return {"colors": colors, "valid": not errors, "errors": errors}
  • Zeile 14: [get] gibt nur den ersten Wert des Parameters zurück;
  • Zeile 21: [getlist] gibt alle seine Werte in einer Liste zurück, die leer ist, wenn der Parameter fehlt. Das ist das Besondere an [MultiDict]: Es behält die Liste der Werte für jeden Schlüssel;
  • Zeilen 27–34: Die Liste wird mit einem [Pydantic]-Modell validiert. Diesmal wird das Modell durch einen gewöhnlichen Aufruf erzeugt, [ChoiceModel(color=colors)], wobei die Felder als benannte Parameter übergeben werden: Das entspricht [model_validate] für ein Dictionary. Das erzeugte Objekt dient nur der Validierung: Es wird nicht aufbewahrt. Der Ausdruck [not errors] ist für eine leere Liste gleichbedeutend mit [True].

Das Modell [models/choice.py]:

# models/choice.py: eine Liste und eine Einschränkung für JEDES Element der Liste
from typing import Annotated, Literal

from pydantic import BaseModel, Field


class ChoiceModel(BaseModel):
    # list[Literal[...]]: jedes Element muss "red", "green" oder "blue" sein;
    # min_length=1: die Liste muss mindestens ein Element enthalten
    color: Annotated[list[Literal["red", "green", "blue"]], Field(min_length=1)]
  • Zeile 10: Der Typ [list[Literal["red", "green", "blue"]]] ist der einer Liste, in der jedes Element eine von drei Farben ist. Die Einschränkung [min_length=1], auf eine Liste angewendet, bezieht sich auf die Anzahl der Elemente: Es muss mindestens eines vorhanden sein.

Die Datei [models/messages.py] ist die aus Beispiel 09. Die Ergebnisse:

1
2
3
curl "http://localhost:5000/arrays/action01?color=red&color=green"
curl "http://localhost:5000/arrays/action02?color=red&color=green"
curl http://localhost:5000/arrays/action02
{
  "color": "red"
}
{
  "color": [
    "red",
    "green"
  ],
  "count": 2
}
{
  "color": [],
  "count": 0
}

Die Validierung war zunächst erfolgreich, schlug dann wegen einer unbekannten Farbe fehl und anschließend wegen einer leeren Liste:

1
2
3
curl "http://localhost:5000/arrays/action03?color=red&color=blue"
curl "http://localhost:5000/arrays/action03?color=red&color=yellow"
curl http://localhost:5000/arrays/action03
{
  "colors": [
    "red",
    "blue"
  ],
  "valid": true,
  "errors": []
}
{
  "colors": [
    "red",
    "yellow"
  ],
  "valid": false,
  "errors": [
    "color.1: unknown value"
  ]
}
{
  "colors": [],
  "valid": false,
  "errors": [
    "color: 1 item(s) at least"
  ]
}

Der Fehler „unknown value“ bezieht sich auf [color.1]: Das Fehlertupel [loc] ist [("color", 1)]; das Feld und der Index des problematischen Elements in der Liste (des zweiten, da die Indizes bei 0 beginnen).

3.5. Beispiel 11: Die Parameter einer POST-Anfrage

Die vorherigen Beispiele verwendeten GET-Anfragen, deren Parameter in der URL enthalten sind. Eine POST-Anfrage überträgt ihre Daten in ihrem Body, hauptsächlich in zwei Formen:

  • Felder eines HTML-Formulars: Der Body hat dieselbe Syntax wie ein Query-String ([name=martin&age=42]), und sein Typ (Header [Content-Type]) lautet [application/x-www-form-urlencoded];
  • ein JSON-Dokument, das von einem Programm gesendet wird ([JavaScript] auf einer Seite, Client einer API ...): Der Typ ist [application/json].

Die Datei [controllers/post.py]:

# controllers/post.py: die Parameter einer POST-Anfrage
from flask import Blueprint, request
from pydantic import ValidationError

from models.messages import field, message_en
from models.person import PersonModel

post = Blueprint("post", __name__, url_prefix="/post")


# die Felder eines HTML-Formulars (Rumpf application/x-www-form-urlencoded):
# request.form, ein "Multi"-Dictionary (MultiDict), wie request.args
@post.post("/action01")
def action01():
    return {
        "receivedType": request.content_type,
        # flat=False: jedes Feld -> die Liste seiner Werte
        "fields": request.form.to_dict(flat=False),
    }


# ein JSON-Rumpf: get_json deserialisiert ihn (Dictionary, Liste ...); ein Rumpf,
# der kein JSON ist -> Fehler 415 (nicht unterstützter Typ) oder 400 (fehlerhaftes JSON)
@post.post("/action02")
def action02():
    return {"receivedType": request.content_type, "body": request.get_json()}


# ein einzelnes Feld des Formulars
@post.post("/action03")
def action03():
    name = request.form.get("name")
    return f"name = [{name}]"


# die Felder des Formulars, von der Klasse PersonModel gebunden und validiert
@post.post("/action04")
def action04():
    try:
        person = PersonModel.model_validate(request.form.to_dict()).model_dump()
        errors = []
    except ValidationError as e:
        person = None
        errors = sorted(f"{field(error)}: {message_en(error)}" for error in e.errors())
    return {"person": person, "valid": not errors, "errors": errors}
  • Zeile 13: [post.post(...)]: Das erste [post] ist der Blueprint, das zweite die Methode, die eine Route für die HTTP-Methode POST deklariert (siehe Beispiel 02);
  • Zeile 16: [request.content_type] ist der Header [Content-Type] der Anfrage;
  • Zeile 18: [request.form] enthält die Felder eines per POST gesendeten Formulars. Wie [request.args] ist es ein [MultiDict]. [to_dict(flat=False)] erzeugt tatsächlich ein Dictionary, in dem jeder Wert die Liste der Werte des Feldes ist;
  • Zeile 26: [request.get_json()] deserialisiert einen JSON-Body: Der JSON-Text wird zu einem [Python]-Objekt (einem Dictionary für ein JSON-Objekt, einer Liste für ein JSON-Array ...). Wenn der Body nicht als JSON deklariert ist, löst [get_json] einen Fehler 415 aus (*Unsupported Media Type*); ist er es, aber der Text fehlerhaft, tritt ein Fehler 400 auf;
  • Zeile 32: ein Feld, interpretiert als URL-Parameter;
  • Zeilen 38–45: das [PersonModel]-Modell aus Beispiel 08, diesmal an die Formularfelder gebunden. Der Code ist derselbe wie bei den URL-Parametern: Nur die Quelle des Dictionarys ändert sich. [sorted] sortiert die Meldungen, um eine konsistente Antwort zu gewährleisten.

Mit [curl] sendet die Option [-d] (*data*) einen Body; die Anfrage wird dann zu einer POST-Anfrage vom Typ [application/x-www-form-urlencoded], es sei denn, die Option [-H] (*header*) gibt einen anderen Typ an. Die Option [-X POST] legt die Methode ausdrücklich fest (hier ist sie optional). Die Felder eines Formulars, einschließlich eines wiederholten Feldes:

curl -i -X POST -d "name=martin&age=42&hobby=tennis&hobby=piano" http://localhost:5000/post/action01
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 195

{
  "receivedType": "application/x-www-form-urlencoded",
  "fields": {
    "name": [
      "martin"
    ],
    "age": [
      "42"
    ],
    "hobby": [
      "tennis",
      "piano"
    ]
  }
}

Ein JSON-Body, der eine Ganzzahl und ein Array enthält:

curl -H "Content-Type: application/json" -d "{\"name\": \"martin\", \"age\": 42, \"children\": [\"léa\", \"tom\"]}" http://localhost:5000/post/action02
{
  "receivedType": "application/json",
  "body": {
    "name": "martin",
    "age": 42,
    "children": [
      "léa",
      "tom"
    ]
  }
}

Den Anführungszeichen in JSON wird ein [\] vorangestellt, damit die Befehlszeichenfolge nicht endet; unter [Linux] und [macOS] können Sie JSON auch in Apostrophe einschließen: [-d '{"name": "martin"}']. Anders als Formularfelder transportiert JSON Datentypen: Das Alter ist bereits eine Ganzzahl. Ein Body, der kein JSON ist, gefolgt von fehlerhaftem JSON:

curl -i -d "name=martin" http://localhost:5000/post/action02
curl -i -H "Content-Type: application/json" -d "{\"name\": " http://localhost:5000/post/action02
HTTP/1.1 415 UNSUPPORTED MEDIA TYPE
Content-Type: text/html; charset=utf-8
Content-Length: 215

<!doctype html>
<html lang=en>
<title>415 Unsupported Media Type</title>
<h1>Unsupported Media Type</h1>
<p>Did not attempt to load JSON data because the request Content-Type was not &#39;application/json&#39;.</p>
HTTP/1.1 400 BAD REQUEST
Content-Type: text/html; charset=utf-8
Content-Length: 163

<!doctype html>
<html lang=en>
<title>400 Bad Request</title>
<h1>Bad Request</h1>
<p>Failed to decode JSON object: Expecting value: line 1 column 10 (char 9)</p>

Ein einzelnes Feld, dann dieselbe URL als GET angefordert:

curl -d "name=jean%20dupont" http://localhost:5000/post/action03
curl -i "http://localhost:5000/post/action03?name=martin"
name = [jean dupont]
HTTP/1.1 405 METHOD NOT ALLOWED
Content-Type: text/html; charset=utf-8
Allow: POST, OPTIONS
Content-Length: 153

<!doctype html>
<html lang=en>
<title>405 Method Not Allowed</title>
<h1>Method Not Allowed</h1>
<p>The method is not allowed for the requested URL.</p>

Die URL existiert, aber nicht für die Methode GET: [Flask] liefert eine 405 (*Method Not Allowed*), und ihr Header [Allow] listet die akzeptierten Methoden auf ([OPTIONS] wird für jede Route automatisch von [Flask] behandelt). Schließlich das an die Formularfelder gebundene Modell, zuerst gültig, dann ungültig:

curl -d "name=martin&age=42&title=Mr" http://localhost:5000/post/action04
curl -d "name=m&age=200" http://localhost:5000/post/action04
{
  "person": {
    "name": "martin",
    "age": 42,
    "title": "Mr",
    "email": null
  },
  "valid": true,
  "errors": []
}
{
  "person": null,
  "valid": false,
  "errors": [
    "age: the value must be less than or equal to 150",
    "name: 2 character(s) at least",
    "title: the field is required"
  ]
}

3.6. Beispiel 12: Benutzerdefiniertes Binding und benutzerdefinierte Validierung

Standardtypen reichen nicht immer aus. Dieses Beispiel zeigt drei Möglichkeiten, Binding und Validierung zu erweitern:

  • ein Pfad-Converter: ein Datum im französischen Format, [23-09-2026], im Pfad der URL;
  • ein Dekorator , der der Action einen Parameter liefert, der nicht aus der URL, sondern aus einem HTTP-Header stammt;
  • „benutzerdefinierte“ Typen für [Pydantic]: eine Einschränkung (keine Leerzeichen) und eine Konvertierung (ein Datum im Format [dd/mm/yyyy]).
1
2
3
4
5
6
7
8
12-custom-binding/
├── app.py
├── binding/
│   ├── date_fr.py
│   ├── language.py
│   └── types.py
└── controllers/
    └── examples.py

3.6.1. Ein Pfad-Converter: binding/date_fr.py

In Beispiel 02 sind wir den [Werkzeug]-Convertern begegnet: [<int:id>] akzeptiert nur eine Ganzzahl und konvertiert sie. Sie können neue schreiben.

# binding/date_fr.py: ein französisches Datum "23-09-2026" im Pfad der URL
from datetime import date, datetime

from werkzeug.routing import BaseConverter, ValidationError


# ein Werkzeug-KONVERTER (die Bibliothek, auf der Flask aufbaut):
# er entscheidet, ob ein Pfadstück passt, und wandelt es in ein Python-Objekt um
class DateFrConverter(BaseConverter):
    # der reguläre Ausdruck des Pfadstücks: dd-mm-yyyy
    regex = r"\d{2}-\d{2}-\d{4}"

    # Text des Pfads -> date-Objekt
    def to_python(self, value: str) -> date:
        try:
            # strptime prüft, ob das Datum existiert: "31-02-2026" wird abgelehnt
            return datetime.strptime(value, "%d-%m-%Y").date()
        except ValueError:
            # die Route passt nicht: Flask sucht eine andere Route und antwortet dann mit 404
            raise ValidationError()

    # date-Objekt -> Text des Pfads (wird von url_for verwendet)
    def to_url(self, value: date) -> str:
        return value.strftime("%d-%m-%Y")
  • Zeile 9: Ein Converter ist eine Klasse, die von [BaseConverter] erbt;
  • Zeile 11: Das Attribut [regex] ist ein regulärer Ausdruck , der das Format des akzeptierten Pfadsegments beschreibt: [\d] steht für eine Ziffer, [{2}] für die Wiederholung des vorangehenden Elements – hier zwei Ziffern. Das Präfix [r] vor dem String (*raw string*) verhindert, dass [Python] [\] interpretiert. Das Routing versucht nur bei einem Pfadsegment dieser Form, diesen Converter zu verwenden;
  • Zeilen 14–20: [to_python] wandelt den Pfadtext in ein [Python]-Objekt um, hier in ein [date]. [datetime.strptime] (*string parse time*) parst einen String gemäß einem bestimmten Format: [%d] für den Tag, [%m] für den Monat und [%Y] für das vierstellige Jahr; [.date()] behält das Datum ohne die Uhrzeit. [strptime] prüft, ob das Datum existiert: [31-02-2026] hat das richtige Format, löst aber einen [ValueError] aus. Der Converter löst dann die [ValidationError]-Ausnahme von [Werkzeug] (nicht zu verwechseln mit der von [Pydantic]) aus: Für das Routing passt die Route nicht zur URL, was daher zu einem Fehler 404 führt, wenn keine andere Route passt;
  • Zeilen 23–24: die Umkehroperation, die von [url_for] verwendet wird, um aus einem Datum eine URL zu erstellen. [strftime] (*string format time*) formatiert ein Datum.

Der Converter wird in [app.py] registriert:

# app.py: die Anwendung von Beispiel 12
from flask import Flask

from controllers.examples import examples
from binding.date_fr import DateFrConverter


def create_app():
    app = Flask(__name__)
    # ein Konverter für Pfadvariablen unter dem Namen [datefr]: die Routen
    # können nun <datefr:day> schreiben, wie <int:id>
    app.url_map.converters["datefr"] = DateFrConverter
    app.register_blueprint(examples)
    return app


if __name__ == "__main__":
    create_app().run(port=5000, debug=True)
  • Zeile 12: [app.url_map] ist die Routing-Tabelle der Anwendung; ihr Dictionary [converters] ordnet jedem Converter einen Namen zu ([int], [path] ...). Wir fügen unseren dort unter dem Namen [datefr] hinzu. Der Eintrag muss vor denen der Blueprints stehen, die ihn verwenden.

3.6.2. Ein von einem Dekorator bereitgestellter Parameter: binding/language.py

Eine [Flask]-Action erhält die Pfadvariablen als Parameter und sonst nichts. Um ihr zusätzliche Informationen zu liefern, können wir die Action dekorieren: Der Dekorator ersetzt die Action durch eine Funktion, die die Information berechnet und dann die Action aufruft, indem sie ihr diese Information übergibt.

# binding/language.py: ein Dekorator, der der Action einen Parameter LIEFERT
from functools import wraps

from flask import request


# @with_language, auf einer Action platziert, übergibt ihr den Parameter [language], gelesen aus
# dem Header "Accept-Language: fr-FR,fr;q=0.9,en;q=0.8" -> "fr"
def with_language(action):
    # wraps: die erzeugte Funktion behält den Namen der Action (Flask verwendet ihn,
    # um die Route zu benennen)
    @wraps(action)
    def action_with_language(*args, **kwargs):
        # request.accept_languages: der Header, bereits von Werkzeug geparst;
        # best_match: die bevorzugte Sprache des Browsers unter den angebotenen
        kwargs["language"] = request.accept_languages.best_match(["fr", "en"], default="fr")
        return action(*args, **kwargs)

    return action_with_language
  • Zeile 9: Ein Dekorator ist eine Funktion, die eine Funktion (hier die Action) entgegennimmt und eine andere Funktion zurückgibt (siehe Beispiel 01). Die Schreibweise [@with_language] über [def hello(...)] ist gleichbedeutend damit, nach der Definition [hello = with_language(hello)] zu schreiben;
  • Zeile 13: Die Funktion, die die Action ersetzen wird. [*args] empfängt Positionsparameter in einem Tupel und [**kwargs] (*keyword arguments*) empfängt benannte Parameter in einem Dictionary. So übergibt [Flask] die Pfadvariablen ([id=3]): Die Funktion erhält sie, ohne sie kennen zu müssen;
  • Zeile 16: Ein benannter Parameter, [language], wird hinzugefügt. [request.accept_languages] ist der Anfrage-Header [Accept-Language], der bereits von [Werkzeug] geparst wurde. Der Browser gibt hier die Sprachen des Benutzers in der Reihenfolge ihrer Präferenz an: [fr-FR,fr;q=0.9,en;q=0.8] (der Koeffizient [q] misst die Präferenz auf einer Skala von 0 bis 1). [best_match] wählt unter den von der Anwendung angebotenen Sprachen diejenige aus, die der Benutzer bevorzugt, oder den Wert [default] , wenn keine passt;
  • Zeile 17: der Aufruf der ursprünglichen Action mit den empfangenen Parametern und dem neuen. Die Schreibweisen [*args] und [**kwargs] entpacken diesmal das Tupel und das Dictionary in Parameter;
  • Zeile 12: Die Funktion [action_with_language] übernimmt den Namen ([__name__]) und die Dokumentation der Action. Das ist hier unerlässlich: [Flask] benennt jede Route nach dem Namen ihrer Funktion (das [hello] von [url_for("examples.hello")]) und würde sich weigern, zwei Routen mit demselben Namen zu registrieren, [action_with_language], wenn zwei Actions den Dekorator verwendeten.

Diesen Ansatz werden wir im gesamten Kurs wiederfinden: Die Dekoratoren [@login_required] und [@role_required] im Kapitel über die Authentifizierung sind auf dieselbe Weise aufgebaut.

3.6.3. „Benutzerdefinierte“ Typen für Pydantic: binding/types.py

# binding/types.py: "selbstgebaute" Typen für die Pydantic-Modelle
from datetime import date, datetime
from typing import Annotated

from pydantic import AfterValidator, BeforeValidator


# eine "selbstgebaute" Einschränkung: der String darf kein Leerzeichen enthalten.
# Die Funktion erhält den Wert BEREITS in str umgewandelt; sie gibt ihn zurück oder löst
# einen ValueError aus, dessen Meldung zur Meldung des Validierungsfehlers wird
def no_space(value: str) -> str:
    if " " in value:
        raise ValueError("the field must not contain a space")
    return value


# Annotated: der Typ str, ergänzt um eine Prüfung, die NACH der
# Umwandlung ausgeführt wird. NoSpace wird dann wie ein gewöhnlicher Typ verwendet
NoSpace = Annotated[str, AfterValidator(no_space)]


# eine "selbstgebaute" Umwandlung: "23/09/2026" -> date(2026, 9, 23), ausgeführt VOR
# der Validierung des Typs date
def date_fr(value):
    if isinstance(value, str):
        try:
            return datetime.strptime(value, "%d/%m/%Y").date()
        except ValueError:
            raise ValueError(f"[{value}] is not a valid dd/mm/yyyy date")
    return value


DateFr = Annotated[date, BeforeValidator(date_fr)]
  • Zeilen 11–14: eine Validierungsfunktion: Sie nimmt den Wert des Feldes entgegen, gibt ihn zurück, wenn er gültig ist, und löst andernfalls einen [ValueError] aus. Die Meldung der Ausnahme wird zur Meldung des Validierungsfehlers;
  • Zeile 19: Der Typ [NoSpace] ist der Typ [str], annotiert mit [AfterValidator(no_space)]: [Pydantic] ruft die Funktion auf, nachdem der Wert geprüft (und gegebenenfalls) in [str] konvertiert wurde. So können wir einmal einen Typ definieren, der in allen Modellen wie ein gewöhnlicher Typ wiederverwendet werden kann;
  • Zeilen 24–30: eine Konvertierungsfunktion. Der Typ ***[date] von *[Pydantic] akzeptiert Strings im internationalen Format, ***[2026-09-23]; wir wollen das französische Format, ***[23/09/2026]. Die Funktion erhält den Rohwert: Ist er ein String, konvertiert sie ihn in [date]. Jeder andere Wert (zum Beispiel ein bereits erzeugtes [date]**) wird unverändert zurückgegeben;
  • Zeile 33: [BeforeValidator]: Die Funktion wird vor der Validierung des Typs [date] aufgerufen, der daher ein bereits erzeugtes [date] erhält.

3.6.4. Der Controller: controllers/examples.py

# controllers/examples.py: benutzerdefiniertes Binding und Validierung
from datetime import date

from flask import Blueprint, request, url_for
from pydantic import BaseModel, ValidationError

from binding.language import with_language
from binding.types import DateFr, NoSpace

examples = Blueprint("examples", __name__, url_prefix="/examples")


# /examples/schedule/23-09-2026: ein benutzerdefinierter Pfadkonverter (siehe app.py)
@examples.get("/schedule/<datefr:day>")
def schedule(day: date):
    # url_for verwendet die Methode to_url des Konverters: date -> "23-09-2026"
    return f"schedule for the day [{day}], of type {type(day).__name__}, " \
           f"URL: {url_for('examples.schedule', day=day)}"


# /examples/hello: ein Parameter, der nicht aus der URL stammt, sondern aus einem Header,
# geliefert vom Dekorator @with_language
@examples.get("/hello")
@with_language
def hello(language: str):
    return "Hello!" if language == "en" else "Bonjour !"


# das Modell der Suche: zwei "selbstgebaute" Typen
class SearchModel(BaseModel):
    keyword: NoSpace | None = None
    since: DateFr | None = None


# /examples/search?keyword=flask&since=01/09/2026
@examples.get("/search")
def search():
    model = SearchModel.model_validate(request.args.to_dict())
    return f"search for [{model.keyword}] since [{model.since}]"


# --------------------------------------------------------------- Fehler
# errorhandler eines BLUEPRINTS: wandelt eine von einer SEINER Actions ausgelöste Exception
# in eine Antwort um (derselbe Dekorator an der Anwendung gilt für alle)
@examples.errorhandler(ValidationError)
def validation(e: ValidationError):
    # die Meldung des ersten Fehlers, ohne das Präfix "Value error, " von Pydantic
    message = e.errors()[0]["msg"].removeprefix("Value error, ")
    return message, 400, {"Content-Type": "text/plain; charset=utf-8"}
  • Zeilen 14–18: Die Pfadvariable [day] verwendet den Converter [datefr]: Die Action erhält ein [date]. [url_for] erzeugt die URL für dieselbe Action anhand des Datums, und zwar mit der Methode [to_url] des Converters. Das Zeichen [\] am Zeilenende setzt die Anweisung in der nächsten Zeile fort; zwei aufeinanderfolgende Zeichenkettenliterale werden verkettet;
  • Zeilen 23–25: Die Reihenfolge der Dekoratoren ist wichtig. Sie werden von unten nach oben angewendet: [@with_language] wandelt zuerst die Action um, dann [@examples.get] registriert die umgewandelte Funktion im Blueprint. In umgekehrter Reihenfolge würde der Blueprint die ursprüngliche Action registrieren, und der Parameter [language] würde nie geliefert;
  • Zeilen 30–32: ein Modell, das die beiden „benutzerdefinierten“ Typen wie gewöhnliche Typen verwendet. Beide Felder sind optional;
  • Zeilen 45–49: ein Exception-Handler, diesmal auf dem Blueprint deklariert: Er behandelt nur Ausnahmen, die von den Actions dieses Blueprints ausgelöst werden. [removeprefix] entfernt das Präfix ["Value error, "] aus der Meldung, das [Pydantic] den Meldungen von [ValueError] voranstellt. Die Antwort ist ein Tupel aus drei Elementen: dem Body, dem Code und einem Dictionary mit Headern (siehe Beispiel 03), hier für eine Antwort im Klartext.

3.6.5. Ausführung

Der Pfad-Converter:

curl "http://localhost:5000/examples/schedule/23-09-2026"
curl -i "http://localhost:5000/examples/schedule/31-02-2026"
1
2
3
4
5
schedule for the day [2026-09-23], of type date, URL: /examples/schedule/23-09-2026
HTTP/1.1 404 NOT FOUND
Content-Type: text/html; charset=utf-8
Content-Length: 207
...

Das Datum wird von [Python] im internationalen Format angezeigt (das ist das Ergebnis der Umwandlung eines [date] in einen String), aber die von [url_for] erzeugte URL hat wieder das französische Format. Den 31. Februar gibt es nicht: 404. Ein Datum im internationalen Format, [2026-09-23], passt nicht zu dem vom regulären Ausdruck beschriebenen Muster: ebenfalls 404.

Der Dekorator. Die Option [-H] von [curl] setzt den Header [Accept-Language]:

1
2
3
curl -H "Accept-Language: en-US,en;q=0.9,fr;q=0.8" http://localhost:5000/examples/hello
curl -H "Accept-Language: fr-FR,fr;q=0.9" http://localhost:5000/examples/hello
curl http://localhost:5000/examples/hello
1
2
3
Hello!
Bonjour !
Bonjour !

Ohne Header [Accept-Language] ([curl] sendet keinen) gilt die Standardsprache. Das Kapitel über die Internationalisierung greift diese Frage wieder auf, wobei der Benutzer die Sprache auswählt.

„Benutzerdefinierte“ Typen:

1
2
3
4
5
curl "http://localhost:5000/examples/search?keyword=flask&since=01/09/2026"
curl "http://localhost:5000/examples/search"
curl -i "http://localhost:5000/examples/search?keyword=flask%20mvc"
curl "http://localhost:5000/examples/search?since=2026-09-01"
curl "http://localhost:5000/examples/search?since=31/02/2026"
1
2
3
4
5
6
7
8
9
search for [flask] since [2026-09-01]
search for [None] since [None]
HTTP/1.1 400 BAD REQUEST
Content-Type: text/plain; charset=utf-8
Content-Length: 34

the field must not contain a space
[2026-09-01] is not a valid dd/mm/yyyy date
[31/02/2026] is not a valid dd/mm/yyyy date

3.6.6. Fazit

Fassen wir die Methoden zusammen, die einer Action zur Verfügung stehen, um ihr Modell zu erhalten:

Quelle
Methode
Pfadvariablen
die Parameter der Action, typisiert durch die Converter ([<int:id>], [<datefr:day>])
URL-Parameter
[request.args]: [get] (zusammen mit [type] und [default]), [getlist], [to_dict]
Felder eines POST-Formulars
[request.form], ein [MultiDict], und ein [request.args]
JSON-Body
[request.get_json()]
Header
[request.headers] und bereits analysierte Objekte wie [request.accept_languages]
Konvertierung und Validierung
ein [Pydantic]-Modell: [model_validate], [ValidationError], [e.errors()]
Allgemeine Fehler
[@app.errorhandler] (gesamte Anwendung) oder [@blueprint.errorhandler] (ein Blueprint)
Berechneter Parameter
Ein Dekorator, der der Action einen benannten Parameter hinzufügt

HTML-Formulare erfordern dagegen mehr als nur Validierung: Sie müssen angezeigt, mit den Eingaben des Benutzers und etwaigen Fehlern erneut angezeigt und gegen gefälschte Anfragen geschützt werden. Das wird die Aufgabe von [WTForms] sein, das im nächsten Kapitel behandelt wird, nachdem die Views eingeführt wurden.