Deklarative Mapping-Stile

Wie in Deklarativem Mapping eingeführt, ist das Deklarative Mapping die typische Methode, wie Mappings im modernen SQLAlchemy konstruiert werden. Dieser Abschnitt gibt einen Überblick über die Formen, die für die deklarative Mapper-Konfiguration verwendet werden können.

Verwendung einer deklarativen Basisklasse

Der gebräuchlichste Ansatz ist die Erzeugung einer „deklarativen Basis“-Klasse durch Unterklasse der DeclarativeBase Superklasse.

from sqlalchemy.orm import DeclarativeBase


# declarative base class
class Base(DeclarativeBase):
    pass

Die deklarative Basisklasse kann auch unter Angabe einer vorhandenen registry erstellt werden, indem diese als Klassenvariable namens registry zugewiesen wird.

from sqlalchemy.orm import DeclarativeBase
from sqlalchemy.orm import registry

reg = registry()


# declarative base class
class Base(DeclarativeBase):
    registry = reg

Geändert in Version 2.0: Die DeclarativeBase Superklasse ersetzt die Verwendung der declarative_base() Funktion und der registry.generate_base() Methoden; der Superklassenansatz integriert sich mit PEP 484 Werkzeugen ohne die Verwendung von Plugins. Siehe ORM Deklarative Modelle für Migrationshinweise.

Mit der deklarativen Basisklasse werden neue abgebildete Klassen als Unterklassen der Basis deklariert.

from datetime import datetime
from typing import List
from typing import Optional

from sqlalchemy import ForeignKey
from sqlalchemy import func
from sqlalchemy import Integer
from sqlalchemy import String
from sqlalchemy.orm import DeclarativeBase
from sqlalchemy.orm import Mapped
from sqlalchemy.orm import mapped_column
from sqlalchemy.orm import relationship


class Base(DeclarativeBase):
    pass


class User(Base):
    __tablename__ = "user"

    id = mapped_column(Integer, primary_key=True)
    name: Mapped[str]
    fullname: Mapped[Optional[str]]
    nickname: Mapped[Optional[str]] = mapped_column(String(64))
    create_date: Mapped[datetime] = mapped_column(insert_default=func.now())

    addresses: Mapped[List["Address"]] = relationship(back_populates="user")


class Address(Base):
    __tablename__ = "address"

    id = mapped_column(Integer, primary_key=True)
    user_id = mapped_column(ForeignKey("user.id"))
    email_address: Mapped[str]

    user: Mapped["User"] = relationship(back_populates="addresses")

Oben dient die Klasse Base als Basis für neue abzubildende Klassen. Wie oben gezeigt, werden die neuen abgebildeten Klassen User und Address konstruiert.

Für jede konstruierte Unterklasse folgt der Körper der Klasse dem deklarativen Mapping-Ansatz, der sowohl eine Table als auch ein Mapper-Objekt im Hintergrund definiert, die ein vollständiges Mapping bilden.

Siehe auch

Tabellenkonfiguration mit Deklarativem - beschreibt, wie die Komponenten der abgebildeten Table spezifiziert werden, die generiert werden soll, einschließlich Hinweisen und Optionen zur Verwendung des mapped_column() Konstrukts und wie es mit dem Mapped Annotationstyp interagiert.

Mapper-Konfiguration mit Deklarativem - beschreibt alle anderen Aspekte der ORM-Mapper-Konfiguration innerhalb des Deklarativen, einschließlich relationship() Konfiguration, SQL-Ausdrücken und Mapper Parametern.

Deklaratives Mapping mit einem Dekorator (keine deklarative Basis)

Als Alternative zur Verwendung der „deklarativen Basis“-Klasse kann das deklarative Mapping explizit auf eine Klasse angewendet werden, entweder mit einer imperativen Technik, ähnlich der eines „klassischen“ Mappings, oder noch prägnanter durch die Verwendung eines Dekorators. Die Funktion registry.mapped() ist ein Klassen-Dekorator, der auf jede Python-Klasse ohne bestehende Hierarchie angewendet werden kann. Die Python-Klasse wird ansonsten normal im deklarativen Stil konfiguriert.

Das folgende Beispiel richtet das identische Mapping ein, wie im vorherigen Abschnitt gezeigt, und verwendet den registry.mapped() Dekorator anstelle der Verwendung der DeclarativeBase Superklasse.

from datetime import datetime
from typing import List
from typing import Optional

from sqlalchemy import ForeignKey
from sqlalchemy import func
from sqlalchemy import Integer
from sqlalchemy import String
from sqlalchemy.orm import Mapped
from sqlalchemy.orm import mapped_column
from sqlalchemy.orm import registry
from sqlalchemy.orm import relationship

mapper_registry = registry()


@mapper_registry.mapped
class User:
    __tablename__ = "user"

    id = mapped_column(Integer, primary_key=True)
    name: Mapped[str]
    fullname: Mapped[Optional[str]]
    nickname: Mapped[Optional[str]] = mapped_column(String(64))
    create_date: Mapped[datetime] = mapped_column(insert_default=func.now())

    addresses: Mapped[List["Address"]] = relationship(back_populates="user")


@mapper_registry.mapped
class Address:
    __tablename__ = "address"

    id = mapped_column(Integer, primary_key=True)
    user_id = mapped_column(ForeignKey("user.id"))
    email_address: Mapped[str]

    user: Mapped["User"] = relationship(back_populates="addresses")

Bei Verwendung des obigen Stils erfolgt das Mapping einer bestimmten Klasse **nur**, wenn der Dekorator direkt auf diese Klasse angewendet wird. Für Vererbungsmappings (detailliert beschrieben in Mapping von Klassenvererbungshierarchien) sollte der Dekorator auf jede abzubildende Unterklasse angewendet werden.

from sqlalchemy.orm import registry

mapper_registry = registry()


@mapper_registry.mapped
class Person:
    __tablename__ = "person"

    person_id = mapped_column(Integer, primary_key=True)
    type = mapped_column(String, nullable=False)

    __mapper_args__ = {
        "polymorphic_on": type,
        "polymorphic_identity": "person",
    }


@mapper_registry.mapped
class Employee(Person):
    __tablename__ = "employee"

    person_id = mapped_column(ForeignKey("person.person_id"), primary_key=True)

    __mapper_args__ = {
        "polymorphic_identity": "employee",
    }

Sowohl der Stil der deklarativen Tabellenkonfiguration als auch der Stil der imperativen Tabellenkonfiguration können sowohl mit dem Deklarativen Basis- als auch mit dem Dekorator-Stil des Deklarativen Mappings verwendet werden.

Die Dekoratorform des Mappings ist nützlich, wenn ein SQLAlchemy-deklaratives Mapping mit anderen Klasseninstrumentierungssystemen wie Dataclasses und attrs kombiniert wird, obwohl zu beachten ist, dass SQLAlchemy 2.0 nun auch die Integration mit Dataclasses in deklarativen Basisklassen bietet.