Skip to content

9. Schichtenarchitektur und Datenzugriff

Die bisherigen Beispiele hielten ihre Daten im Arbeitsspeicher. Eine reale Anwendung speichert sie in einer Datenbank und ist in Schichten organisiert (siehe das Diagramm in der Einführung):

  • die Web-Schicht (Controller, Views): liest die Anfrage, ruft die Geschäftsschicht auf und wählt die View aus;
  • die Geschäftsschicht: Geschäftsregeln;
  • die DAO-Schicht (*Data Access Object*): Datenbankabfragen.

Jede Schicht kennt nur die darunterliegende Schicht und deren Details so wenig wie möglich: Die Web-Schicht weiß nichts von SQL, und die Geschäftsschicht weiß nichts von HTML. Diese Trennung macht jede Schicht leichter verständlich, testbar und weiterentwickelbar. Beispiel 28 wendet dies auf die Verwaltung einer Personenliste an: Es ist, in kleinerem Maßstab, die Verwaltung der Ärzte und Clients aus der Fallstudie.

In [Python] ist der Datenbankzugriff auf mehrere Schichten verteilt:

  • Der DB-API-Standard (PEP 249) definiert die gemeinsame Schnittstelle für Datenbank-Treiber: eine Verbindung öffnen, einen SQL-Befehl ausführen und Zeilen lesen. Für [MySQL] (und [MariaDB]) verwenden wir [PyMySQL], einen Treiber, der vollständig in [Python] geschrieben ist und sich ohne Compiler installieren lässt;
  • [SQLAlchemy] ist die am weitesten verbreitete Datenzugriffsbibliothek in [Python]. Sie hat zwei Ebenen. Ihr Kern (*Core*) verwaltet die Verbindungen (darunter einen Verbindungspool, der einige Verbindungen offen hält und sie an Abfragen verleiht, da das Öffnen einer Verbindung aufwendig ist) und erstellt SQL-Anweisungen aus [Python]-Ausdrücken, unabhängig vom DBMS. Ihr ORM (*Object-Relational Mapper*) bildet [Python]-Klassen (die Entitäten) auf Datenbanktabellen ab und wandelt die gelesenen Zeilen in Objekte um.

Dies entspricht [JDBC], [JPA] und [Hibernate] bei [Java] oder [Entity Framework Core] bei [C#]. Die Erweiterung [Flask-SQLAlchemy] vereinfacht die Konfiguration von [SQLAlchemy] in einer [Flask]-Anwendung geringfügig; wir verwenden [SQLAlchemy] direkt, was zeigt, was geschieht, und die Geschäftsschichten und das DAO unabhängig von [Flask] hält.

Das Beispiel erfordert einen laufenden [MySQL]- (oder [MariaDB]-)Server: Der Anhang erklärt, wie Sie einen mit [Laragon] installieren.

9.1. Beispiel 28: Eine dreischichtige Personalverwaltung

28-layers/
├── app.py
├── business/
│   ├── data.py
│   ├── exception.py
│   └── persons_business.py
├── config.py
├── controllers/
│   └── persons.py
├── dao/
│   └── persons_dao.py
├── database/
│   └── dbpersons.sql
├── entities/
│   └── person.py
├── models/
│   └── person_form.py
├── static/
│   ├── css/
│   │   └── styles.css
│   └── js/
│       └── app.js
└── templates/
    ├── fragments/
    │   ├── confirmation.html
    │   └── field.html
    ├── layout.html
    └── persons/
        ├── form.html
        └── list.html

9.1.1. Die Datenbank

Die Datenbank [dbpersons] wird durch das SQL-Skript erstellt. Mit [Laragon] können Sie es zum Beispiel im Werkzeug [HeidiSQL] ausführen (Menü Datei / SQL-Datei ausführen) oder über die Befehlszeile, aus dem Beispielordner heraus:

mysql -u root < database/dbpersons.sql

Die Datei [database/dbpersons.sql]:

-- Datenbank von Beispiel 28: eine einzige Tabelle, [persons]
-- Das Skript ist in UTF-8 geschrieben
SET NAMES utf8mb4;
DROP DATABASE IF EXISTS dbpersons;
CREATE DATABASE dbpersons CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
USE dbpersons;

CREATE TABLE persons (
  id INT NOT NULL AUTO_INCREMENT,
  -- die Version der Zeile, von SQLAlchemy bei jeder Änderung erhöht
  version INT NOT NULL DEFAULT 0,
  first_name VARCHAR(30) NOT NULL,
  last_name VARCHAR(30) NOT NULL,
  age INT NOT NULL,
  PRIMARY KEY (id),
  -- zwei Personen dürfen nicht denselben Vor- und Nachnamen haben
  CONSTRAINT unq_persons_first_name_last_name UNIQUE (first_name, last_name)
) ENGINE = InnoDB;

INSERT INTO persons (first_name, last_name, age) VALUES
  ('Marie', 'Pélissier', 42),
  ('Jacques', 'Bromard', 35),
  ('Philippe', 'Jandot', 58);
  • Zeile 3: Das Skript ist in [UTF-8] geschrieben; dies wird dem Server mitgeteilt, damit Akzente in den Daten ([Pélissier]) erhalten bleiben;
  • Zeile 5: Der Zeichensatz [utf8mb4] akzeptiert alle Zeichen (Akzente, Emojis usw.). Die Kollation [utf8mb4_unicode_ci] vergleicht Zeichenketten, ohne Groß- und Kleinbuchstaben oder Akzente zu unterscheiden: Für [MySQL] sind [pelissier] und [Pélissier] gleich;
  • Zeile 11: eine Versionsnummer, die bei jeder Änderung der Zeile erhöht wird (siehe „optimistisches Sperren“ weiter unten);
  • Zeile 17: eine benannte Eindeutigkeitsbedingung: Die Datenbank lässt nicht zu, dass zwei Personen denselben Vor- und Nachnamen haben. Der Name dient dazu, den Fehler zu identifizieren.

9.1.2. Die Konfiguration

# config.py: die Konfiguration der Anwendung (siehe Beispiel 25)

# der geheime Schlüssel: er signiert die Session (Flash-Meldungen) und die Anti-CSRF-Tokens
SECRET_KEY = "a-secret-key-for-example-28"

# die Fehlermeldungen von WTForms werden von WTForms selbst übersetzt (siehe Beispiel 19)
WTF_I18N_ENABLED = False

# die Verbindung zur Datenbank: eine SQLAlchemy-URL.
#   mysql+pymysql: das DBMS MySQL, über den Treiber PyMySQL
#   root:        : der Benutzer root, ohne Passwort (das von Laragon);
#                  mit einem Passwort: root:myPassword@...
#   localhost:3306/dbpersons: der Server, sein Port, die Datenbank
#   charset=utf8mb4: der Austausch mit der Datenbank erfolgt in UTF-8
DATABASE_URL = "mysql+pymysql://root:@localhost:3306/dbpersons?charset=utf8mb4"

# True: die an die Datenbank gesendeten SQL-Anweisungen werden in der Konsole angezeigt
SQL_ECHO = False
  • Zeile 15: [SQLAlchemy] bezieht sich auf eine Datenbank, die durch eine URL identifiziert wird. [mysql+pymysql]: der SQL-Dialekt ([MySQL]) und der Treiber ([PyMySQL]); dann der Benutzer und sein Passwort (hier [root]; ohne Passwort ist das die Konfiguration von [Laragon]), der Server, sein Port und die Datenbank; schließlich die Parameter: [charset=utf8mb4] aktiviert die Kommunikation zwischen Treiber und Server in [UTF-8]. Wenn Ihr Server ein Passwort hat, ändern Sie diese Zeile oder setzen Sie die Umgebungsvariable [FLASK_DATABASE_URL] (Beispiel 25);
  • Zeile 18: Bei [True] zeigt [SQLAlchemy] in der Konsole jeden an die Datenbank gesendeten SQL-Befehl an. Das ist sehr aufschlussreich, und wir werden es später nutzen.
# app.py: die Anwendung von Beispiel 28; der Zusammenbau der drei Schichten
from pathlib import Path

from flask import Blueprint, Flask
from flask_wtf.csrf import CSRFProtect
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker

from controllers.persons import persons
from dao.persons_dao import PersonsDao
from business.persons_business import PersonsBusiness

BOOTSTRAP = Path(__file__).resolve().parent.parent / "common" / "bootstrap"


def create_app():
    app = Flask(__name__)
    app.jinja_env.trim_blocks = True
    app.jinja_env.lstrip_blocks = True
    app.config.from_pyfile("config.py")
    app.config.from_prefixed_env()

    # der Zugriff auf die Datenbank: die SQLAlchemy-"Engine" verwaltet einen POOL von Verbindungen
    # (einmal geöffnete Verbindungen, die dann von einer Anfrage zur nächsten wiederverwendet werden).
    # pool_pre_ping: eine Verbindung wird vor der Wiederverwendung getestet
    engine = create_engine(app.config["DATABASE_URL"], echo=app.config["SQL_ECHO"],
                           pool_pre_ping=True)
    # die Session-Factory; expire_on_commit=False: die gelesenen Objekte bleiben
    # nach dem Ende der Transaktion verwendbar (insbesondere durch die View)
    sessions = sessionmaker(engine, expire_on_commit=False)

    # der Zusammenbau der Schichten: DAO -> Geschäftsschicht; die Web-Schicht kennt nur die Geschäftsschicht
    app.extensions["business"] = PersonsBusiness(sessions, PersonsDao())

    app.register_blueprint(Blueprint("bootstrap", __name__, static_folder=BOOTSTRAP,
                                     static_url_path="/bootstrap"))
    app.register_blueprint(persons)
    CSRFProtect(app)
    return app


if __name__ == "__main__":
    create_app().run(port=5000, debug=True)
  • Zeilen 26–27: Die *Engine* von [SQLAlchemy] ist das Objekt, das die Verbindungen zu einer Datenbank und den Verbindungspool verwaltet. Sie wird einmal beim Start erstellt; die erste Verbindung wird erst bei der ersten Anfrage geöffnet. [pool_pre_ping=True] prüft eine Verbindung aus dem Pool, bevor sie wiederverwendet wird: Ein [MySQL]-Server schließt Verbindungen, die zu lange inaktiv waren, und die Anwendung würde sonst einen Fehler erhalten;
  • Zeile 30: Eine Session vom Typ ORM ist das Objekt, mit dem Entitäten gelesen und geschrieben werden; sie leiht sich eine Verbindung aus dem Pool und verfolgt die gelesenen Entitäten, um Änderungen daran zu erkennen. [sessionmaker] erstellt eine Session-Factory, deren jeder Aufruf eine Session erzeugt. Standardmäßig lässt die Session die Entitäten am Ende einer Transaktion „verfallen“ (sie vergisst ihre Werte, um sie bei der nächsten Verwendung erneut zu lesen). [expire_on_commit=False] verhindert dies: Die von der Geschäftsschicht zurückgegebenen Entitäten bleiben nach der Transaktion für die View, die sie anzeigt, nutzbar;
  • Zeile 33: das Zusammensetzen der Schichten: Die Geschäftsschicht erhält die Session-Factory und die DAO-Schicht. Die Web-Schicht kennt nur die Geschäftsschicht;
  • Zeile 38: Anti-CSRF-Schutz für die gesamte Anwendung (Beispiel 21).

9.1.3. Die Entität Person

# entities/person.py: eine Zeile der Tabelle [persons]
from sqlalchemy import String
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column


# die Elternklasse aller Entitäten: SQLAlchemy erfasst darin das
# Mapping Klasse <-> Tabelle jeder ihrer Kindklassen
class Base(DeclarativeBase):
    pass


class Person(Base):
    # der Name der Tabelle
    __tablename__ = "persons"

    # der Primärschlüssel, von der Datenbank erzeugt (AUTO_INCREMENT); SQLAlchemy liest
    # seinen Wert nach jedem INSERT zurück. Mapped[int]: der Python-Typ der Spalte
    id: Mapped[int] = mapped_column(primary_key=True)
    # das optimistische Sperren: siehe __mapper_args__ weiter unten
    version: Mapped[int] = mapped_column()
    first_name: Mapped[str] = mapped_column(String(30))
    last_name: Mapped[str] = mapped_column(String(30))
    age: Mapped[int]

    # version_id_col: SQLAlchemy erhöht die Version bei jedem UPDATE und fügt
    # die Bedingung "AND version = <gelesener Wert>" hinzu
    __mapper_args__ = {"version_id_col": version}

    def __init__(self, first_name: str, last_name: str, age: int):
        self.first_name = first_name
        self.last_name = last_name
        self.age = age
  • Zeilen 8–9: Alle Entitäten einer Anwendung erben von derselben Basisklasse, die von [DeclarativeBase] abgeleitet ist. [SQLAlchemy] speichert die Beschreibung jeder Entität (ihre Tabelle, ihre Spalten) in dieser Klasse: Das ist das deklarative Modell;
  • Zeile 14: die der Klasse zugeordnete Tabelle;
  • Zeile 18: Eine Spalte wird durch ein Attribut deklariert, das mit [Mapped[type]] annotiert ist: dem Typ der Spalte, [Python]. [mapped_column] legt ihre Eigenschaften fest: hier den Primärschlüssel. Standardmäßig wird ein ganzzahliger Primärschlüssel von der Datenbank erzeugt ([AUTO_INCREMENT]): [SQLAlchemy] liest seinen Wert nach jedem [INSERT] erneut aus;
  • Zeilen 21–23: [String(30)] legt die Länge der Spalte fest (nützlich, falls [SQLAlchemy] die Tabelle selbst erstellen sollte). Eine Spalte ohne besondere Eigenschaften kann einfach die Annotation verwenden ([age]). Der Typ [Mapped[str]] macht die Spalte zur Pflichtangabe ([NOT NULL]); [Mapped[str | None]] würde sie optional machen;
  • Zeile 27: [version_id_col] bezeichnet die Versionsspalte: [SQLAlchemy] erhöht sie bei jedem [UPDATE] und fügt diesem die Bedingung [AND version = <value read>] hinzu. Hat eine andere Abfrage die Zeile in der Zwischenzeit geändert, hat sich ihre Version geändert; [UPDATE] ändert dann keine Zeile, und [SQLAlchemy] löst eine [StaleDataError]-Ausnahme aus. Dies ist ein optimistisches Sperren: Nichts wird blockiert, aber gleichzeitige Änderungen werden erkannt;
  • Zeilen 29–32: ein Konstruktor, um eine Person in einer einzigen Zeile zu erstellen.

9.1.4. Die DAO-Schicht

# dao/persons_dao.py: die DAO-Schicht, Abfragen, keine Geschäftsregel.
# Jede Methode erhält die SQLAlchemy-SESSION, die von der Geschäfts-
# schicht geöffnet wurde: alle Abfragen derselben Operation teilen sich so dieselbe
# Verbindung und dieselbe Transaktion
from sqlalchemy import delete, select
from sqlalchemy.orm import Session

from entities.person import Person


class PersonsDao:

    # SELECT ... FROM persons ORDER BY last_name, first_name
    def list(self, session: Session) -> list[Person]:
        return list(session.scalars(select(Person).order_by(Person.last_name, Person.first_name)))

    # SELECT ... WHERE id = ?; None, wenn die Person nicht existiert
    def read(self, session: Session, id: int) -> Person | None:
        return session.get(Person, id)

    # eine Person mit demselben Vor- und Nachnamen, außer [except_id]:
    # SELECT ... WHERE first_name = ? AND last_name = ? AND id <> ? LIMIT 1
    def namesake(self, session: Session, first_name: str, last_name: str, except_id: int = 0) -> Person | None:
        query = select(Person).where(Person.first_name == first_name, Person.last_name == last_name,
                                     Person.id != except_id).limit(1)
        return session.scalars(query).first()

    # INSERT (neue Person): die Person wird der Session hinzugefügt, und
    # flush sendet die SQL-Anweisung SOFORT (und nicht erst beim COMMIT)
    def add(self, session: Session, person: Person) -> Person:
        session.add(person)
        session.flush()
        return person

    # DELETE FROM persons WHERE id = ?
    def delete(self, session: Session, id: int):
        session.execute(delete(Person).where(Person.id == id))

Die DAO-Schicht enthält nur Abfragen, keine Geschäftsregeln. Jede Methode erhält die von der Geschäftsschicht geöffnete Session: Alle Abfragen einer einzelnen Geschäftsoperation teilen sich so dieselbe Verbindung und dieselbe Transaktion.

  • Zeile 15: [select(Person)] erstellt eine Abfrage ([SELECT]) auf die Tabelle „persons“; [order_by] sortiert sie. Die Spalten werden als Attribute der Klasse geschrieben ([Person.last_name]): Der Editor kann ihre Namen prüfen, und es wird kein SQL von Hand geschrieben. [session.scalars(...)] führt die Abfrage aus und gibt die aus den gelesenen Zeilen erstellten Entitäten zurück;
  • Zeile 19: Lesen über den Primärschlüssel, oder [None];
  • Zeilen 23–26: [where] fügt Bedingungen hinzu, die mit den Operatoren von [Python] ([==], [!=]) geschrieben werden: [SQLAlchemy] übersetzt sie in SQL, mit Parametern (die Werte werden nie in den Text des SQL-Befehls kopiert, wodurch SQL-Injection unmöglich ist). [first()] gibt die erste Entität zurück, oder [None];
  • Zeilen 30–33: [session.add] übergibt eine neue Entität an die Session; [flush] sendet sofort [INSERT] an die Datenbank (ohne [flush] geschähe dies erst beim [COMMIT]). Die Datenbank erzeugt dann die ID, die [SQLAlchemy] in der Entität ablegt;
  • Zeile 37: ein [DELETE], auf dieselbe Weise erstellt.

9.1.5. Die Geschäftsschicht

1
2
3
4
5
6
7
8
9
# business/data.py: die Daten einer Person, so wie die Web-Schicht sie weitergibt
from dataclasses import dataclass


@dataclass(frozen=True)
class PersonData:
    first_name: str
    last_name: str
    age: int

Die Daten einer Person, wie sie von der Web-Schicht an die Geschäftsschicht übergeben werden: ein einfaches Objekt, unabhängig von [Flask], [WTForms] oder [SQLAlchemy].

1
2
3
4
# business/exception.py: eine Geschäftsregel lehnt die Operation ab; die Meldung
# ist für den Benutzer bestimmt
class BusinessException(Exception):
    pass

Eine Ausnahmeklasse speziell für die Geschäftsschicht: Eine Geschäftsregel lehnt die Operation ab, und die Meldung der Ausnahme ist für den Benutzer bestimmt.

# business/persons_business.py: die GESCHÄFTSSCHICHT, die Geschäftsregeln und nur sie.
# Jede Methode öffnet ihre TRANSAKTION: am Ende des with-Blocks bestätigt (COMMIT),
# abgebrochen (ROLLBACK), wenn eine Exception aus ihm herauskommt
from sqlalchemy.exc import IntegrityError
from sqlalchemy.orm import sessionmaker
from sqlalchemy.orm.exc import StaleDataError

from dao.persons_dao import PersonsDao
from entities.person import Person
from business.data import PersonData
from business.exception import BusinessException

NAMESAKE = "A person already has these first and last names."
MODIFIED = "This record has been modified meanwhile: reload it."
UNKNOWN = "This person does not exist (anymore)."


class PersonsBusiness:

    # sessions: die SQLAlchemy-Session-"Factory" (siehe app.py)
    def __init__(self, sessions: sessionmaker, dao: PersonsDao):
        self._sessions = sessions
        self._dao = dao

    def list(self) -> list[Person]:
        # sessions.begin(): eine Session UND ihre Transaktion; der with-Block schließt sie
        with self._sessions.begin() as session:
            return self._dao.list(session)

    def read(self, id: int) -> Person:
        with self._sessions.begin() as session:
            return self._read(session, id)

    def add(self, data: PersonData) -> Person:
        try:
            with self._sessions.begin() as session:
                # Regel 1: keine zwei Personen mit demselben Vor- und Nachnamen
                if self._dao.namesake(session, data.first_name, data.last_name):
                    raise BusinessException(NAMESAKE)
                return self._dao.add(session, Person(data.first_name, data.last_name, data.age))
        except IntegrityError as e:
            raise self._translate(e)

    def edit(self, id: int, version: int | None, data: PersonData) -> Person:
        try:
            with self._sessions.begin() as session:
                person = self._read(session, id)
                # Regel 2: wir ändern keinen Datensatz, der in der Zwischenzeit von jemand anderem geändert wurde
                if person.version != version:
                    raise BusinessException(MODIFIED)
                if self._dao.namesake(session, data.first_name, data.last_name, id):
                    raise BusinessException(NAMESAKE)
                # die gelesene Entität wird von der Session "verfolgt": es genügt, sie zu
                # ändern; flush sendet das UPDATE sofort
                person.first_name = data.first_name
                person.last_name = data.last_name
                person.age = data.age
                session.flush()
                return person
        except StaleDataError:
            # das UPDATE "WHERE id = ... AND version = ..." hat keine Zeile geändert
            raise BusinessException(MODIFIED)
        except IntegrityError as e:
            raise self._translate(e)

    def delete(self, id: int) -> Person:
        with self._sessions.begin() as session:
            person = self._read(session, id)
            self._dao.delete(session, id)
            return person

    def _read(self, session, id: int) -> Person:
        person = self._dao.read(session, id)
        if person is None:
            raise BusinessException(UNKNOWN)
        return person

    # zwei gleichzeitige Hinzufügungen: die Eindeutigkeitsbedingung der Datenbank hat die
    # zweite abgelehnt; e.orig: der ursprüngliche Fehler, der des Treibers PyMySQL
    @staticmethod
    def _translate(e: IntegrityError) -> Exception:
        if "unq_persons_first_name_last_name" in str(e.orig):
            return BusinessException(NAMESAKE)
        return e
  • Zeile 27: Jede Methode öffnet ihre eigene Session und Transaktion: [sessions.begin()] gibt eine Session mit gestarteter Transaktion zurück. Am Ende des [with]-Blocks wird die Transaktion bestätigt ([COMMIT]) und die Session geschlossen; tritt innerhalb des Blocks eine Ausnahme auf, wird die Transaktion zurückgerollt ([ROLLBACK]): Keine der im Block vorgenommenen Änderungen bleibt erhalten. Die Geschäftsschicht legt somit den Umfang der Transaktionen fest: Eine Geschäftsoperation entspricht einer Transaktion;
  • Zeilen 34–42: Regel Nr. 1: Keine zwei Personen dürfen denselben Vor- und Nachnamen haben. Die Geschäftsschicht prüft diese Regel vor dem Schreiben in die Datenbank und löst eine [BusinessException] aus, wenn sie nicht erfüllt ist. Diese Prüfung reicht jedoch nicht aus: Zwei gleichzeitige Anfragen könnten beide feststellen, dass es keine Namensvetter gibt, und dann beide mit dem Einfügen fortfahren. Die Eindeutigkeitsbedingung der Datenbank weist dann das zweite [INSERT] zurück, und [SQLAlchemy] löst eine [IntegrityError]-Ausnahme aus, die die Methode [_translate] in dieselbe [BusinessException] umwandelt. Die Datenbank ist die letzte Verteidigungslinie;
  • Zeilen 44–64: Regel Nr. 2: Ändern Sie keinen Datensatz, der in der Zwischenzeit von jemand anderem geändert wurde. Das Änderungsformular trägt die Version des gelesenen Datensatzes (in einem versteckten Feld); weicht sie von der aktuellen Version ab, wurde der Datensatz seit seiner Anzeige geändert. Auch hier erkennt die Datenbank (über das optimistische Sperren) den Fall, dass eine gleichzeitige Änderung zwischen dem Lesen und dem [UPDATE] erfolgt: Das ist die [StaleDataError]-Ausnahme. Beachten Sie, dass die Änderung einfach durch Ändern der Attribute der gelesenen Entität erfolgt: Die Session verfolgt dies, und [flush] sendet ein [UPDATE] , das nur die geänderten Spalten enthält;
  • Zeilen 66–70: Das Löschen einer Person führt zur Bestätigungsmeldung;
  • Zeilen 72–76: Eine nicht vorhandene Person ist ein Geschäftsfehler;
  • Zeilen 80–84: Eine statische Methode nimmt weder ein Objekt noch eine Klasse entgegen; sie ist einfach eine innerhalb der Klasse definierte Funktion. [e.orig] ist die ursprüngliche Ausnahme, die des Treibers [PyMySQL], deren Meldung den Namen der verletzten Bedingung enthält. Ein anderer Integritätsfehler wird unverändert weitergemeldet: Das ist kein Geschäftsfehler, sondern ein Programmierfehler.

9.1.6. Die Web-Schicht

# models/person_form.py: die Felder des Formulars und ihre Einschränkungen (siehe Beispiel 19)
from flask_wtf import FlaskForm
from wtforms import HiddenField, IntegerField, StringField
from wtforms.validators import DataRequired, InputRequired, Length, NumberRange, Optional


def clean(value):
    return value.strip() if isinstance(value, str) else value


# eine Version: eine Ganzzahl oder None, wenn das Feld leer ist (Formular zum Hinzufügen)
def integer_or_none(value):
    return int(value) if value not in (None, "") else None


class PersonForm(FlaskForm):

    class Meta:
        locales = ["en"]

    first_name = StringField("First name", filters=[clean], validators=[
        DataRequired("The first name is required."), Length(max=30, message="30 characters at most.")])
    last_name = StringField("Last name", filters=[clean], validators=[
        DataRequired("The last name is required."), Length(max=30, message="30 characters at most.")])
    age = IntegerField("Age", validators=[
        InputRequired("The age is required."),
        NumberRange(min=0, max=150, message="The age must be between 0 and 150.")])
    # die Version des Datensatzes, von einem versteckten Feld getragen (nur beim Bearbeiten)
    version = HiddenField(filters=[integer_or_none])

Das Formular [WTForms] (Beispiel 19). Das versteckte Feld [version] hat einen Filter, der es in eine ganze Zahl umwandelt, oder in [None] , wenn es leer ist (Formular zum Hinzufügen).

# controllers/persons.py: die WEB-Schicht; sie kennt nur die Geschäftsschicht
from flask import Blueprint, current_app, flash, redirect, render_template, url_for

from business.data import PersonData
from business.exception import BusinessException
from business.persons_business import PersonsBusiness
from models.person_form import PersonForm

persons = Blueprint("persons", __name__)


def business() -> PersonsBusiness:
    return current_app.extensions["business"]


@persons.get("/")
def home():
    return redirect(url_for("persons.list_persons"))


@persons.get("/persons")
def list_persons():
    return render_template("persons/list.html", persons=business().list())


@persons.get("/persons/add")
def add_form():
    return form_page("Add a person", url_for("persons.add"), PersonForm())


@persons.post("/persons/add")
def add():
    form = PersonForm()
    if not form.validate():
        return form_page("Add a person", url_for("persons.add"), form)
    try:
        p = business().add(PersonData(form.first_name.data, form.last_name.data, form.age.data))
    except BusinessException as e:
        # eine Geschäftsregel lehnt ab: wir zeigen das Formular erneut an, die Meldung am Seitenende
        return form_page("Add a person", url_for("persons.add"), form, str(e))
    flash(f"{p.first_name} {p.last_name} has been added.", "success")
    return redirect(url_for("persons.list_persons"))


@persons.get("/persons/<int:id>/edit")
def edit_form(id):
    try:
        p = business().read(id)
    except BusinessException as e:
        flash(str(e), "error")
        return redirect(url_for("persons.list_persons"))
    # obj=p: die Felder des Formulars werden mit den gleichnamigen Attributen von p gefüllt
    return form_page("Edit a person", url_for("persons.edit", id=id),
                     PersonForm(obj=p))


@persons.post("/persons/<int:id>/edit")
def edit(id):
    action = url_for("persons.edit", id=id)
    form = PersonForm()
    if not form.validate():
        return form_page("Edit a person", action, form)
    try:
        data = PersonData(form.first_name.data, form.last_name.data, form.age.data)
        p = business().edit(id, form.version.data, data)
    except BusinessException as e:
        return form_page("Edit a person", action, form, str(e))
    flash(f"{p.first_name} {p.last_name} has been edited.", "success")
    return redirect(url_for("persons.list_persons"))


@persons.post("/persons/<int:id>/delete")
def delete(id):
    try:
        p = business().delete(id)
        flash(f"{p.first_name} {p.last_name} has been deleted.", "success")
    except BusinessException as e:
        # kein Formular, das erneut anzuzeigen wäre: der Fehler wird auch als Flash-Meldung übermittelt
        flash(str(e), "error")
    return redirect(url_for("persons.list_persons"))


# die Seite des Formulars: Titel, Adresse für das Absenden, Formular, globaler Fehler
def form_page(title: str, action: str, form: PersonForm, error: str | None = None):
    return render_template("persons/form.html", title=title, action=action,
                           form=form, error=error)
  • Zeilen 12–13: die Geschäftsschicht, die einzige Schicht, die der Controller kennt;
  • Zeilen 32–42: die Operation „Hinzufügen“ in drei Schritten: Formularvalidierung (Eingabefehler), Aufruf der Geschäftsschicht (Geschäftsregeln), dann das PRG-Schema. Eine [BusinessException] zeigt das Formular samt der Meldung in der Fußzeile erneut an. [flash] erhält als zweiten Parameter eine Kategorie (["success"]), anhand derer das Template die Darstellung der Meldung auswählt;
  • Zeilen 46–54: das Formular zum Bearbeiten, vorausgefüllt: Der Parameter [obj] füllt die Formularfelder mit den gleichnamigen Attributen des Objekts, einschließlich der Version. Eine nicht vorhandene Person führt zur Weiterleitung auf die Liste, mit einer Flash-Fehlermeldung;
  • Zeilen 58–69: das Bearbeiten, nach demselben Muster wie das Hinzufügen;
  • Zeilen 73–80: das Löschen. Es gibt kein Formular, das erneut angezeigt werden müsste: Jeder Fehler wird zusätzlich in einer Popup-Meldung der Kategorie ["error"] angezeigt.

Die Web-Schicht enthält weder SQL noch irgendwelche Geschäftsregeln: Sie übersetzt die Anfrage in einen Aufruf der Geschäftsschicht und das Ergebnis in eine Seite.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Persons</title>
  <link rel="stylesheet" href="{{ url_for('bootstrap.static', filename='css/bootstrap.min.css') }}">
  <link rel="stylesheet" href="{{ url_for('static', filename='css/styles.css') }}">
</head>
<body>
  <div class="container py-3" style="max-width: 40rem">
    {# die Erfolgsmeldungen (Flash-Meldungen der Kategorie "success"): oben #}
    {% for message in get_flashed_messages(category_filter=["success"]) %}
    <div class="alert alert-success" role="status">{{ message }}</div>
    {% endfor %}
    <main>
      {% block content %}{% endblock %}
    </main>
    {# der Fehler: der aktuellen Anfrage oder von vor der Weiterleitung (Flash-Meldung) #}
    {% for message in get_flashed_messages(category_filter=["error"]) + ([error] if error else []) %}
    <div class="error-area" role="alert">{{ message }}</div>
    {% endfor %}
  </div>
  {% include "fragments/confirmation.html" %}
  <script src="{{ url_for('static', filename='js/app.js') }}"></script>
</body>
</html>
  • Zeilen 12–14: [category_filter] gibt nur die Flash-Meldungen der angegebenen Kategorien aus: Erfolgsmeldungen am Seitenanfang;
  • Zeilen 19–21: Fehler am Seitenende: zuerst die, die vor einer Weiterleitung auftraten (Flash-Meldungen), gefolgt vom Fehler der aktuellen Anfrage (Variable [error]). Der Operator [+] verkettet zwei Listen.
{% extends "layout.html" %}

{% block content %}
  <h1 class="h3">Persons</h1>
  <table class="table align-middle">
    <thead><tr><th>First name</th><th>Last name</th><th>Age</th><th></th></tr></thead>
    <tbody>
      {% for p in persons %}
      <tr>
        <td>{{ p.first_name }}</td>
        <td>{{ p.last_name }}</td>
        <td>{{ p.age }}</td>
        <td class="text-end">
          <a class="btn btn-sm btn-outline-primary" href="{{ url_for('persons.edit_form', id=p.id) }}">Edit</a>
          <form method="post" class="d-inline" action="{{ url_for('persons.delete', id=p.id) }}"
                data-confirmation="Delete {{ p.first_name }} {{ p.last_name }}?">
            <input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
            <button class="btn btn-sm btn-outline-danger" type="submit">Delete</button>
          </form>
        </td>
      </tr>
      {% endfor %}
    </tbody>
  </table>
  <a class="btn btn-primary" href="{{ url_for('persons.add_form') }}">Add a person</a>
{% endblock %}

Die Liste enthält die Links und Schaltflächen aus Beispiel 21 samt ihrem Bestätigungsfenster (die Dateien [fragments/confirmation.html] und [static/js/app.js] sind die aus Beispiel 21).

{% extends "layout.html" %}
{% from "fragments/field.html" import field_row %}

{% block content %}
  <h1 class="h3">{{ title }}</h1>
  <form method="post" action="{{ action }}" novalidate>
    {{ form.csrf_token }}
    {# die Version des gelesenen Datensatzes: sie kommt mit dem Formular zurück #}
    {{ form.version }}
    {{ field_row(form.first_name) }}
    {{ field_row(form.last_name) }}
    {{ field_row(form.age) }}
    <button class="btn btn-primary" type="submit">Save</button>
    <a class="btn btn-link" href="{{ url_for('persons.list_persons') }}">Cancel</a>
  </form>
{% endblock %}
  • Zeile 9: das versteckte Feld, das die Version des gelesenen Datensatzes trägt;
  • Zeilen 10–12: das Makro aus Beispiel 19.

9.1.7. Ausführung

Die Personenliste:

Image

Ein falsch ausgefülltes Formular zum Hinzufügen: Eingabefehler werden von der Web-Schicht erkannt.

Image

Ein Namensvetter: Die Eingabe ist korrekt, aber die Geschäftsschicht lehnt das Hinzufügen ab. Da der Vergleich von der Datenbank durchgeführt wird, ignoriert er sowohl Groß- und Kleinschreibung als auch Akzente: [marie pelissier] wäre ebenfalls ein Namensvetter von [Marie Pélissier].

Image

Ein erfolgreiches Hinzufügen:

Image

Um Regel Nr. 2 zu testen, öffnen wir denselben Datensatz in zwei Tabs. Im ersten Tab ändern wir das Alter und speichern. Im zweiten Tab, der noch die alte Version anzeigt, ändern wir den Datensatz ebenfalls:

Image

Das Löschen mit seiner Bestätigung:

Image

Image

9.1.8. Die SQL-Befehle

Starten wir die Anwendung neu mit der Umgebungsvariablen [FLASK_SQL_ECHO=true] (unter [Windows]: [$env:FLASK_SQL_ECHO="true"]) und beobachten wir in der Konsole die SQL-Befehle bei einer Änderung. Die Anzeige des Änderungsformulars für Person Nr. 1:

1
2
3
4
5
6
INFO sqlalchemy.engine.Engine BEGIN (implicit)
INFO sqlalchemy.engine.Engine SELECT persons.id, persons.version, persons.first_name, persons.last_name, persons.age
FROM persons
WHERE persons.id = %(pk_1)s
INFO sqlalchemy.engine.Engine [generated in 0.00017s] {'pk_1': 1}
INFO sqlalchemy.engine.Engine COMMIT

Eine Transaktion, [SELECT], über den Primärschlüssel, dessen Wert als Parameter übergeben wird ([%(pk_1)s]; siehe die Parametersyntax von [PyMySQL]). Das Speichern des Datensatzes mit einem neuen Alter:

INFO sqlalchemy.engine.Engine BEGIN (implicit)
INFO sqlalchemy.engine.Engine SELECT persons.id, persons.version, persons.first_name, persons.last_name, persons.age
FROM persons
WHERE persons.id = %(pk_1)s
INFO sqlalchemy.engine.Engine [cached since 0.05972s ago] {'pk_1': 1}
INFO sqlalchemy.engine.Engine SELECT persons.id, persons.version, persons.first_name, persons.last_name, persons.age
FROM persons
WHERE persons.first_name = %(first_name_1)s AND persons.last_name = %(last_name_1)s AND persons.id != %(id_1)s
 LIMIT %(param_1)s
INFO sqlalchemy.engine.Engine [generated in 0.00016s] {'first_name_1': 'Marie', 'last_name_1': 'Pélissier', 'id_1': 1, 'param_1': 1}
INFO sqlalchemy.engine.Engine UPDATE persons SET version=%(version)s, age=%(age)s WHERE persons.id = %(persons_id)s AND persons.version = %(persons_version)s
INFO sqlalchemy.engine.Engine [generated in 0.00015s] {'version': 1, 'age': 43, 'persons_id': 1, 'persons_version': 0}
INFO sqlalchemy.engine.Engine COMMIT

In einer einzigen Transaktion sehen wir Folgendes: das Lesen des Datensatzes, die Suche nach einem Namensvetter und dann das [UPDATE]. Dieses ändert nur die geänderte Spalte ([age]), erhöht die Version (von 0 auf 1) und setzt die Bedingung des optimistischen Sperrens ([AND persons.version = 0]). Der Eintrag [cached since] zeigt an, dass [SQLAlchemy] die SQL-Übersetzung einer zuvor erstellten Anfrage wiederverwendet hat. Senden wir nun dasselbe Formular ein zweites Mal ab, weiterhin mit Version 0:

1
2
3
4
5
6
INFO sqlalchemy.engine.Engine BEGIN (implicit)
INFO sqlalchemy.engine.Engine SELECT persons.id, persons.version, persons.first_name, persons.last_name, persons.age
FROM persons
WHERE persons.id = %(pk_1)s
INFO sqlalchemy.engine.Engine [cached since 0.09593s ago] {'pk_1': 1}
INFO sqlalchemy.engine.Engine ROLLBACK

Die gelesene Version (1) ist nicht die des Formulars (0): Die Geschäftsschicht hat eine [BusinessException] ausgelöst, die die Transaktion zurückgerollt hat ([ROLLBACK]), und die Seite zeigt „This record has been modified meanwhile: reload it.“ Ebenso endet das Hinzufügen eines Namensvetters nach der Namensvetter-Suche, ohne ein [INSERT].