Class Mapping API¶

Objektname	Beschreibung
add_mapped_attribute(target, key, attr)	Fügt ein neues zugeordnetes Attribut zu einer ORM-zugeordneten Klasse hinzu.
as_declarative(**kw)	Klassendekorator, der eine gegebene Klasse in eine `declarative_base()` anpasst.
class_mapper(class_[, configure])	Gibt für eine Klasse den primären `Mapper` zurück, der mit dem Schlüssel assoziiert ist.
clear_mappers()	Entfernt alle Mapper aus allen Klassen.
column_property(column, *additional_columns, [group, deferred, raiseload, comparator_factory, init, repr, default, default_factory, compare, kw_only, hash, active_history, expire_on_flush, info, doc])	Stellt eine spaltenbezogene Eigenschaft für die Verwendung mit einem Mapping bereit.
configure_mappers()	Initialisiert die Beziehungen zwischen den Makern aller bisher in allen `registry`-Sammlungen konstruierten Makern.
declarative_base(*, [metadata, mapper, cls, name, class_registry, type_annotation_map, constructor, metaclass])	Erstellt eine Basisklasse für deklarative Klassendefinitionen.
declarative_mixin(cls)	Markiert eine Klasse als Bereitsteller der Funktion „deklaratives Mixin“.
DeclarativeBase	Basisklasse für deklarative Klassendefinitionen.
DeclarativeBaseNoMeta	Dasselbe wie `DeclarativeBase`, verwendet aber keine Metaklasse, um neue Attribute abzufangen.
declared_attr	Markiert eine klassenbezogene Methode als Definition einer zugeordneten Eigenschaft oder einer deklarativen Direktive.
has_inherited_table(cls)	Gibt True zurück, wenn eine der Klassen, von denen die gegebene Klasse erbt, eine zugeordnete Tabelle hat, andernfalls False.
identity_key([class_, ident], *, [instance, row, identity_token])	Erzeugt „Identitätsschlüssel“-Tupel, wie sie als Schlüssel im Wörterbuch `Session.identity_map` verwendet werden.
mapped_column([__name_pos, __type_pos], args, [init, repr, default, default_factory, compare, kw_only, hash, nullable, primary_key, deferred, deferred_group, deferred_raiseload, use_existing_column, name, type_, autoincrement, doc, key, index, unique, info, onupdate, insert_default, server_default, server_onupdate, active_history, quote, system, comment, sort_order], *kw)	Deklariert eine neue ORM-zugeordnete `Column`-Konstruktion für die Verwendung innerhalb der Deklarative Tabelle-Konfiguration.
MappedAsDataclass	Mixin-Klasse, die anzeigt, dass beim Mappen dieser Klasse diese auch in eine Dataclass umgewandelt wird.
MappedClassProtocol	Ein Protokoll, das eine SQLAlchemy zugeordnete Klasse repräsentiert.
Mapper	Definiert eine Zuordnung zwischen einer Python-Klasse und einer Datenbanktabelle oder einer anderen relationalen Struktur, damit ORM-Operationen auf der Klasse durchgeführt werden können.
object_mapper(instance)	Gibt für ein Objekt den primären Mapper zurück, der der Objektinstanz zugeordnet ist.
orm_insert_sentinel([name, type_], *, [default, omit_from_statements])	Bietet eine Ersatz-`mapped_column()`, die eine sogenannte Sentinel-Spalte generiert, was effiziente Masseneinfügungen mit deterministischer RETURNING-Sortierung für Tabellen ermöglicht, die anderweitig keine qualifizierenden Primärschlüsselkonfigurationen haben.
polymorphic_union(table_map, typecolname[, aliasname, cast_nulls])	Erstellt eine `UNION`-Anweisung, die von einem polymorphen Mapper verwendet wird.
reconstructor(fn)	Dekoriert eine Methode als „Rekonstruktor“-Hook.
registry	Allgemeine Registry zum Zuordnen von Klassen.
synonym_for(name[, map_column])	Dekorator, der ein `synonym()`-Attribut in Verbindung mit einem Python-Deskriptor erzeugt.

class sqlalchemy.orm.registry¶

Allgemeine Registry zum Zuordnen von Klassen.

Die registry dient als Grundlage für die Pflege einer Sammlung von Mappings und bietet Konfigurations-Hooks, die zum Mappen von Klassen verwendet werden.

Die drei allgemeinen Arten von unterstützten Mappings sind Declarative Base, Declarative Decorator und Imperative Mapping. Alle diese Mapping-Stile können austauschbar verwendet werden.

registry.generate_base() gibt eine neue deklarative Basisklasse zurück und ist die zugrunde liegende Implementierung der Funktion declarative_base().
registry.mapped() bietet einen Klassendekorator, der die deklarative Zuordnung auf eine Klasse ohne die Verwendung einer deklarativen Basisklasse anwendet.
registry.map_imperatively() erzeugt einen Mapper für eine Klasse, ohne die Klasse nach deklarativen Klassenattributen zu durchsuchen. Diese Methode eignet sich für den Anwendungsfall, der historisch von der klassischen Mapping-Funktion sqlalchemy.orm.mapper() bereitgestellt wurde, die ab SQLAlchemy 2.0 entfernt ist.

Neu in Version 1.4.

Mitglieder

__init__(), as_declarative_base(), configure(), dispose(), generate_base(), map_declaratively(), map_imperatively(), mapped(), mapped_as_dataclass(), mappers, update_type_annotation_map()

Siehe auch

Übersicht über ORM-zugeordnete Klassen - Überblick über Mapping-Stile für Klassen.

method sqlalchemy.orm.registry.__init__(*, metadata: Optional[MetaData] = None, class_registry: Optional[clsregistry._ClsRegistryType] = None, type_annotation_map: Optional[_TypeAnnotationMapType] = None, constructor: Callable[..., None] = <function _declarative_constructor>)¶

Erstellt eine neue registry

Parameter:

metadata¶ – Eine optionale MetaData-Instanz. Alle Table-Objekte, die mit der deklarativen Tabellenzuordnung generiert werden, verwenden diese MetaData-Sammlung. Wenn dieses Argument auf seinem Standardwert von None belassen wird, wird eine leere MetaData-Sammlung erstellt.
constructor¶ – Gibt die Implementierung für die Funktion __init__ einer zugeordneten Klasse an, die keine eigene __init__ hat. Standardmäßig eine Implementierung, die **kwargs für deklarierte Felder und Beziehungen einer Instanz zuweist. Wenn None übergeben wird, wird keine __init__ bereitgestellt und die Konstruktion fällt über die normalen Python-Semantiken auf cls.__init__ zurück.
class_registry¶ – Ein optionales Wörterbuch, das als Registry von Klassennamen -> zugeordneten Klassen dient, wenn Zeichenkettennamen zum Identifizieren von Klassen innerhalb von relationship() und anderen verwendet werden. Ermöglicht zwei oder mehr deklarativen Basisklassen, dieselbe Registry von Klassennamen für vereinfachte Beziehungen zwischen Basen zu teilen.
type_annotation_map¶ –
ein optionales Wörterbuch von Python-Typen zu SQLAlchemy TypeEngine-Klassen oder -Instanzen. Das bereitgestellte Wörterbuch aktualisiert die Standardtypzuordnung. Dies wird ausschließlich von der Konstruktion MappedColumn verwendet, um Spaltentypen basierend auf Anmerkungen im Typ Mapped zu erzeugen.

Neu in Version 2.0.

Siehe auch

Anpassen der Typzuordnung

method sqlalchemy.orm.registry.as_declarative_base(**kw: Any) → Callable[[Type[_T]], Type[_T]]¶

Klassendekorator, der registry.generate_base() für eine gegebene Basisklasse aufruft.

Z. B.

from sqlalchemy.orm import registry

mapper_registry = registry()


@mapper_registry.as_declarative_base()
class Base:
    @declared_attr
    def __tablename__(cls):
        return cls.__name__.lower()

    id = Column(Integer, primary_key=True)


class MyMappedClass(Base): ...

Alle Schlüsselwortargumente, die an registry.as_declarative_base() übergeben werden, werden an registry.generate_base() weitergeleitet.

method sqlalchemy.orm.registry.configure(cascade: bool = False) → None¶

Konfiguriert alle bisher unkonfigurierten Mapper in dieser registry.

Der Konfigurationsschritt dient dazu, die relationship()-Verknüpfungen zwischen zugeordneten Klassen abzugleichen und zu initialisieren, sowie Konfigurationsereignisse aufzurufen, wie z. B. MapperEvents.before_configured() und MapperEvents.after_configured(), die von ORM-Erweiterungen oder benutzerdefinierten Erweiterungshooks verwendet werden können.

Wenn ein oder mehrere Mapper in dieser Registry relationship()-Konstrukte enthalten, die auf zugeordnete Klassen in anderen Registrys verweisen, gilt diese Registry als *abhängig* von diesen Registrys. Um diese abhängigen Registrys automatisch zu konfigurieren, sollte das Flag configure.cascade auf True gesetzt werden. Andernfalls wird eine Ausnahme ausgelöst, wenn sie nicht konfiguriert sind. Der Grund für dieses Verhalten ist, dass eine Anwendung die Konfiguration von Registrys programmgesteuert aufrufen kann, während sie steuert, ob der Prozess implizit andere Registrys erreicht.

Als Alternative zur Ausführung von registry.configure() kann die ORM-Funktion configure_mappers() verwendet werden, um sicherzustellen, dass die Konfiguration für alle registry-Objekte im Speicher abgeschlossen ist. Dies ist im Allgemeinen einfacher zu verwenden und stammt aus der Zeit vor der Verwendung von registry-Objekten. Diese Funktion wirkt sich jedoch auf alle Mappings im gesamten laufenden Python-Prozess aus und kann für eine Anwendung, die viele Registrys für verschiedene Zwecke verwendet, die möglicherweise nicht sofort benötigt werden, speicher- und zeitaufwändiger sein.

Siehe auch

configure_mappers()

Neu ab Version 1.4.0b2.

method sqlalchemy.orm.registry.dispose(cascade: bool = False) → None¶

Entsorgt alle Mapper in dieser registry.

Nach der Ausführung haben alle Klassen, die in dieser Registry zugeordnet wurden, keine Klasseninstrumentierung mehr, die mit ihnen assoziiert ist. Diese Methode ist das pro-registry-Analogon zur anwendungsweiten Funktion clear_mappers().

Wenn diese Registry Mapper enthält, die Abhängigkeiten anderer Registrys sind, typischerweise über relationship()-Links, dann müssen auch diese Registrys entsorgt werden. Wenn solche Registrys in Bezug auf diese existieren, wird deren registry.dispose()-Methode ebenfalls aufgerufen, wenn das Flag dispose.cascade auf True gesetzt ist; andernfalls wird ein Fehler ausgelöst, wenn diese Registrys nicht bereits entsorgt wurden.

Neu ab Version 1.4.0b2.

Siehe auch

clear_mappers()

method sqlalchemy.orm.registry.generate_base(mapper: ~typing.Callable[[...], ~sqlalchemy.orm.mapper.Mapper[~typing.Any]] | None, cls: ~typing.Type[~typing.Any] = <class 'object'>, name: str = 'Base', metaclass: ~typing.Type[~typing.Any] = <class 'sqlalchemy.orm.decl_api.DeclarativeMeta'>) → Any¶

Generiert eine deklarative Basisklasse.

Klassen, die von der zurückgegebenen Klasse erben, werden automatisch mit deklarativer Zuordnung zugeordnet.

Z. B.

from sqlalchemy.orm import registry

mapper_registry = registry()

Base = mapper_registry.generate_base()


class MyClass(Base):
    __tablename__ = "my_table"
    id = Column(Integer, primary_key=True)

Die obige dynamisch generierte Klasse ist äquivalent zum nicht-dynamischen Beispiel unten

from sqlalchemy.orm import registry
from sqlalchemy.orm.decl_api import DeclarativeMeta

mapper_registry = registry()


class Base(metaclass=DeclarativeMeta):
    __abstract__ = True
    registry = mapper_registry
    metadata = mapper_registry.metadata

    __init__ = mapper_registry.constructor

Geändert in Version 2.0: Beachten Sie, dass die Methode registry.generate_base() durch die neue Klasse DeclarativeBase ersetzt wird, die eine neue „Basis“-Klasse durch Unterklassenbildung generiert, anstatt den Rückgabewert einer Funktion. Dies ermöglicht einen Ansatz, der mit den PEP 484-Typwerkzeugen kompatibel ist.

Die Methode registry.generate_base() stellt die Implementierung für die Funktion declarative_base() bereit, die die registry und die Basisklasse auf einmal erstellt.

Siehe den Abschnitt Deklarative Zuordnung für Hintergründe und Beispiele.

Parameter:

mapper¶ – Ein optionaler aufrufbarer Wert, Standard ist Mapper. Diese Funktion wird verwendet, um neue Mapper-Objekte zu generieren.
cls¶ – Standard ist object. Ein Typ, der als Basis für die generierte deklarative Basisklasse verwendet wird. Kann eine Klasse oder ein Tupel von Klassen sein.
name¶ – Standard ist Base. Der Anzeigename für die generierte Klasse. Dies anzupassen ist nicht erforderlich, kann aber die Klarheit in Tracebacks und beim Debugging verbessern.
metaclass¶ – Standard ist DeclarativeMeta. Eine Metaklasse oder eine __metaclass__-kompatible aufrufbare Funktion, die als Metatyp der generierten deklarativen Basisklasse verwendet wird.

Siehe auch

Deklarative Zuordnung

declarative_base()

method sqlalchemy.orm.registry.map_declaratively(cls: Type[_O]) → Mapper[_O]¶

Ordnet eine Klasse deklarativ zu.

In dieser Zuordnungsform wird die Klasse nach Zuordnungsinformationen durchsucht, einschließlich Spalten, die einer Tabelle zugeordnet werden sollen, und/oder einem tatsächlichen Tabellenobjekt.

Gibt das Mapper-Objekt zurück.

Z. B.

from sqlalchemy.orm import registry

mapper_registry = registry()

class Foo:
    __tablename__ = "some_table"

    id = Column(Integer, primary_key=True)
    name = Column(String)

mapper = mapper_registry.map_declaratively(Foo)

Diese Funktion wird bequemer indirekt entweder über den Klassendekorator registry.mapped() oder durch Unterklassenbildung einer deklarativen Metaklasse, die aus registry.generate_base() generiert wurde, aufgerufen.

Siehe den Abschnitt Deklarative Zuordnung für vollständige Details und Beispiele.

Parameter:: cls¶ – Die zuzuordnende Klasse.
Gibt zurück:: ein Mapper-Objekt.

Siehe auch

Deklarative Zuordnung

registry.mapped() - gebräuchlichere Dekorator-Schnittstelle zu dieser Funktion.

registry.map_imperatively()

method sqlalchemy.orm.registry.map_imperatively(class_: Type[_O], local_table: FromClause | None = None, **kw: Any) → Mapper[_O]¶

Ordnet eine Klasse imperativ zu.

In dieser Zuordnungsform wird die Klasse nicht nach Zuordnungsinformationen durchsucht. Stattdessen werden alle Zuordnungskonstrukte als Argumente übergeben.

Diese Methode ist vollständig äquivalent zur inzwischen entfernten SQLAlchemy-Funktion mapper(), außer dass sie sich auf eine bestimmte Registry bezieht.

Z. B.

from sqlalchemy.orm import registry

mapper_registry = registry()

my_table = Table(
    "my_table",
    mapper_registry.metadata,
    Column("id", Integer, primary_key=True),
)


class MyClass:
    pass


mapper_registry.map_imperatively(MyClass, my_table)

Siehe den Abschnitt Imperative Zuordnung für vollständige Hintergründe und Anwendungsbeispiele.

Parameter:

class_¶ – Die zuzuordnende Klasse. Entspricht dem Parameter Mapper.class_.
local_table¶ – die Table oder eine andere FromClause, die das Thema der Zuordnung ist. Entspricht dem Parameter Mapper.local_table.
**kw¶ – Alle anderen Schlüsselwortargumente werden direkt an den Konstruktor von Mapper übergeben.

Siehe auch

Imperative Zuordnung

Deklarative Zuordnung

method sqlalchemy.orm.registry.mapped(cls: Type[_O]) → Type[_O]¶

Klassendekorator, der den deklarativen Zuordnungsprozess auf eine gegebene Klasse anwendet.

Z. B.

from sqlalchemy.orm import registry

mapper_registry = registry()


@mapper_registry.mapped
class Foo:
    __tablename__ = "some_table"

    id = Column(Integer, primary_key=True)
    name = Column(String)

Siehe den Abschnitt Deklarative Zuordnung für vollständige Details und Beispiele.

Parameter:: cls¶ – Die zuzuordnende Klasse.
Gibt zurück:: die übergebene Klasse.

Siehe auch

Deklarative Zuordnung

registry.generate_base() - generiert eine Basisklasse, die die deklarative Zuordnung automatisch über eine Python-Metaklasse auf Unterklassen anwendet.

Siehe auch

registry.mapped_as_dataclass()

methode sqlalchemy.orm.registry.mapped_as_dataclass(_registry__cls: Type[_O] | None = None, *, init: _NoArg | bool = _NoArg.NO_ARG, repr: _NoArg | bool = _NoArg.NO_ARG, eq: _NoArg | bool = _NoArg.NO_ARG, order: _NoArg | bool = _NoArg.NO_ARG, unsafe_hash: _NoArg | bool = _NoArg.NO_ARG, match_args: _NoArg | bool = _NoArg.NO_ARG, kw_only: _NoArg | bool = _NoArg.NO_ARG, dataclass_callable: _NoArg | Callable[..., Type[Any]] = _NoArg.NO_ARG) → Type[_O] | Callable[[Type[_O]], Type[_O]]¶: Klassendekorator, der den deklarativen Mapping-Prozess auf eine gegebene Klasse anwendet und die Klasse zusätzlich in eine Python-Datenklasse konvertiert.

Siehe auch

Deklaratives Mapping von Datenklassen - Vollständiger Hintergrund zum nativen Mapping von Datenklassen in SQLAlchemy

Neu in Version 2.0.

attribut sqlalchemy.orm.registry.mappers¶: Schreibgeschützte Sammlung aller Mapper-Objekte.

methode sqlalchemy.orm.registry.update_type_annotation_map(type_annotation_map: _TypeAnnotationMapType) → None¶: Aktualisiert die registry.type_annotation_map mit neuen Werten.

funktion sqlalchemy.orm.add_mapped_attribute(target: Type[_O], key: str, attr: MapperProperty[Any]) → None¶

Fügt ein neues zugeordnetes Attribut zu einer ORM-zugeordneten Klasse hinzu.

Z. B.

add_mapped_attribute(User, "addresses", relationship(Address))

Dies kann für ORM-Mappings verwendet werden, die keine deklarativen Metaklassen verwenden, die Attribut-Set-Operationen abfangen.

Neu in Version 2.0.

funktion sqlalchemy.orm.column_property(column: _ORMColumnExprArgument[_T], *additional_columns: _ORMColumnExprArgument[Any], group: str | None = None, deferred: bool = False, raiseload: bool = False, comparator_factory: Type[PropComparator[_T]] | None = None, init: _NoArg | bool = _NoArg.NO_ARG, repr: _NoArg | bool = _NoArg.NO_ARG, default: Any | None = _NoArg.NO_ARG, default_factory: _NoArg | Callable[[], _T] = _NoArg.NO_ARG, compare: _NoArg | bool = _NoArg.NO_ARG, kw_only: _NoArg | bool = _NoArg.NO_ARG, hash: _NoArg | bool | None = _NoArg.NO_ARG, active_history: bool = False, expire_on_flush: bool = True, info: _InfoType | None = None, doc: str | None = None) → MappedSQLExpression[_T]¶

Stellt eine spaltenbezogene Eigenschaft für die Verwendung mit einem Mapping bereit.

Bei deklarativen Mappings wird column_property() verwendet, um schreibgeschützte SQL-Ausdrücke einer gemappten Klasse zuzuordnen.

Bei imperativen Mappings übernimmt column_property() auch die Zuordnung von Tabellenspalten mit zusätzlichen Funktionen. Bei vollständig deklarativen Mappings sollte das Konstrukt mapped_column() für diesen Zweck verwendet werden.

Bei deklarativen Datenklassen-Mappings wird column_property() als **schreibgeschützt** betrachtet und nicht im Konstruktor __init__() der Datenklasse enthalten.

Die Funktion column_property() gibt eine Instanz von ColumnProperty zurück.

Siehe auch

Verwendung von column_property - Allgemeine Verwendung von column_property() zur Zuordnung von SQL-Ausdrücken

Anwenden von Lade-, Persistenz- und Mapping-Optionen für imperative Tabellenspalten - Verwendung von column_property() mit imperativen Tabellenmappings, um einem einfachen Column-Objekt zusätzliche Optionen hinzuzufügen

Parameter:

*cols¶ – Liste der abzubildenden Spaltenobjekte.
active_history=False¶ – Nur für imperative Tabellenmappings oder Legacy-Deklarativ-Mappings (d.h. die nicht auf mapped_column() aktualisiert wurden) verwendet, für spaltenbasierte Attribute, die beschreibbar sein sollen; für deklarative Mappings verwenden Sie mapped_column() mit mapped_column.active_history. Einzelheiten siehe dort.
comparator_factory¶ – Eine Klasse, die von Comparator erbt und benutzerdefinierte SQL-Klauselgenerierung für Vergleichsoperationen bereitstellt.
group¶ – Ein Gruppenname für diese Eigenschaft, wenn sie als verzögert markiert ist.
deferred¶ – Wenn True, ist die Spalteneigenschaft „verzögert“, d.h. sie wird nicht sofort geladen, sondern erst, wenn auf das Attribut eines Instanz zugegriffen wird. Siehe auch deferred().
doc¶ – Optionaler String, der als Docstring für den klassengebundenen Deskriptor angewendet wird.
expire_on_flush=True¶ – Deaktiviert die Ablauflogik bei Flush. Eine column_property(), die sich auf einen SQL-Ausdruck (und nicht auf eine einzelne tabellengebundene Spalte) bezieht, gilt als „schreibgeschützte“ Eigenschaft; das Befüllen hat keine Auswirkung auf den Zustand der Daten und kann nur den Datenbankzustand zurückgeben. Aus diesem Grund wird der Wert einer column_property() jedes Mal abgelaufen, wenn das übergeordnete Objekt an einem Flush beteiligt ist, d.h. während eines Flushes einen „dirty“-Zustand aufweist. Das Setzen dieses Parameters auf False hat zur Folge, dass nach dem Flush ein vorhandener Wert bestehen bleibt. Beachten Sie jedoch, dass die Session mit Standard-Ablauf-Einstellungen nach einem Session.commit()-Aufruf alle Attribute ablaufen lässt.
info¶ – Optionales Datenwörterbuch, das in das MapperProperty.info-Attribut dieses Objekts aufgenommen wird.
raiseload¶ –
Wenn True, zeigt an, dass die Spalte einen Fehler auslösen soll, wenn sie nicht verzögert ist, anstatt den Wert zu laden. Dies kann zur Abfragezeit durch Verwendung der Option deferred() mit raiseload=False geändert werden.

Neu in Version 1.4.

Siehe auch

raiseload verwenden, um das Laden verzögerter Spalten zu verhindern
init¶ –
Spezifisch für Deklaratives Mapping von Datenklassen, gibt an, ob das zugeordnete Attribut Teil der von der Datenklasse generierten __init__()-Methode sein soll.

Veraltet seit Version 1.4: Der Parameter column_property.init ist für column_property() veraltet. Dieser Parameter gilt nur für beschreibbare Attribute in einer Konfiguration von Deklarativen Datenklassen, und column_property() wird in diesem Kontext als schreibgeschütztes Attribut behandelt.
repr¶ – Spezifisch für Deklaratives Mapping von Datenklassen, gibt an, ob das zugeordnete Attribut Teil der von der Datenklasse generierten __repr__()-Methode sein soll.
default_factory¶ –
Spezifisch für Deklaratives Mapping von Datenklassen, gibt eine Funktion zur Generierung von Standardwerten an, die als Teil der von der Datenklasse generierten __init__()-Methode ausgeführt wird.

Veraltet seit Version 1.4: Der Parameter column_property.default_factory ist für column_property() veraltet. Dieser Parameter gilt nur für beschreibbare Attribute in einer Konfiguration von Deklarativen Datenklassen, und column_property() wird in diesem Kontext als schreibgeschütztes Attribut behandelt.

Siehe auch

Was sind default, default_factory und insert_default und was sollte ich verwenden?

mapped_column.default

mapped_column.insert_default
compare¶ –
Spezifisch für Deklaratives Mapping von Datenklassen, gibt an, ob dieses Feld bei der Generierung der Methoden __eq__() und __ne__() für die zugeordnete Klasse in Vergleichsoperationen einbezogen werden soll.

Neu ab Version 2.0.0b4.
kw_only¶ –
Spezifisch für Deklaratives Mapping von Datenklassen, gibt an, ob dieses Feld bei der Generierung von __init__() als nur-Schlüsselwort-Argument gekennzeichnet werden soll.

Veraltet seit Version 1.4: Der Parameter column_property.kw_only ist für column_property() veraltet. Dieser Parameter gilt nur für beschreibbare Attribute in einer Konfiguration von Deklarativen Datenklassen, und column_property() wird in diesem Kontext als schreibgeschütztes Attribut behandelt.
hash¶ –
Spezifisch für Deklaratives Mapping von Datenklassen, steuert, ob dieses Feld bei der Generierung der __hash__()-Methode für die zugeordnete Klasse einbezogen wird.

Neu in Version 2.0.36.

funktion sqlalchemy.orm.declarative_base(*, metadata: Optional[MetaData] = None, mapper: Optional[Callable[..., Mapper[Any]]] = None, cls: Type[Any] = <class 'object'>, name: str = 'Base', class_registry: Optional[clsregistry._ClsRegistryType] = None, type_annotation_map: Optional[_TypeAnnotationMapType] = None, constructor: Callable[..., None] = <function _declarative_constructor>, metaclass: Type[Any] = <class 'sqlalchemy.orm.decl_api.DeclarativeMeta'>) → Any¶

Erstellt eine Basisklasse für deklarative Klassendefinitionen.

Die neue Basisklasse erhält eine Metaklasse, die entsprechende Table-Objekte erstellt und die entsprechenden Mapper-Aufrufe basierend auf den deklarativ in der Klasse und ihren Unterklassen bereitgestellten Informationen durchführt.

Geändert in Version 2.0: Beachten Sie, dass die Funktion declarative_base() durch die neue Klasse DeclarativeBase ersetzt wird, die eine neue „Basis“-Klasse durch Vererbung generiert und nicht durch den Rückgabewert einer Funktion. Dies ermöglicht einen Ansatz, der mit den Typisierungswerkzeugen von PEP 484 kompatibel ist.

Die Funktion declarative_base() ist eine Kurzform für die Verwendung der Methode registry.generate_base(). Das heißt, das Folgende

from sqlalchemy.orm import declarative_base

Base = declarative_base()

Ist äquivalent zu

from sqlalchemy.orm import registry

mapper_registry = registry()
Base = mapper_registry.generate_base()

Siehe die Docstring für registry und registry.generate_base() für weitere Details.

Geändert in Version 1.4: Die Funktion declarative_base() ist jetzt eine Spezialisierung der allgemeineren Klasse registry. Die Funktion wird auch vom Paket declarative.ext in das Paket sqlalchemy.orm verschoben.

Parameter:

metadata¶ – Eine optionale MetaData-Instanz. Alle durch Unterklassen der Basis implizit deklarierten Table-Objekte teilen sich dieses MetaData. Wenn keines angegeben ist, wird eine MetaData-Instanz erstellt. Die MetaData-Instanz ist über das Attribut metadata der generierten deklarativen Basisklasse verfügbar.
mapper¶ – Ein optionaler aufrufbarer, standardmäßig Mapper. Wird verwendet, um Unterklassen ihren Tabellen zuzuordnen.
cls¶ – Standardmäßig object. Ein Typ, der als Basis für die generierte deklarative Basisklasse verwendet wird. Kann eine Klasse oder ein Tupel von Klassen sein.
name¶ – Standardmäßig Base. Der Anzeigename für die generierte Klasse. Die Anpassung ist nicht erforderlich, kann aber die Klarheit in Tracebacks und beim Debugging verbessern.
constructor¶ – Gibt die Implementierung für die Funktion __init__ einer zugeordneten Klasse an, die keine eigene __init__ hat. Standardmäßig eine Implementierung, die **kwargs für deklarierte Felder und Beziehungen einer Instanz zuweist. Wenn None übergeben wird, wird keine __init__ bereitgestellt und die Konstruktion fällt über normale Python-Semantik auf cls.__init__ zurück.
class_registry¶ – Ein optionales Dictionary, das als Registrierung von Klassennamen -> zugeordneten Klassen dient, wenn Zeichenkettennamen zur Identifizierung von Klassen innerhalb von relationship() und anderen verwendet werden. Ermöglicht zwei oder mehr deklarativen Basisklassen, sich dieselbe Registrierung von Klassennamen für vereinfachte Beziehungen zwischen Basen zu teilen.
type_annotation_map¶ –
Ein optionales Dictionary von Python-Typen zu SQLAlchemy TypeEngine-Klassen oder -Instanzen. Dies wird ausschließlich vom Konstrukt MappedColumn verwendet, um Spaltentypen basierend auf Annotationen innerhalb des Typs Mapped zu erzeugen.

Neu in Version 2.0.

Siehe auch

Anpassen der Typzuordnung
metaclass¶ – Standardmäßig DeclarativeMeta. Eine Metaklasse oder ein __metaclass__-kompatibler aufrufbarer, der als Metatyp der generierten deklarativen Basisklasse verwendet wird.

Siehe auch

registry

function sqlalchemy.orm.declarative_mixin(cls: Type[_T]) → Type[_T]¶

Markiert eine Klasse als Bereitsteller der Funktion „deklaratives Mixin“.

Z. B.

from sqlalchemy.orm import declared_attr
from sqlalchemy.orm import declarative_mixin


@declarative_mixin
class MyMixin:

    @declared_attr
    def __tablename__(cls):
        return cls.__name__.lower()

    __table_args__ = {"mysql_engine": "InnoDB"}
    __mapper_args__ = {"always_refresh": True}

    id = Column(Integer, primary_key=True)


class MyModel(MyMixin, Base):
    name = Column(String(1000))

Der Dekorator declarative_mixin() modifiziert die gegebene Klasse derzeit in keiner Weise; sein aktueller Zweck ist ausschließlich, das Mypy Plugin zu unterstützen, damit es SQLAlchemy-deklarative Mixin-Klassen identifizieren kann, wenn kein anderer Kontext vorhanden ist.

Neu in Version 1.4.6.

Siehe auch

Zusammensetzen von gemappten Hierarchien mit Mixins

Verwendung von @declared_attr und deklarativen Mixins - in der Mypy-Plugin-Dokumentation

function sqlalchemy.orm.as_declarative(**kw: Any) → Callable[[Type[_T]], Type[_T]]¶

Klassendekorator, der eine gegebene Klasse in eine declarative_base() anpasst.

Diese Funktion verwendet die Methode registry.as_declarative_base(), indem sie zuerst automatisch eine registry erstellt und dann den Dekorator aufruft.

Z. B.

from sqlalchemy.orm import as_declarative


@as_declarative()
class Base:
    @declared_attr
    def __tablename__(cls):
        return cls.__name__.lower()

    id = Column(Integer, primary_key=True)


class MyMappedClass(Base): ...

Siehe auch

registry.as_declarative_base()

Deklariert eine neue ORM-zugeordnete Column-Konstruktion für die Verwendung innerhalb der Deklarative Tabelle-Konfiguration.

Die Funktion mapped_column() bietet ein ORM-fähiges und mit Python-Typen kompatibles Konstrukt, das mit deklarativen Zuordnungen verwendet wird, um ein Attribut anzuzeigen, das einer Core Column-Objekt zugeordnet ist. Sie bietet dieselbe Funktionalität wie die direkte Zuordnung eines Attributs zu einem Column-Objekt bei Verwendung von Declarative, insbesondere bei Verwendung der Deklarativen Tabellenkonfiguration.

Neu in Version 2.0.

mapped_column() wird normalerweise mit expliziter Typisierung zusammen mit dem Annotationstyp Mapped verwendet, wo sie den SQL-Typ und die Nullbarkeit für die Spalte basierend auf dem, was in der Mapped-Annotation vorhanden ist, ableiten kann. Sie kann auch ohne Annotationen als direkter Ersatz für die Verwendung von Column in Deklarativen Zuordnungen im SQLAlchemy 1.x-Stil verwendet werden.

Verwendungsbeispiele für mapped_column() finden Sie in der Dokumentation unter Deklarative Tabelle mit mapped_column().

Siehe auch

Deklarative Tabelle mit mapped_column() - vollständige Dokumentation

ORM Deklarative Modelle - Migrationhinweise für Deklarative Zuordnungen mit Zuordnungen im 1.x-Stil

Parameter:

__name¶ – Der Zeichenkettenname, der der Column gegeben wird. Dies ist ein optionales, nur positionelles Argument, das, wenn es vorhanden ist, das erste übergebene positionelle Argument sein muss. Wenn es weggelassen wird, wird der Attributname, dem mapped_column() zugeordnet ist, als SQL-Spaltenname verwendet.
__type¶ – TypeEngine-Typ oder -Instanz, die den Datentyp angibt, der der Column zugeordnet werden soll. Dies ist ein optionales, nur positionelles Argument, das, wenn es vorhanden ist, unmittelbar nach dem Parameter __name, falls ebenfalls vorhanden, oder andernfalls das erste positionelle Argument sein muss. Wenn es weggelassen wird, kann der endgültige Typ der Spalte entweder aus dem annotierten Typ abgeleitet werden oder, wenn ein ForeignKey vorhanden ist, aus dem Datentyp der referenzierten Spalte.
*args¶ – Zusätzliche positionelle Argumente umfassen Konstrukte wie ForeignKey, CheckConstraint und Identity, die an die konstruierte Column weitergegeben werden.
nullable¶ – Optionales bool, ob die Spalte „NULL“ oder „NOT NULL“ sein soll. Wenn weggelassen, wird die Nullbarkeit aus der Typannotation abgeleitet, basierend darauf, ob typing.Optional vorhanden ist. nullable ist standardmäßig True für Nicht-Primärschlüsselspalten und False für Primärschlüsselspalten.
primary_key¶ – optionales bool, gibt an, ob die Column Teil des Primärschlüssels der Tabelle ist oder nicht.
deferred¶ –
Optionales bool - dieses Schlüsselwortargument wird vom ORM-Deklarationsprozess verbraucht und ist kein Teil der Column selbst; stattdessen zeigt es an, dass diese Spalte für das Laden "verzögert" werden soll, als ob sie von deferred() zugeordnet wäre.

Siehe auch

Spaltenverzögerung auf Mappings konfigurieren
deferred_group¶ –
Impliziert mapped_column.deferred zu True und setzt den Parameter deferred.group.

Siehe auch

Verzögerte Spalten in Gruppen laden
deferred_raiseload¶ –
Impliziert mapped_column.deferred zu True und setzt den Parameter deferred.raiseload.

Siehe auch

raiseload verwenden, um das Laden verzögerter Spalten zu verhindern
use_existing_column¶ –
Wenn True, wird versucht, den angegebenen Spaltennamen auf einer geerbten Superklasse (typischerweise einer einzelnen vererbten Superklasse) zu finden. Wenn vorhanden, wird keine neue Spalte erzeugt, sondern auf die Spalte der Superklasse gemappt, als wäre sie in dieser Klasse weggelassen worden. Dies wird für Mixins verwendet, die neue Spalten zu einer geerbten Superklasse hinzufügen.

Siehe auch

Auflösung von Spaltenkonflikten mit use_existing_column

Neu ab Version 2.0.0b4.
default¶ –
Wird direkt an den Parameter Column.default übergeben, wenn der Parameter mapped_column.insert_default nicht vorhanden ist. Wenn er mit Deklarative Dataclass-Abbildung verwendet wird, gibt er zusätzlich einen Standard-Python-Wert an, der auf den Schlüsselwortkonstruktor in der generierten __init__()-Methode angewendet werden soll.

Beachten Sie, dass im Falle der Dataclass-Generierung, wenn mapped_column.insert_default nicht vorhanden ist, der Wert von mapped_column.default an **zwei** Stellen verwendet wird, sowohl in der __init__()-Methode als auch im Parameter Column.default. Obwohl sich dieses Verhalten in einer zukünftigen Version ändern kann, funktioniert es derzeit in der Regel gut. Ein Standardwert von None bedeutet, dass die Column keinen Standard-Generator erhält, während ein Wert, der auf einem nicht-None Python- oder SQL-Ausdruckswert verweist, beim Aufruf von __init__() im Voraus auf das Objekt angewendet wird, was derselbe Wert ist, den die Core Insert-Konstruktion ohnehin verwenden würde, was zum gleichen Endergebnis führt.

Hinweis

Bei Verwendung von Core-Spalten-Standardwerten, die aufrufbare Funktionen sind und von der zugrunde liegenden Column interpretiert werden sollen, in Verbindung mit ORM-abgebildeten Dataclasses, insbesondere bei **kontextabhängigen Standardfunktionen**, **muss stattdessen der Parameter mapped_column.insert_default verwendet werden**. Dies ist notwendig, um die aufrufbare Funktion von der Interpretation als Standardwert auf Dataclass-Ebene zu unterscheiden.

Siehe auch

Was sind default, default_factory und insert_default und was sollte ich verwenden?

mapped_column.insert_default

mapped_column.default_factory
insert_default¶ –
Wird direkt an den Parameter Column.default übergeben; überschreibt den Wert von mapped_column.default, wenn vorhanden. mapped_column.default gilt jedoch immer für den Konstruktor-Standardwert für eine Dataclass-Abbildung.

Siehe auch

Was sind default, default_factory und insert_default und was sollte ich verwenden?

mapped_column.default

mapped_column.default_factory
sort_order¶ –
Eine ganze Zahl, die angibt, wie diese abgebildete Spalte im Vergleich zu anderen sortiert werden soll, wenn die ORM eine Table erstellt. Unter abgebildeten Spalten mit demselben Wert wird die Standardreihenfolge verwendet, wobei zuerst die in der Hauptklasse definierten, dann die in den Superklassen definierten abgebildeten Spalten platziert werden. Standardwert ist 0. Die Sortierung ist aufsteigend.

Neu seit Version 2.0.4.
active_history=False¶ –
Wenn True, zeigt dies an, dass der "vorherige" Wert für ein Skalarattribut geladen werden soll, wenn er ersetzt wird und noch nicht geladen ist. Normalerweise muss die Verfolgung des Verlaufs für einfache Skalarwerte, die keine Primärschlüssel sind, nur den "neuen" Wert kennen, um einen Flush durchzuführen. Dieses Flag ist für Anwendungen verfügbar, die get_history() oder Session.is_modified() verwenden und auch den "vorherigen" Wert des Attributs kennen müssen.

Neu in Version 2.0.10.
init¶ – Spezifisch für die Deklarative Dataclass-Abbildung, gibt an, ob das abgebildete Attribut Teil der von __init__() generierten Methode sein soll, wie sie vom Dataclass-Prozess erstellt wird.
repr¶ – Spezifisch für die Deklarative Dataclass-Abbildung, gibt an, ob das abgebildete Attribut Teil der von __repr__() generierten Methode sein soll, wie sie vom Dataclass-Prozess erstellt wird.
default_factory¶ –
Spezifisch für Deklaratives Mapping von Datenklassen, gibt eine Funktion zur Generierung von Standardwerten an, die als Teil der von der Datenklasse generierten __init__()-Methode ausgeführt wird.

Siehe auch

Was sind default, default_factory und insert_default und was sollte ich verwenden?

mapped_column.default

mapped_column.insert_default
compare¶ –
Spezifisch für Deklaratives Mapping von Datenklassen, gibt an, ob dieses Feld bei der Generierung der Methoden __eq__() und __ne__() für die zugeordnete Klasse in Vergleichsoperationen einbezogen werden soll.

Neu ab Version 2.0.0b4.
kw_only¶ – Spezifisch für die Deklarative Dataclass-Abbildung, gibt an, ob dieses Feld beim Generieren von __init__() als nur-Schlüsselwort-Argument markiert werden soll.
hash¶ –
Spezifisch für Deklaratives Mapping von Datenklassen, steuert, ob dieses Feld bei der Generierung der __hash__()-Methode für die zugeordnete Klasse einbezogen wird.

Neu in Version 2.0.36.
**kw¶ – Alle verbleibenden Schlüsselwortargumente werden an den Konstruktor für die Column weitergegeben.

class sqlalchemy.orm.declared_attr¶

Markiert eine klassenbezogene Methode als Definition einer zugeordneten Eigenschaft oder einer deklarativen Direktive.

declared_attr wird typischerweise als Dekorator auf eine Klassenmethode angewendet und wandelt das Attribut in eine skalarähnliche Eigenschaft um, die von der nicht instanziierten Klasse aus aufgerufen werden kann. Der Deklarative Abbildungsprozess sucht nach diesen declared_attr-Aufrufbaren, während er Klassen scannt, und geht davon aus, dass jedes mit declared_attr markierte Attribut eine aufrufbare Funktion ist, die ein für die Deklarative Abbildung oder Tabellenkonfiguration spezifisches Objekt erzeugt.

declared_attr ist normalerweise auf Mixins anwendbar, um Beziehungen zu definieren, die auf verschiedene Implementierer der Klasse angewendet werden sollen. Es kann auch verwendet werden, um dynamisch generierte Spaltenausdrücke und andere deklarative Attribute zu definieren.

Beispiel

class ProvidesUserMixin:
    "A mixin that adds a 'user' relationship to classes."

    user_id: Mapped[int] = mapped_column(ForeignKey("user_table.id"))

    @declared_attr
    def user(cls) -> Mapped["User"]:
        return relationship("User")

Bei Verwendung mit deklarativen Direktiven wie __tablename__ kann der Modifikator declared_attr.directive() verwendet werden, der PEP 484-Typ-Tools mitteilt, dass die gegebene Methode nicht mit Mapped-Attributen arbeitet.

class CreateTableName:
    @declared_attr.directive
    def __tablename__(cls) -> str:
        return cls.__name__.lower()

declared_attr kann auch direkt auf abgebildete Klassen angewendet werden, um Attribute zu ermöglichen, die sich beim Verwenden von abgebildeten Vererbungsschemata dynamisch auf Unterklassen konfigurieren. Das Folgende veranschaulicht declared_attr zur Erstellung eines dynamischen Schemas zur Generierung des Parameters Mapper.polymorphic_identity für Unterklassen.

class Employee(Base):
    __tablename__ = "employee"

    id: Mapped[int] = mapped_column(primary_key=True)
    type: Mapped[str] = mapped_column(String(50))

    @declared_attr.directive
    def __mapper_args__(cls) -> Dict[str, Any]:
        if cls.__name__ == "Employee":
            return {
                "polymorphic_on": cls.type,
                "polymorphic_identity": "Employee",
            }
        else:
            return {"polymorphic_identity": cls.__name__}


class Engineer(Employee):
    pass

declared_attr unterstützt das Dekorieren von Funktionen, die explizit mit @classmethod dekoriert sind. Dies ist aus Laufzeitperspektive niemals notwendig, kann jedoch zur Unterstützung von PEP 484-Typ-Tools erforderlich sein, die die dekorierte Funktion andernfalls nicht als Klassen-Level-Verhalten für den Parameter cls erkennen.

class SomethingMixin:
    x: Mapped[int]
    y: Mapped[int]

    @declared_attr
    @classmethod
    def x_plus_y(cls) -> Mapped[int]:
        return column_property(cls.x + cls.y)

Neu in Version 2.0: - declared_attr kann eine Funktion, die mit @classmethod dekoriert ist, aufnehmen, um die PEP 484-Integration bei Bedarf zu unterstützen.

Siehe auch

Zusammensetzen von abgebildeten Hierarchien mit Mixins - Dokumentation zu deklarativen Mixins mit Hintergrundinformationen zu Verwendungsmustern für declared_attr.

Mitglieder

cascading, directive

Klassensignatur

class sqlalchemy.orm.declared_attr (sqlalchemy.orm.base._MappedAttribute, sqlalchemy.orm.decl_api._declared_attr_common)

attribute sqlalchemy.orm.declared_attr.cascading¶

Markiert ein declared_attr als kaskadierend.

Dies ist ein Modifikator für spezielle Anwendungsfälle, der angibt, dass ein auf Spalten oder MapperProperty basierendes deklariertes Attribut für jede abgebildete Unterklasse in einem abgebildeten Vererbungsszenario unterschiedlich konfiguriert werden soll.

Warnung

Der Modifikator declared_attr.cascading hat mehrere Einschränkungen

Das Flag gilt **nur** für die Verwendung von declared_attr auf deklarativen Mixin-Klassen und __abstract__-Klassen; es hat derzeit keine Auswirkung, wenn es direkt auf einer abgebildeten Klasse verwendet wird.
Das Flag gilt **nur** für normal benannte Attribute, d. h. nicht für spezielle Unterstrich-Attribute wie __tablename__. Auf diese Attribute hat es **keine** Auswirkung.
Das Flag **lässt derzeit keine weiteren Überschreibungen** in der Klassenhierarchie zu; wenn eine Unterklasse versucht, das Attribut zu überschreiben, wird eine Warnung ausgegeben und das überschriebene Attribut wird übersprungen. Dies ist eine Einschränkung, von der gehofft wird, dass sie irgendwann behoben wird.

Unten erhalten sowohl MyClass als auch MySubClass eine eigene id Column-Objektinstanziierung unter dem Attributnamen some_id.

class HasIdMixin:
    @declared_attr.cascading
    def id(cls) -> Mapped[int]:
        if has_inherited_table(cls):
            return mapped_column(ForeignKey("myclass.id"), primary_key=True)
        else:
            return mapped_column(Integer, primary_key=True)


class MyClass(HasIdMixin, Base):
    __tablename__ = "myclass"
    # ...


class MySubClass(MyClass):
    """ """

    # ...

Das Verhalten der obigen Konfiguration ist, dass MySubClass sowohl auf seine eigene id Spalte als auch auf die von MyClass unter dem Attributnamen some_id verweist.

Siehe auch

Deklarative Vererbung

Verwendung von _orm.declared_attr() zur Generierung Tabellen-spezifischer, vererbender Spalten

attribute sqlalchemy.orm.declared_attr.directive¶

Markiert ein declared_attr als Dekorator für eine deklarative Direktive wie __tablename__ oder __mapper_args__.

Der Zweck von declared_attr.directive ist ausschließlich die Unterstützung von PEP 484-Typ-Tools, indem der dekorierten Funktion ein Rückgabetyp gestattet wird, der **nicht** die generische Klasse Mapped verwendet, wie es normalerweise der Fall wäre, wenn declared_attr für Spalten und abgebildete Eigenschaften verwendet wird. Zur Laufzeit gibt declared_attr.directive die Klasse declared_attr unverändert zurück.

Z. B.

class CreateTableName:
    @declared_attr.directive
    def __tablename__(cls) -> str:
        return cls.__name__.lower()

Neu in Version 2.0.

Siehe auch

Zusammensetzen von gemappten Hierarchien mit Mixins

declared_attr

class sqlalchemy.orm.DeclarativeBase¶

Basisklasse für deklarative Klassendefinitionen.

Die Klasse DeclarativeBase ermöglicht die Erstellung neuer deklarativer Basen auf eine Weise, die mit Typ-Checkern kompatibel ist.

from sqlalchemy.orm import DeclarativeBase


class Base(DeclarativeBase):
    pass

Die obige Klasse Base kann nun als Basis für neue deklarative Abbildungen verwendet werden. Die Oberklasse nutzt die Methode __init_subclass__(), um neue Klassen einzurichten, und es werden keine Metaklassen verwendet.

Bei der ersten Verwendung instanziiert die Klasse DeclarativeBase eine neue registry, die mit der Basis verwendet werden soll, vorausgesetzt, es wurde keine explizit bereitgestellt. Die Klasse DeclarativeBase unterstützt Klassen-Level-Attribute, die als Parameter für die Konstruktion dieser Registrierung dienen; beispielsweise, um eine spezifische MetaData-Sammlung sowie einen spezifischen Wert für registry.type_annotation_map anzugeben.

from typing_extensions import Annotated

from sqlalchemy import BigInteger
from sqlalchemy import MetaData
from sqlalchemy import String
from sqlalchemy.orm import DeclarativeBase

bigint = Annotated[int, "bigint"]
my_metadata = MetaData()


class Base(DeclarativeBase):
    metadata = my_metadata
    type_annotation_map = {
        str: String().with_variant(String(255), "mysql", "mariadb"),
        bigint: BigInteger(),
    }

Als Klassen-Level-Attribute können spezifiziert werden:

Parameter:

metadata¶ – optionale MetaData-Sammlung. Wenn eine registry automatisch konstruiert wird, wird diese MetaData-Sammlung zur Konstruktion verwendet. Andernfalls überschreibt die lokale MetaData-Sammlung diejenige, die von einer vorhandenen registry verwendet wird, die über den Parameter DeclarativeBase.registry übergeben wird.
type_annotation_map¶ – optionale Typen-Annotationszuordnung, die an die registry als registry.type_annotation_map übergeben wird.
registry¶ – liefert eine bereits existierende registry direkt.

Neu in Version 2.0: Hinzugefügt wurde DeclarativeBase, damit deklarative Basisklassen so konstruiert werden können, dass sie auch von PEP 484-Typ-Checkern erkannt werden. Infolgedessen werden DeclarativeBase und andere subclassing-orientierte APIs als Nachfolger früherer "von einer Funktion zurückgegebene Klasse"-APIs angesehen, nämlich declarative_base() und registry.generate_base(), bei denen die zurückgegebene Basisklasse von Typ-Checkern ohne Verwendung von Plugins nicht erkannt werden konnte.

__init__ Verhalten

In einer reinen Python-Klasse ist die Basis-`__init__()`-Methode in der Klassenhierarchie object.__init__(), die keine Argumente akzeptiert. Wenn jedoch die Unterklasse DeclarativeBase zum ersten Mal deklariert wird, erhält die Klasse eine __init__()-Methode, die mit der Konstruktorfunktion registry.constructor verknüpft ist, falls keine __init__()-Methode bereits vorhanden ist. Dies ist der übliche deklarative Konstruktor, der Schlüsselwortargumente als Attribute auf der Instanz zuweist, vorausgesetzt, diese Attribute sind auf Klassenebene definiert (d.h. sie sind abgebildet oder mit einem Deskriptor verknüpft). Dieser Konstruktor wird **niemals von einer abgebildeten Klasse aufgerufen, ohne explizit über super() aufgerufen zu werden**, da abgebildete Klassen selbst direkt eine __init__()-Methode erhalten, die registry.constructor aufruft. Im Standardfall funktioniert dies also unabhängig davon, was die Basis-`__init__()`-Methode tut.

Geändert in Version 2.0.1: DeclarativeBase hat standardmäßig einen Konstruktor, der mit registry.constructor verknüpft ist, sodass Aufrufe von super().__init__() auf diesen Konstruktor zugreifen können. Zuvor fehlte dieser Standardkonstruktor aufgrund eines Implementierungsfehlers, und der Aufruf von super().__init__() rief object.__init__() auf.

Die Unterklasse DeclarativeBase kann auch eine explizite __init__()-Methode deklarieren, die die Verwendung der Funktion registry.constructor auf dieser Ebene ersetzt.

class Base(DeclarativeBase):
    def __init__(self, id=None):
        self.id = id

Abgebildete Klassen rufen diesen Konstruktor immer noch nicht implizit auf; er ist nur über den Aufruf von super().__init__() zugänglich.

class MyClass(Base):
    def __init__(self, id=None, name=None):
        self.name = name
        super().__init__(id=id)

Beachten Sie, dass dies ein anderes Verhalten ist als das, was Funktionen wie das Legacy declarative_base() tun würden; die von diesen Funktionen erstellte Basis würde immer registry.constructor für __init__() installieren.

Mitglieder

__mapper__, __mapper_args__, __table__, __table_args__, __tablename__, metadata, registry

Klassensignatur

class sqlalchemy.orm.DeclarativeBase (sqlalchemy.inspection.Inspectable)

attribute sqlalchemy.orm.DeclarativeBase.__mapper__: ClassVar[Mapper[Any]]¶

Das Mapper-Objekt, an das eine bestimmte Klasse abgebildet wird.

Kann auch über inspect() bezogen werden, z. B. inspect(klass).

attribute sqlalchemy.orm.DeclarativeBase.__mapper_args__: Any¶: Wörterbuch von Argumenten, die an den Konstruktor von Mapper übergeben werden.

Siehe auch

Mapper-Konfigurationsoptionen mit Deklarativ

attribute sqlalchemy.orm.DeclarativeBase.__table__: ClassVar[FromClause]¶

Die FromClause, der eine bestimmte Unterklasse zugeordnet wird.

Dies ist normalerweise eine Instanz von Table, kann aber auch auf andere Arten von FromClause verweisen, wie z.B. Subquery, abhängig davon, wie die Klasse abgebildet wird.

Siehe auch

Zugriff auf Tabelle und Metadaten

attribute sqlalchemy.orm.DeclarativeBase.__table_args__: Any¶: Ein Wörterbuch oder eine Tupel von Argumenten, die an den Konstruktor von Table übergeben werden. Siehe Deklarative Tabellenkonfiguration für Hintergrundinformationen zur spezifischen Struktur dieser Sammlung.

Siehe auch

Deklarative Tabellenkonfiguration

attribute sqlalchemy.orm.DeclarativeBase.__tablename__: Any¶: Name der Zeichenkette, der das generierte Table-Objekt zugewiesen werden soll, falls nicht direkt über DeclarativeBase.__table__ angegeben.

Siehe auch

Deklarative Tabelle mit mapped_column()

attribute sqlalchemy.orm.DeclarativeBase.metadata: ClassVar[MetaData]¶: Bezieht sich auf die MetaData-Sammlung, die für neue Table-Objekte verwendet wird.

Siehe auch

Zugriff auf Tabelle und Metadaten

attribute sqlalchemy.orm.DeclarativeBase.registry: ClassVar[registry]¶: Bezieht sich auf die verwendete registry, mit der neue Mapper-Objekte verknüpft werden.

class sqlalchemy.orm.DeclarativeBaseNoMeta¶

Dasselbe wie DeclarativeBase, verwendet aber keine Metaklasse, um neue Attribute abzufangen.

Die Basisklasse DeclarativeBaseNoMeta kann verwendet werden, wenn die Verwendung benutzerdefinierter Metaklassen erwünscht ist.

Neu in Version 2.0.

Mitglieder

__mapper__, __mapper_args__, __table__, __table_args__, __tablename__, metadata, registry

Klassensignatur

class sqlalchemy.orm.DeclarativeBaseNoMeta (sqlalchemy.inspection.Inspectable)

Attribut sqlalchemy.orm.DeclarativeBaseNoMeta.__mapper__: ClassVar[Mapper[Any]]¶

Das Mapper-Objekt, an das eine bestimmte Klasse abgebildet wird.

Kann auch über inspect() bezogen werden, z. B. inspect(klass).

Attribut sqlalchemy.orm.DeclarativeBaseNoMeta.__mapper_args__: Any¶: Wörterbuch von Argumenten, die an den Konstruktor von Mapper übergeben werden.

Siehe auch

Mapper-Konfigurationsoptionen mit Deklarativ

Attribut sqlalchemy.orm.DeclarativeBaseNoMeta.__table__: FromClause | None¶

Die FromClause, der eine bestimmte Unterklasse zugeordnet wird.

Dies ist normalerweise eine Instanz von Table, kann aber auch auf andere Arten von FromClause verweisen, wie z.B. Subquery, abhängig davon, wie die Klasse abgebildet wird.

Siehe auch

Zugriff auf Tabelle und Metadaten

Attribut sqlalchemy.orm.DeclarativeBaseNoMeta.__table_args__: Any¶: Ein Wörterbuch oder eine Tupel von Argumenten, die an den Konstruktor von Table übergeben werden. Siehe Deklarative Tabellenkonfiguration für Hintergrundinformationen zur spezifischen Struktur dieser Sammlung.

Siehe auch

Deklarative Tabellenkonfiguration

Attribut sqlalchemy.orm.DeclarativeBaseNoMeta.__tablename__: Any¶: Name der Zeichenkette, der das generierte Table-Objekt zugewiesen werden soll, falls nicht direkt über DeclarativeBase.__table__ angegeben.

Siehe auch

Deklarative Tabelle mit mapped_column()

Attribut sqlalchemy.orm.DeclarativeBaseNoMeta.metadata: ClassVar[MetaData]¶: Bezieht sich auf die MetaData-Sammlung, die für neue Table-Objekte verwendet wird.

Siehe auch

Zugriff auf Tabelle und Metadaten

Attribut sqlalchemy.orm.DeclarativeBaseNoMeta.registry: ClassVar[registry]¶: Bezieht sich auf die verwendete registry, mit der neue Mapper-Objekte verknüpft werden.

Funktion sqlalchemy.orm.has_inherited_table(cls: Type[_O]) → bool¶

Gibt True zurück, wenn eine der Klassen, von denen die gegebene Klasse erbt, eine zugeordnete Tabelle hat, andernfalls False.

Dies wird in deklarativen Mixins verwendet, um Attribute zu erstellen, die sich für die Basisklasse im Vergleich zu einer Unterklasse einer Vererbungshierarchie unterschiedlich verhalten.

Siehe auch

Verwendung von Mixins und Basisklassen mit Mapped Inheritance Mustern

Funktion sqlalchemy.orm.synonym_for(name: str, map_column: bool = False) → Callable[[Callable[[...], Any]], Synonym[Any]]¶

Dekorator, der ein synonym()-Attribut in Verbindung mit einem Python-Deskriptor erzeugt.

Die dekorierte Funktion wird als Parameter synonym.descriptor an synonym() übergeben

class MyClass(Base):
    __tablename__ = "my_table"

    id = Column(Integer, primary_key=True)
    _job_status = Column("job_status", String(50))

    @synonym_for("job_status")
    @property
    def job_status(self):
        return "Status: %s" % self._job_status

Das Feature Hybrid Properties von SQLAlchemy wird in der Regel Synomymen vorgezogen, da dies ein älteres Feature ist.

Siehe auch

Synonyme - Übersicht über Synonyme

synonym() - die mapper-Level-Funktion

Verwendung von Deskriptoren und Hybriden - Die Hybrid-Attribut-Erweiterung bietet einen aktualisierten Ansatz zur flexibleren Erweiterung des Attributverhaltens, als dies mit Synonymen möglich ist.

Funktion sqlalchemy.orm.object_mapper(instance: _T) → Mapper[_T]¶

Gibt für ein Objekt den primären Mapper zurück, der der Objektinstanz zugeordnet ist.

Löst sqlalchemy.orm.exc.UnmappedInstanceError aus, wenn keine Zuordnung konfiguriert ist.

Diese Funktion ist über das Inspektionssystem verfügbar als

inspect(instance).mapper

Die Verwendung des Inspektionssystems löst sqlalchemy.exc.NoInspectionAvailable aus, wenn die Instanz nicht Teil einer Zuordnung ist.

Funktion sqlalchemy.orm.class_mapper(class_: Type[_O], configure: bool = True) → Mapper[_O]¶

Gibt für eine Klasse den primären Mapper zurück, der mit dem Schlüssel assoziiert ist.

Löst UnmappedClassError aus, wenn keine Zuordnung für die gegebene Klasse konfiguriert ist, oder ArgumentError, wenn ein Nicht-Klasse-Objekt übergeben wird.

Äquivalente Funktionalität ist über die Funktion inspect() verfügbar als

inspect(some_mapped_class)

Die Verwendung des Inspektionssystems löst sqlalchemy.exc.NoInspectionAvailable aus, wenn die Klasse nicht zugeordnet ist.

Funktion sqlalchemy.orm.configure_mappers() → None¶

Initialisiert die Beziehungen zwischen den Makern aller bisher in allen registry-Sammlungen konstruierten Makern.

Der Konfigurationsschritt dient dazu, die relationship()-Verknüpfungen zwischen zugeordneten Klassen abzugleichen und zu initialisieren, sowie Konfigurationsereignisse aufzurufen, wie z. B. MapperEvents.before_configured() und MapperEvents.after_configured(), die von ORM-Erweiterungen oder benutzerdefinierten Erweiterungshooks verwendet werden können.

Die Mapper-Konfiguration wird normalerweise automatisch aufgerufen, wenn Zuordnungen aus einer bestimmten registry zum ersten Mal verwendet werden, sowie immer dann, wenn Zuordnungen verwendet werden und zusätzliche, noch nicht konfigurierte Mapper erstellt wurden. Der automatische Konfigurationsprozess ist jedoch nur lokal für die registry, die den Zielmapper und alle damit verbundenen registry-Objekte, von denen sie abhängen könnte, umfasst; dies entspricht dem Aufruf der Methode registry.configure() für eine bestimmte registry.

Im Gegensatz dazu ruft die Funktion configure_mappers() den Konfigurationsprozess für alle im Speicher vorhandenen registry-Objekte auf und kann für Szenarien nützlich sein, in denen viele einzelne registry-Objekte, die dennoch miteinander verbunden sind, verwendet werden.

Geändert in Version 1.4: Ab SQLAlchemy 1.4.0b2 funktioniert diese Funktion pro registry, findet alle vorhandenen registry-Objekte und ruft die Methode registry.configure() für jedes auf. Die Methode registry.configure() kann bevorzugt werden, um die Konfiguration von Mappern auf diejenigen zu beschränken, die einer bestimmten registry und/oder einer deklarativen Basisklasse zugeordnet sind.

Zeitpunkte, zu denen die automatische Konfiguration aufgerufen wird, sind, wenn eine zugeordnete Klasse in eine Instanz instanziiert wird, sowie wenn ORM-Abfragen mit Session.query() oder Session.execute() mit einer ORM-aktivierten Anweisung gesendet werden.

Der Mapper-Konfigurationsprozess, egal ob aufgerufen durch configure_mappers() oder aus registry.configure(), bietet mehrere Ereignishaken, die verwendet werden können, um den Mapper-Konfigurationsschritt zu erweitern. Diese Haken umfassen

MapperEvents.before_configured() - wird einmal aufgerufen, bevor configure_mappers() oder registry.configure() irgendeine Arbeit verrichtet; dies kann verwendet werden, um zusätzliche Optionen, Eigenschaften oder verwandte Zuordnungen festzulegen, bevor der Vorgang fortgesetzt wird.
MapperEvents.mapper_configured() - wird aufgerufen, wenn jeder einzelne Mapper im Prozess konfiguriert wird; beinhaltet den gesamten Mapper-Status außer Backrefs, die von anderen noch zu konfigurierenden Mappern gesetzt wurden.
MapperEvents.after_configured() - wird einmal aufgerufen, nachdem configure_mappers() oder registry.configure() abgeschlossen ist; zu diesem Zeitpunkt sind alle Mapper-Objekte, die in den Geltungsbereich der Konfigurationsoperation fallen, vollständig konfiguriert. Beachten Sie, dass die aufrufende Anwendung möglicherweise noch andere Zuordnungen hat, die noch nicht erstellt wurden, z. B. wenn sie sich in noch nicht importierten Modulen befinden, und auch Zuordnungen, die noch konfiguriert werden müssen, wenn sie sich in anderen registry-Sammlungen befinden, die nicht Teil des aktuellen Konfigurationsumfangs sind.

Funktion sqlalchemy.orm.clear_mappers() → None¶

Entfernt alle Mapper aus allen Klassen.

Geändert in Version 1.4: Diese Funktion findet nun alle registry-Objekte und ruft die Methode registry.dispose() für jedes auf.

Diese Funktion entfernt die gesamte Instrumentierung von Klassen und verwirft ihre zugehörigen Mapper. Nach dem Aufruf sind die Klassen entmapped und können später mit neuen Mappern neu zugeordnet werden.

clear_mappers() ist **nicht** für den normalen Gebrauch bestimmt, da es absolut keinen gültigen Verwendungszweck außerhalb sehr spezifischer Testszenarien gibt. Normalerweise sind Mapper permanente strukturelle Komponenten von benutzerdefinierten Klassen und werden nie unabhängig von ihrer Klasse verworfen. Wenn eine zugeordnete Klasse selbst vom Garbage Collector gesammelt wird, wird auch ihr Mapper automatisch verworfen. Daher ist clear_mappers() nur für die Verwendung in Testsuiten bestimmt, die dieselben Klassen mit unterschiedlichen Zuordnungen wiederverwenden, was an sich ein extrem seltener Anwendungsfall ist - der einzige solche Anwendungsfall ist in der Tat die eigene Testsuite von SQLAlchemy und möglicherweise die Testsuiten anderer ORM-Erweiterungsbibliotheken, die verschiedene Kombinationen von Mapper-Konstruktionen auf einem festen Satz von Klassen testen möchten.

Erzeugt „Identitätsschlüssel“-Tupel, wie sie als Schlüssel im Wörterbuch Session.identity_map verwendet werden.

Diese Funktion hat mehrere Aufrufstile

identity_key(class, ident, identity_token=token)

Diese Form empfängt eine zugeordnete Klasse und einen Primärschlüssel-Skalar oder ein Tupel als Argument.

Z. B.
```
>>> identity_key(MyClass, (1, 2))
(<class '__main__.MyClass'>, (1, 2), None)
```
param class:

zugeordnete Klasse (muss ein positionelles Argument sein)

param ident:

Primärschlüssel, kann ein Skalar- oder Tupelargument sein.

param identity_token:

optionales Identitätstoken

Neu in Version 1.2: identity_token hinzugefügt
identity_key(instance=instance)

Diese Form erzeugt den Identitätsschlüssel für eine gegebene Instanz. Die Instanz muss nicht persistent sein, nur ihre Primärschlüsselattribute müssen gefüllt sein (andernfalls enthält der Schlüssel für fehlende Werte None).

Z. B.
```
>>> instance = MyClass(1, 2)
>>> identity_key(instance=instance)
(<class '__main__.MyClass'>, (1, 2), None)
```
In dieser Form wird die gegebene Instanz schließlich durch Mapper.identity_key_from_instance() ausgeführt, was zur Folge hat, dass eine Datenbankprüfung für die entsprechende Zeile durchgeführt wird, wenn das Objekt abgelaufen ist.

param instance:

Objektinstanz (muss als Schlüsselwortargument übergeben werden)
identity_key(class, row=row, identity_token=token)

Diese Form ist ähnlich der Klasse/Tupel-Form, empfängt aber stattdessen eine Datenbankergebniszeile als Objekt Row oder RowMapping.

Z. B.
```
>>> row = engine.execute(text("select * from table where a=1 and b=2")).first()
>>> identity_key(MyClass, row=row)
(<class '__main__.MyClass'>, (1, 2), None)
```
param class:

zugeordnete Klasse (muss ein positionelles Argument sein)

param row:

Row-Zeile, die von einem CursorResult zurückgegeben wurde (muss als Schlüsselwortargument übergeben werden)

param identity_token:

optionales Identitätstoken

Neu in Version 1.2: identity_token hinzugefügt

Funktion sqlalchemy.orm.polymorphic_union(table_map, typecolname, aliasname='p_union', cast_nulls=True)¶

Erstellt eine UNION-Anweisung, die von einem polymorphen Mapper verwendet wird.

Siehe Concrete Table Inheritance für ein Beispiel, wie dies verwendet wird.

Parameter:

table_map¶ – Zuordnung von polymorphen Identitäten zu Table-Objekten.
typecolname¶ – Zeichenkettenname einer "Diskriminator"-Spalte, die aus der Abfrage abgeleitet wird und die polymorphe Identität für jede Zeile erzeugt. Wenn None, wird kein polymorpher Diskriminator generiert.
aliasname¶ – Name des generierten alias()-Konstrukts.
cast_nulls¶ – wenn True, werden nicht vorhandene Spalten, die als beschriftete NULLs dargestellt werden, in eine CAST eingefügt. Dies ist ein Legacy-Verhalten, das auf einigen Backends wie Oracle problematisch ist - in diesem Fall kann es auf False gesetzt werden.

Funktion sqlalchemy.orm.orm_insert_sentinel(name: str | None = None, type_: _TypeEngineArgument[Any] | None = None, *, default: Any | None = None, omit_from_statements: bool = True) → MappedColumn[Any]¶

Bietet eine Ersatz-mapped_column(), die eine sogenannte Sentinel-Spalte generiert, was effiziente Masseneinfügungen mit deterministischer RETURNING-Sortierung für Tabellen ermöglicht, die anderweitig keine qualifizierenden Primärschlüsselkonfigurationen haben.

Die Verwendung von orm_insert_sentinel() ist analog zur Verwendung des insert_sentinel() Konstrukts innerhalb eines Core Table Konstrukts.

Die Richtlinien für die Hinzufügung dieses Konstrukts zu einer deklarativen zugeordneten Klasse sind die gleichen wie für das insert_sentinel() Konstrukt; die Datenbanktabelle selbst muss ebenfalls eine Spalte mit diesem Namen enthalten.

Hintergrundinformationen zur Verwendung dieses Objekts finden Sie im Abschnitt Konfiguration von Sentinel-Spalten als Teil des Abschnitts Verhalten "Insert Many Values" für INSERT-Anweisungen.

Siehe auch

insert_sentinel()

„Insert Many Values“-Verhalten für INSERT-Anweisungen

Konfiguration von Sentinel-Spalten

Neu in Version 2.0.10.

funktion sqlalchemy.orm.reconstructor(fn)¶

Dekoriert eine Methode als „Rekonstruktor“-Hook.

Bezeichnet eine einzelne Methode als "reconstructor", eine __init__-ähnliche Methode, die vom ORM aufgerufen wird, nachdem die Instanz aus der Datenbank geladen oder anderweitig wiederhergestellt wurde.

Tipp

Der Dekorator reconstructor() nutzt den InstanceEvents.load() Event-Hook, der direkt verwendet werden kann.

Der Reconstructor wird ohne Argumente aufgerufen. Skalare (nicht-kollektionelle) datenbankabgebildete Attribute der Instanz sind innerhalb der Funktion verfügbar. Eagerly-loaded Collections sind im Allgemeinen noch nicht verfügbar und enthalten normalerweise nur das erste Element. ORM-Zustandsänderungen, die an Objekten in diesem Stadium vorgenommen werden, werden nicht für die nächste flush()-Operation aufgezeichnet, daher sollte die Aktivität innerhalb eines Reconstructors konservativ sein.

Siehe auch

InstanceEvents.load()

klasse sqlalchemy.orm.Mapper¶

Definiert eine Zuordnung zwischen einer Python-Klasse und einer Datenbanktabelle oder einer anderen relationalen Struktur, damit ORM-Operationen auf der Klasse durchgeführt werden können.

Das Mapper Objekt wird mithilfe von Mapping-Methoden des registry Objekts instanziiert. Informationen zur Instanziierung neuer Mapper Objekte finden Sie unter Übersicht über ORM Mapped Classes.

Klassensignatur

class sqlalchemy.orm.Mapper (sqlalchemy.orm.ORMFromClauseRole, sqlalchemy.orm.ORMEntityColumnsClauseRole, sqlalchemy.sql.cache_key.MemoizedHasCacheKey, sqlalchemy.orm.base.InspectionAttr, sqlalchemy.log.Identified, sqlalchemy.inspection.Inspectable, sqlalchemy.event.registry.EventTarget, typing.Generic)

methode sqlalchemy.orm.Mapper.__init__(class_: Type[_O], local_table: FromClause | None = None, properties: Mapping[str, MapperProperty[Any]] | None = None, primary_key: Iterable[_ORMColumnExprArgument[Any]] | None = None, non_primary: bool = False, inherits: Mapper[Any] | Type[Any] | None = None, inherit_condition: _ColumnExpressionArgument[bool] | None = None, inherit_foreign_keys: Sequence[_ORMColumnExprArgument[Any]] | None = None, always_refresh: bool = False, version_id_col: _ORMColumnExprArgument[Any] | None = None, version_id_generator: Literal[False] | Callable[[Any], Any] | None = None, polymorphic_on: _ORMColumnExprArgument[Any] | str | MapperProperty[Any] | None = None, _polymorphic_map: Dict[Any, Mapper[Any]] | None = None, polymorphic_identity: Any | None = None, concrete: bool = False, with_polymorphic: _WithPolymorphicArg | None = None, polymorphic_abstract: bool = False, polymorphic_load: Literal['selectin', 'inline'] | None = None, allow_partial_pks: bool = True, batch: bool = True, column_prefix: str | None = None, include_properties: Sequence[str] | None = None, exclude_properties: Sequence[str] | None = None, passive_updates: bool = True, passive_deletes: bool = False, confirm_deleted_rows: bool = True, eager_defaults: Literal[True, False, 'auto'] = 'auto', legacy_is_orphan: bool = False, _compiled_cache_size: int = 100)¶

Direkter Konstruktor für ein neues Mapper Objekt.

Der Mapper Konstruktor wird nicht direkt aufgerufen und wird normalerweise über die Verwendung des registry Objekts über den Deklarativen oder Imperativen Mapping-Stil aufgerufen.

Geändert in Version 2.0: Die öffentlich zugängliche Funktion mapper() wurde entfernt; für eine klassische Mapping-Konfiguration verwenden Sie die Methode registry.map_imperatively().

Die unten dokumentierten Parameter können entweder an die Methode registry.map_imperatively() übergeben oder im deklarativen Klassenattribut __mapper_args__ übergeben werden, das unter Mapper-Konfigurationsoptionen mit Deklarativ beschrieben wird.

Parameter:

class_¶ – Die zu mappende Klasse. Bei der Verwendung von Deklarativ wird dieses Argument automatisch als die deklarierte Klasse selbst übergeben.
local_table¶ – Die Table oder eine andere FromClause (d. h. auswählbar), auf die die Klasse gemappt wird. Kann None sein, wenn dieser Mapper von einem anderen Mapper mit Single-Table-Inheritance erbt. Bei der Verwendung von Deklarativ wird dieses Argument automatisch von der Erweiterung übergeben, basierend auf dem, was über das Attribut DeclarativeBase.__table__ konfiguriert wurde oder über die Table, die als Ergebnis des Attributs DeclarativeBase.__tablename__ vorhanden ist.
polymorphic_abstract¶ –
Gibt an, dass diese Klasse in einer polymorphen Hierarchie gemappt wird, aber nicht direkt instanziiert wird. Die Klasse wird normal gemappt, außer dass sie keine Anforderung für eine Mapper.polymorphic_identity innerhalb einer Vererbungshierarchie hat. Die Klasse muss jedoch Teil eines polymorphen Vererbungsschemas sein, das Mapper.polymorphic_on an der Basis verwendet.

Neu in Version 2.0.

Siehe auch

Tiefere Hierarchien mit polymorphic_abstract erstellen
always_refresh¶ – Wenn True, überschreiben alle Abfrageoperationen für diese zugeordnete Klasse alle Daten innerhalb von Objektinstanzen, die sich bereits in der Sitzung befinden, und löschen alle Änderungen im Speicher mit den Informationen, die aus der Datenbank geladen wurden. Die Verwendung dieses Flags wird dringend abgeraten. Alternativ siehe die Methode Query.populate_existing().
allow_partial_pks¶ –
Standardmäßig True. Gibt an, dass ein zusammengesetzter Primärschlüssel mit einigen NULL-Werten als möglicherweise in der Datenbank vorhanden betrachtet werden soll. Dies beeinflusst, ob ein Mapper eine eingehende Zeile einer vorhandenen Identität zuordnet und ob Session.merge() zuerst in der Datenbank nach einem bestimmten Primärschlüsselwert sucht. Ein "partieller Primärschlüssel" kann auftreten, wenn beispielsweise auf einen OUTER JOIN gemappt wurde.

Der Parameter Mapper.allow_partial_pks gibt auch dem ORM-Relationship-Lazy-Loader an, ob beim Laden eines Many-to-One-verwandten Objekts ein zusammengesetzter Primärschlüssel mit partiellen NULL-Werten dazu führen soll, dass ein Ladeversuch aus der Datenbank unternommen wird, oder ob kein Ladeversuch erforderlich ist.

Neu in Version 2.0.36: Mapper.allow_partial_pks wird von der Relationship-Lazy-Loader-Strategie berücksichtigt, so dass bei Einstellung auf False kein SELECT für einen zusammengesetzten Primärschlüssel mit partiellen NULL-Werten emittiert wird.
batch¶ – Standardmäßig True, was angibt, dass Speicheroperationen mehrerer Entitäten zur Effizienz zusammengefasst werden können. Die Einstellung auf False bedeutet, dass eine Instanz vollständig gespeichert wird, bevor die nächste Instanz gespeichert wird. Dies wird in dem extrem seltenen Fall verwendet, dass ein MapperEvents Listener zwischen einzelnen Zeilenpersistenzoperationen aufgerufen werden muss.
column_prefix¶ –
Eine Zeichenkette, die dem Namen des zugeordneten Attributs vorangestellt wird, wenn Column Objekte automatisch als Attribute der zugeordneten Klasse zugewiesen werden. Hat keinen Einfluss auf Column Objekte, die explizit im Mapper.properties Wörterbuch zugeordnet sind.

Dieser Parameter ist typischerweise nützlich bei imperativen Mappings, die das Table Objekt separat halten. Unten wird angenommen, dass das user_table Table Objekt die Spalten user_id, user_name und password hat.
```
class User(Base):
    __table__ = user_table
    __mapper_args__ = {"column_prefix": "_"}
```
Das obige Mapping weist die Spalten user_id, user_name und password den Attributen _user_id, _user_name und _password der zugeordneten User-Klasse zu.

Der Parameter Mapper.column_prefix ist im modernen Gebrauch eher unüblich. Für die Handhabung von reflektierten Tabellen ist ein flexiblerer Ansatz zur Automatisierung eines Benennungsschemas das Abfangen der Column Objekte, während sie reflektiert werden; siehe den Abschnitt Automatisierung von Spaltenbenennungsschemata aus reflektierten Tabellen für Hinweise zu diesem Nutzungsmuster.
concrete¶ –
Wenn True, zeigt dies an, dass dieser Mapper Concrete-Table-Inheritance mit seinem übergeordneten Mapper verwenden soll.

Siehe den Abschnitt Concrete Table Inheritance für ein Beispiel.
confirm_deleted_rows¶ – Standardmäßig True; wenn ein DELETE von einer oder mehreren Zeilen basierend auf bestimmten Primärschlüsseln auftritt, wird eine Warnung ausgegeben, wenn die Anzahl der übereinstimmenden Zeilen nicht der erwarteten Anzahl von Zeilen entspricht. Dieser Parameter kann auf False gesetzt werden, um den Fall zu behandeln, in dem Datenbank-ON-DELETE-CASCADE-Regeln einige dieser Zeilen automatisch löschen. Die Warnung kann in einer zukünftigen Version in eine Ausnahme geändert werden.
eager_defaults¶ –
Wenn True, ruft das ORM den Wert serverseitig generierter Standardwerte sofort nach einem INSERT oder UPDATE ab, anstatt sie als abgelaufen zu belassen, um sie beim nächsten Zugriff abzurufen. Dies kann für Event-Schemata verwendet werden, bei denen die serverseitig generierten Werte unmittelbar vor Abschluss des Flush benötigt werden.

Das Abrufen der Werte erfolgt entweder durch Verwendung von RETURNING inline mit der INSERT oder UPDATE Anweisung oder durch Hinzufügen einer zusätzlichen SELECT Anweisung nach dem INSERT oder UPDATE, wenn das Backend RETURNING nicht unterstützt.

Die Verwendung von RETURNING ist besonders performant für INSERT-Anweisungen, bei denen SQLAlchemy insertmanyvalues nutzen kann, während die Verwendung eines zusätzlichen SELECT relativ leistungsschwach ist und zusätzliche SQL-Round-Trips hinzufügt, die unnötig wären, wenn auf diese neuen Attribute ohnehin nicht zugegriffen werden soll.

Aus diesem Grund ist Mapper.eager_defaults standardmäßig auf den Zeichenkettenwert "auto" gesetzt. Dies bedeutet, dass Server-Standardwerte für INSERT mittels RETURNING abgerufen werden sollen, sofern die zugrunde liegende Datenbank dies unterstützt und der verwendete Dialekt "insertmanyreturning" für eine INSERT-Anweisung unterstützt. Wenn die zugrunde liegende Datenbank RETURNING nicht unterstützt oder "insertmanyreturning" nicht verfügbar ist, werden die Server-Standardwerte nicht abgerufen.

Geändert in Version 2.0.0rc1: Option "auto" für Mapper.eager_defaults hinzugefügt.

Siehe auch

Abrufen von serverseitigen Standardwerten

Geändert in Version 2.0.0: RETURNING funktioniert jetzt mit mehreren gleichzeitig eingefügten Zeilen über die Funktion insertmanyvalues, was unter anderem die Mapper.eager_defaults-Funktion auf unterstützenden Backends sehr performant macht.
exclude_properties¶ –
Eine Liste oder Menge von Zeichenketten-Spaltennamen, die von der Abbildung ausgeschlossen werden sollen.

Siehe auch

Zuordnung einer Teilmenge von Tabellenspalten
include_properties¶ –
Eine inklusive Liste oder Menge von Zeichenketten-Spaltennamen, die abgebildet werden sollen.

Siehe auch

Zuordnung einer Teilmenge von Tabellenspalten
inherits¶ –
Eine abgebildete Klasse oder der entsprechende Mapper einer solchen, die auf eine Oberklasse hinweist, von der dieser Mapper *erben* soll. Die hier abgebildete Klasse muss eine Unterklasse der Klasse des anderen Mappers sein. Bei Verwendung von Declarative wird dieses Argument automatisch als Ergebnis der natürlichen Klassenhierarchie der deklarierten Klassen übergeben.

Siehe auch

Abbildung von Klassenhierarchien
inherit_condition¶ – Bei Joined-Table-Vererbung ein SQL-Ausdruck, der festlegt, wie die beiden Tabellen verbunden werden; standardmäßig eine natürliche Verbindung zwischen den beiden Tabellen.
inherit_foreign_keys¶ – Wenn inherit_condition verwendet wird und den vorhandenen Spalten eine ForeignKey-Konfiguration fehlt, kann dieser Parameter verwendet werden, um anzugeben, welche Spalten "fremd" sind. In den meisten Fällen kann dies als None belassen werden.
legacy_is_orphan¶ –
Boolean, standardmäßig False. Wenn True, wird angegeben, dass die "Legacy"-Waisenkind-Betrachtung auf von diesem Mapper abgebildete Objekte angewendet wird. Das bedeutet, dass ein ausstehendes (d. h. nicht persistentes) Objekt nur dann automatisch aus einer besitzenden Session entfernt wird, wenn es von *allen* Eltern abgetrennt wurde, die eine delete-orphan-Kaskade für diesen Mapper angeben. Das neue Standardverhalten ist, dass das Objekt automatisch entfernt wird, wenn es von *einem beliebigen* seiner Eltern abgetrennt wird, die eine delete-orphan-Kaskade angeben. Dieses Verhalten ist konsistenter mit dem eines persistenten Objekts und ermöglicht konsistentes Verhalten in mehr Szenarien, unabhängig davon, ob ein Waisenkind-Objekt bereits geleert wurde oder nicht.

Weitere Details zu dieser Änderung finden Sie in der Änderungsnotiz und im Beispiel unter Die Betrachtung eines „ausstehenden“ Objekts als „Waisenkind“ wurde aggressiver gestaltet.
non_primary¶ –
Gibt an, dass dieser Mapper zusätzlich zum "primären" Mapper, d. h. dem für die Persistenz verwendeten, existiert. Der hier erstellte Mapper kann für die Ad-hoc-Abbildung der Klasse auf eine alternative auswählbare Einheit, nur zum Lesen, verwendet werden.

Seit Version 1.3 veraltet: Der Parameter mapper.non_primary ist veraltet und wird in einer zukünftigen Version entfernt. Die Funktionalität von nicht-primären Mappern wird jetzt besser durch die AliasedClass-Konstruktion abgedeckt, die in 1.3 auch als Ziel einer relationship() verwendet werden kann.

Siehe auch

Beziehung zu AliasedClass - das neue Muster, das die Notwendigkeit des Mapper.non_primary-Flags überflüssig macht.
passive_deletes¶ –
Gibt das DELETE-Verhalten von Fremdschlüsselspalten an, wenn eine Joined-Table-Inheritance-Entität gelöscht wird. Standardmäßig False für einen Basis-Mapper; für einen erbenden Mapper standardmäßig False, es sei denn, der Wert wird auf dem Oberklassen-Mapper auf True gesetzt.

Wenn True, wird angenommen, dass ON DELETE CASCADE für die Fremdschlüsselbeziehungen konfiguriert ist, die die Tabelle dieses Mappers mit seiner Oberklassentabelle verbinden. Daher muss die Einheit der Arbeit beim Löschen der Entität nur eine DELETE-Anweisung für die Oberklassentabelle und nicht für diese Tabelle ausgeben.

Wenn False, wird eine DELETE-Anweisung individuell für die Tabelle dieses Mappers ausgegeben. Wenn die primären Schlüsselattribute, die lokal zu dieser Tabelle gehören, entladen sind, muss ein SELECT ausgegeben werden, um diese Attribute zu validieren; beachten Sie, dass die primären Schlüsselspalten einer Joined-Table-Unterklasse nicht Teil des "Primärschlüssels" des gesamten Objekts sind.

Beachten Sie, dass ein Wert von True **immer** auf die Unterklassen-Mapper erzwungen wird; das heißt, es ist für eine Oberklasse nicht möglich, passive_deletes anzugeben, ohne dass dies für alle Unterklassen-Mapper wirksam wird.

Siehe auch

Verwendung von Fremdschlüssel-ON-DELETE-Kaskade mit ORM-Beziehungen - Beschreibung einer ähnlichen Funktion wie bei relationship()

mapper.passive_updates - Unterstützung für ON UPDATE CASCADE für Joined-Table-Inheritance-Mapper
passive_updates¶ –
Gibt das UPDATE-Verhalten von Fremdschlüsselspalten an, wenn sich eine Primärschlüsselspalte in einer Joined-Table-Inheritance-Abbildung ändert. Standardmäßig True.

Wenn True, wird angenommen, dass ON UPDATE CASCADE für den Fremdschlüssel in der Datenbank konfiguriert ist und die Datenbank die Weitergabe eines UPDATES von einer Quellspalte an abhängige Spalten in Joined-Table-Zeilen handhabt.

Wenn False, wird angenommen, dass die Datenbank keine referentielle Integrität erzwingt und keine eigene CASCADE-Operation für ein Update ausgibt. Der Unit-of-Work-Prozess gibt bei einer Änderung des Primärschlüssels eine UPDATE-Anweisung für die abhängigen Spalten aus.

Siehe auch

Mutable Primary Keys / Update Cascades - Beschreibung einer ähnlichen Funktion wie bei relationship()

mapper.passive_deletes - Unterstützung für ON DELETE CASCADE für Joined-Table-Inheritance-Mapper
polymorphic_load¶ –
Gibt das "polymorphe Ladeverhalten" für eine Unterklasse in einer Vererbungshierarchie an (nur Joined- und Single-Table-Vererbung). Gültige Werte sind:
- „‘inline‘“ - gibt an, dass diese Klasse Teil der "with_polymorphic"-Mapper sein soll, d. h. ihre Spalten werden in eine SELECT-Abfrage gegen die Basis aufgenommen.
- „‘selectin‘“ - gibt an, dass beim Laden von Instanzen dieser Klasse eine zusätzliche SELECT-Abfrage ausgeführt wird, um die spezifischen Spalten dieser Unterklasse abzurufen. Die SELECT-Abfrage verwendet IN, um mehrere Unterklassen gleichzeitig abzurufen.
Neu seit Version 1.2.

Siehe auch

with_polymorphic() auf Mappern konfigurieren

Verwendung von selectin_polymorphic()
polymorphic_on¶ –
Gibt die Spalte, das Attribut oder den SQL-Ausdruck an, der verwendet wird, um die Zielklasse für eine eingehende Zeile zu bestimmen, wenn erbende Klassen vorhanden sind.

Kann als Zeichenketten-Attributname oder als SQL-Ausdruck wie eine Column oder in einer Declarative-Abbildung ein mapped_column()-Objekt angegeben werden. Es wird typischerweise erwartet, dass der SQL-Ausdruck einer Spalte in der Basis-am-weitesten-abgebildeten Table entspricht.
```
class Employee(Base):
    __tablename__ = "employee"

    id: Mapped[int] = mapped_column(primary_key=True)
    discriminator: Mapped[str] = mapped_column(String(50))

    __mapper_args__ = {
        "polymorphic_on": discriminator,
        "polymorphic_identity": "employee",
    }
```
Es kann auch als SQL-Ausdruck angegeben werden, wie in diesem Beispiel, wo wir die case()-Konstruktion verwenden, um einen bedingten Ansatz zu bieten.
```
class Employee(Base):
    __tablename__ = "employee"

    id: Mapped[int] = mapped_column(primary_key=True)
    discriminator: Mapped[str] = mapped_column(String(50))

    __mapper_args__ = {
        "polymorphic_on": case(
            (discriminator == "EN", "engineer"),
            (discriminator == "MA", "manager"),
            else_="employee",
        ),
        "polymorphic_identity": "employee",
    }
```
Es kann sich auch auf ein beliebiges Attribut über seinen Zeichenkettennamen beziehen, was besonders nützlich ist, wenn annotierte Spaltenkonfigurationen verwendet werden.
```
class Employee(Base):
    __tablename__ = "employee"

    id: Mapped[int] = mapped_column(primary_key=True)
    discriminator: Mapped[str]

    __mapper_args__ = {
        "polymorphic_on": "discriminator",
        "polymorphic_identity": "employee",
    }
```
Wenn polymorphic_on so gesetzt wird, dass es auf ein Attribut oder einen Ausdruck verweist, der nicht in der lokal abgebildeten Table vorhanden ist, aber der Wert des Diskriminators in der Datenbank gespeichert werden soll, wird der Wert des Diskriminators nicht automatisch auf neue Instanzen gesetzt; dies muss vom Benutzer gehandhabt werden, entweder manuell oder über Event-Listener. Ein typischer Ansatz zur Einrichtung eines solchen Listeners sieht wie folgt aus:
```
from sqlalchemy import event
from sqlalchemy.orm import object_mapper


@event.listens_for(Employee, "init", propagate=True)
def set_identity(instance, *arg, **kw):
    mapper = object_mapper(instance)
    instance.discriminator = mapper.polymorphic_identity
```
Wo oben der Wert von polymorphic_identity für die abgebildete Klasse dem Attribut discriminator zugewiesen wird, wodurch der Wert in die discriminator-Spalte in der Datenbank geschrieben wird.

Warnung

Derzeit darf **nur eine Diskriminatorspalte gesetzt werden**, typischerweise auf der Basis-am-weitesten-Klasse in der Hierarchie. "Kaskadierende" polymorphe Spalten werden noch nicht unterstützt.

Siehe auch

Abbildung von Klassenhierarchien
polymorphic_identity¶ –
Gibt den Wert an, der diese spezielle Klasse als von dem Spaltenausdruck zurückgegeben identifiziert, auf den durch die Mapper.polymorphic_on-Einstellung verwiesen wird. Wenn Zeilen empfangen werden, wird der Wert, der dem Spaltenausdruck Mapper.polymorphic_on entspricht, mit diesem Wert verglichen, was angibt, welche Unterklasse für das neu rekonstruierte Objekt verwendet werden soll.

Siehe auch

Abbildung von Klassenhierarchien
properties¶ –
Ein Wörterbuch, das die Zeichenkettennamen von Objektattributen auf MapperProperty-Instanzen abbildet, welche das Persistenzverhalten dieses Attributs definieren. Beachten Sie, dass Column-Objekte, die in der abgebildeten Table vorhanden sind, automatisch in ColumnProperty-Instanzen bei der Abbildung platziert werden, sofern nicht überschrieben. Bei Verwendung von Declarative wird dieses Argument automatisch basierend auf allen MapperProperty-Instanzen übergeben, die im Körper der deklarierten Klasse deklariert sind.

Siehe auch

Das properties-Wörterbuch - in der Übersicht über ORM-abgebildete Klassen
primary_key¶ –
Eine Liste von Column-Objekten oder alternativ Zeichenkettennamen von Attributnamen, die sich auf Column beziehen, die den Primärschlüssel definieren, der gegen die auswählbare Einheit dieses Mappers verwendet wird. Dies ist normalerweise einfach der Primärschlüssel der local_table, kann aber hier überschrieben werden.

Geändert in Version 2.0.2: Mapper.primary_key-Argumente können auch als Zeichenketten-Attributnamen angegeben werden.

Siehe auch

Abbildung auf einen expliziten Satz von Primärschlüsselspalten - Hintergrund und Anwendungsbeispiel
version_id_col¶ –
Eine Column, die verwendet wird, um eine laufende Versions-ID von Zeilen in der Tabelle zu führen. Dies wird verwendet, um gleichzeitige Updates oder das Vorhandensein veralteter Daten in einem Flush zu erkennen. Die Methodik besteht darin, zu erkennen, ob eine UPDATE-Anweisung nicht mit der zuletzt bekannten Versions-ID übereinstimmt, woraufhin eine StaleDataError-Ausnahme ausgelöst wird. Standardmäßig muss die Spalte vom Typ Integer sein, es sei denn, version_id_generator gibt einen alternativen Versionsgenerator an.

Siehe auch

Konfigurieren eines Versionszählers - Diskussion über Versionszählung und Begründung.
version_id_generator¶ –
Definiert, wie neue Versions-IDs generiert werden sollen. Standardmäßig None, was bedeutet, dass ein einfaches ganzzahliges Zählschema verwendet wird. Um ein benutzerdefiniertes Versionierungsschema bereitzustellen, geben Sie eine aufrufbare Funktion der Form an:
```
def generate_version(version):
    return next_version
```
Alternativ können serverseitige Versionierungsfunktionen wie Trigger oder programmatische Versionierungsschemata außerhalb des Versions-ID-Generators verwendet werden, indem der Wert False angegeben wird. Weitere Informationen zur Verwendung dieser Option finden Sie unter Serverseitige Versionszähler.

Siehe auch

Benutzerdefinierte Versionszähler / Typen

Serverseitige Versionszähler
with_polymorphic¶ –
Ein Tupel in der Form (<classes>, <selectable>), das den Standardstil des "polymorphen Ladens" angibt, d. h. welche Tabellen gleichzeitig abgefragt werden. <classes> sind beliebige einzelne oder Listen von Mappern und/oder Klassen, die die geerbten Klassen angeben, die gleichzeitig geladen werden sollen. Der spezielle Wert '*' kann verwendet werden, um anzugeben, dass alle absteigenden Klassen sofort geladen werden sollen. Das zweite Tupelargument <selectable> gibt eine auswählbare Einheit an, die zum Abfragen mehrerer Klassen verwendet wird.

Der Parameter Mapper.polymorphic_load kann in modernen Abbildungen gegenüber der Verwendung von Mapper.with_polymorphic bevorzugt werden, um eine Pro-Unterklasse-Technik zur Angabe von polymorphen Ladestilen zu kennzeichnen.

Siehe auch

with_polymorphic() auf Mappern konfigurieren

methode sqlalchemy.orm.Mapper.add_properties(dict_of_properties)¶: Fügt dem Mapper das angegebene Wörterbuch von Eigenschaften hinzu, unter Verwendung von add_property.

methode sqlalchemy.orm.Mapper.add_property(key: str, prop: Column[Any] | MapperProperty[Any]) → None¶

Fügt dem Mapper eine einzelne MapperProperty hinzu.

Wenn der Mapper noch nicht konfiguriert wurde, wird die Eigenschaft einfach dem an den Konstruktor gesendeten initialen Eigenschaften-Wörterbuch hinzugefügt. Wenn dieser Mapper bereits konfiguriert wurde, wird die angegebene MapperProperty sofort konfiguriert.

attribut sqlalchemy.orm.Mapper.all_orm_descriptors¶

Ein Namensraum aller InspectionAttr-Attribute, die der abgebildeten Klasse zugeordnet sind.

Diese Attribute sind in allen Fällen Python Deskriptoren, die der abgebildeten Klasse oder ihren Oberklassen zugeordnet sind.

Dieser Namensraum umfasst Attribute, die der Klasse zugeordnet sind, sowie Attribute, die von Erweiterungsmodulen deklariert wurden. Er umfasst jeden Python-Deskriptor-Typ, der von InspectionAttr erbt. Dazu gehören QueryableAttribute sowie Erweiterungstypen wie hybrid_property, hybrid_method und AssociationProxy.

Um zwischen abgebildeten Attributen und Erweiterungsattributen zu unterscheiden, verweist das Attribut InspectionAttr.extension_type auf eine Konstante, die zwischen verschiedenen Erweiterungstypen unterscheidet.

Die Sortierung der Attribute basiert auf folgenden Regeln:

Iterieren Sie durch die Klasse und ihre Oberklassen in der Reihenfolge von der Unterklasse zur Oberklasse (d. h. iterieren Sie durch cls.__mro__).
Für jede Klasse werden die Attribute in der Reihenfolge ausgegeben, in der sie in __dict__ erscheinen, mit Ausnahme derer in Schritt 3 unten. In Python 3.6 und höher ist diese Reihenfolge dieselbe wie die der Konstruktion der Klasse, mit Ausnahme von Attributen, die nachträglich von der Anwendung oder dem Mapper hinzugefügt wurden.
Wenn ein bestimmter Attributschlüssel auch im __dict__ der Oberklasse vorhanden ist, wird er in der Iteration für diese Klasse und nicht für die Klasse, in der er zuerst erschien, berücksichtigt.

Der obige Prozess erzeugt eine Sortierung, die in Bezug auf die Reihenfolge, in der Attribute der Klasse zugewiesen wurden, deterministisch ist.

Geändert in Version 1.3.19: Determinierte Sortierung für Mapper.all_orm_descriptors() gewährleistet.

Wenn Sie es mit einem QueryableAttribute zu tun haben, verweist das Attribut QueryableAttribute.property auf die MapperProperty-Eigenschaft, was Sie erhalten, wenn Sie auf die Sammlung von abgebildeten Eigenschaften über Mapper.attrs verweisen.

Warnung

Der Zugriffsnamensraum Mapper.all_orm_descriptors ist eine Instanz von OrderedProperties. Dies ist ein wörterbuchähnliches Objekt, das eine kleine Anzahl benannter Methoden wie OrderedProperties.items() und OrderedProperties.values() enthält. Wenn Sie Attribute dynamisch abrufen, verwenden Sie vorzugsweise das Wörterbuchzugriffsschema, z. B. mapper.all_orm_descriptors[somename] anstelle von getattr(mapper.all_orm_descriptors, somename), um Namenskollisionen zu vermeiden.

Siehe auch

Mapper.attrs

attribut sqlalchemy.orm.Mapper.attrs¶

Ein Namensraum aller MapperProperty-Objekte, die diesem Mapper zugeordnet sind.

Dies ist ein Objekt, das jede Eigenschaft basierend auf ihrem Schlüsselnamen bereitstellt. Zum Beispiel würde der Mapper für eine User-Klasse, die das Attribut User.name hat, mapper.attrs.name bereitstellen, was die ColumnProperty ist, die die name-Spalte repräsentiert. Der Namensraum kann auch iteriert werden, was jede MapperProperty liefert.

Mapper verfügt über mehrere vordefinierte Ansichten dieses Attributs, die die zurückgegebenen Eigenschaftstypen einschränken, darunter synonyms, column_attrs, relationships und composites.

Warnung

Der Zugriffsnamensraum Mapper.attrs ist eine Instanz von OrderedProperties. Dies ist ein wörterbuchähnliches Objekt, das eine kleine Anzahl benannter Methoden wie OrderedProperties.items() und OrderedProperties.values() enthält. Wenn Sie Attribute dynamisch abrufen, verwenden Sie vorzugsweise das Wörterbuchzugriffsschema, z. B. mapper.attrs[somename] anstelle von getattr(mapper.attrs, somename), um Namenskollisionen zu vermeiden.

Siehe auch

Mapper.all_orm_descriptors

attribut sqlalchemy.orm.Mapper.base_mapper: Mapper[Any]¶

Der Basis-Mapper in einer Vererbungskette.

In einem nicht-erblichen Szenario ist dieses Attribut immer dieser Mapper. In einem Erbschaftsszenario verweist es auf den Mapper, der Elternteil aller anderen Mapper-Objekte in der Vererbungskette ist.

Dies ist ein *schreibgeschütztes* Attribut, das während der Mapper-Konstruktion bestimmt wird. Das Verhalten ist undefiniert, wenn es direkt modifiziert wird.

attribut sqlalchemy.orm.Mapper.c: ReadOnlyColumnCollection[str, Column[Any]]¶: Ein Synonym für Mapper.columns.

methode sqlalchemy.orm.Mapper.cascade_iterator(type_: str, state: InstanceState[_O], halt_on: Callable[[InstanceState[Any]], bool] | None = None) → Iterator[Tuple[object, Mapper[Any], InstanceState[Any], _InstanceDict]]¶

Iterieren Sie jedes Element und seine Mapper in einem Objektgraphen für alle Beziehungen, die der gegebenen Kaskadenregel entsprechen.

Parameter:

type_¶ –
Der Name der Kaskadenregel (d. h. "save-update", "delete" usw.).

Hinweis

Die "all"-Kaskade wird hier nicht akzeptiert. Für eine allgemeine Objektdurchlauf-Funktion siehe Wie durchlaufe ich alle Objekte, die zu einem bestimmten Objekt gehören?.
state¶ – Der führende InstanceState. Kindelemente werden gemäß den für den Mapper dieses Objekts definierten Beziehungen verarbeitet.

Gibt zurück:

Die Methode liefert einzelne Objektinstanzen.

Siehe auch

Kaskaden

Wie durchlaufe ich alle Objekte, die zu einem bestimmten Objekt gehören? - illustriert eine allgemeine Funktion zum Traversieren aller Objekte, ohne sich auf Kaskaden zu verlassen.

attribut sqlalchemy.orm.Mapper.class_: Type[_O]¶: Die Klasse, zu der dieser Mapper zugeordnet ist.

attribut sqlalchemy.orm.Mapper.class_manager: ClassManager[_O]¶

Der ClassManager, der Ereignis-Listener und klassengebundene Deskriptoren für diesen Mapper verwaltet.

Dies ist ein *schreibgeschütztes* Attribut, das während der Mapper-Konstruktion bestimmt wird. Das Verhalten ist undefiniert, wenn es direkt modifiziert wird.

attribut sqlalchemy.orm.Mapper.column_attrs¶: Gibt einen Namespace aller ColumnProperty-Eigenschaften zurück, die von diesem Mapper verwaltet werden.

Siehe auch

Mapper.attrs - Namespace aller MapperProperty-Objekte.

attribut sqlalchemy.orm.Mapper.columns: ReadOnlyColumnCollection[str, Column[Any]]¶

Eine Sammlung von Column-Objekten oder anderen skalaren Ausdrucksobjekten, die von diesem Mapper verwaltet werden.

Die Sammlung verhält sich genauso wie das c-Attribut eines jeden Table-Objekts, mit der Ausnahme, dass nur die in dieser Zuordnung enthaltenen Spalten vorhanden sind und basierend auf dem in der Zuordnung definierten Attributnamen, nicht unbedingt dem key-Attribut der Column selbst, indiziert werden. Zusätzlich sind auch skalare Ausdrücke, die von column_property() zugeordnet sind, hier vorhanden.

Dies ist ein *schreibgeschütztes* Attribut, das während der Mapper-Konstruktion bestimmt wird. Das Verhalten ist undefiniert, wenn es direkt modifiziert wird.

methode sqlalchemy.orm.Mapper.common_parent(other: Mapper[Any]) → bool¶: Gibt True zurück, wenn der angegebene Mapper einen gemeinsamen geerbten Elternteil wie dieser Mapper teilt.

attribut sqlalchemy.orm.Mapper.composites¶: Gibt einen Namespace aller Composite-Eigenschaften zurück, die von diesem Mapper verwaltet werden.

Siehe auch

Mapper.attrs - Namespace aller MapperProperty-Objekte.

attribut sqlalchemy.orm.Mapper.concrete: bool¶

Stellt True dar, wenn dieser Mapper ein konkreter Vererbungsmmapper ist.

Dies ist ein *schreibgeschütztes* Attribut, das während der Mapper-Konstruktion bestimmt wird. Das Verhalten ist undefiniert, wenn es direkt modifiziert wird.

attribut sqlalchemy.orm.Mapper.configured: bool = False¶

Stellt True dar, wenn dieser Mapper konfiguriert wurde.

Dies ist ein *schreibgeschütztes* Attribut, das während der Mapper-Konstruktion bestimmt wird. Das Verhalten ist undefiniert, wenn es direkt modifiziert wird.

Siehe auch

configure_mappers().

attribut sqlalchemy.orm.Mapper.entity¶

Teil der Inspektions-API.

Gibt self.class_ zurück.

methode sqlalchemy.orm.Mapper.get_property(key: str, _configure_mappers: bool = False) → MapperProperty[Any]¶: Gibt eine MapperProperty zurück, die mit dem angegebenen Schlüssel verbunden ist.

methode sqlalchemy.orm.Mapper.get_property_by_column(column: ColumnElement[_T]) → MapperProperty[_T]¶: Gibt bei einem Column-Objekt die MapperProperty zurück, die diese Spalte zuordnet.

methode sqlalchemy.orm.Mapper.identity_key_from_instance(instance: _O) → _IdentityKeyType[_O]¶

Gibt den Identitätsschlüssel für die gegebene Instanz zurück, basierend auf ihren Primärschlüsselattributen.

Wenn der Zustand der Instanz abgelaufen ist, führt der Aufruf dieser Methode zu einer Datenbankprüfung, ob das Objekt gelöscht wurde. Wenn die Zeile nicht mehr existiert, wird ObjectDeletedError ausgelöst.

Dieser Wert befindet sich typischerweise auch auf dem Instanzzustand unter dem Attributnamen key.

methode sqlalchemy.orm.Mapper.identity_key_from_primary_key(primary_key: Tuple[Any, ...], identity_token: Any | None = None) → _IdentityKeyType[_O]¶

Gibt einen Identitäts-Map-Schlüssel zum Speichern/Abrufen eines Elements aus einer Identitäts-Map zurück.

Parameter:: primary_key¶ – Eine Liste von Werten, die den Bezeichner angeben.

methode sqlalchemy.orm.Mapper.identity_key_from_row(row: Row[Any] | RowMapping, identity_token: Any | None = None, adapter: ORMAdapter | None = None) → _IdentityKeyType[_O]¶

Gibt einen Identitäts-Map-Schlüssel zum Speichern/Abrufen eines Elements aus der Identitäts-Map zurück.

Parameter:

row¶ –

Eine Row oder RowMapping, die aus einem Ergebnisdatensatz erzeugt wurde, der von den ORM-zugeordneten Primärschlüsselspalten ausgewählt wurde.

Geändert in Version 2.0: Row oder RowMapping werden für das Argument "row" akzeptiert

attribut sqlalchemy.orm.Mapper.inherits: Mapper[Any] | None¶: Referenziert den Mapper, von dem dieser Mapper erbt, falls vorhanden.

attribut sqlalchemy.orm.Mapper.is_mapper = True¶: Teil der Inspektions-API.

methode sqlalchemy.orm.Mapper.is_sibling(other: Mapper[Any]) → bool¶: Gibt True zurück, wenn der andere Mapper ein erweiternder Geschwister zu diesem ist. Gemeinsamer Elternteil, aber unterschiedlicher Zweig.

methode sqlalchemy.orm.Mapper.isa(other: Mapper[Any]) → bool¶: Gibt True zurück, wenn dieser Mapper vom angegebenen Mapper erbt.

attribut sqlalchemy.orm.Mapper.iterate_properties¶: Gibt einen Iterator aller MapperProperty-Objekte zurück.

attribut sqlalchemy.orm.Mapper.local_table: FromClause¶

Die unmittelbare FromClause, auf die sich dieser Mapper bezieht.

Typischerweise eine Instanz von Table, kann jede FromClause sein.

Die "lokale" Tabelle ist die wählbare, für die der Mapper aus Sicht des Attributzugriffs und des Flushens direkt verantwortlich ist. Für nicht vererbende Mapper ist Mapper.local_table dasselbe wie Mapper.persist_selectable. Für vererbende Mapper bezieht sich Mapper.local_table auf den spezifischen Teil von Mapper.persist_selectable, der die Spalten enthält, die dieser Mapper lädt/persistiert, wie z. B. eine bestimmte Table innerhalb eines Joins.

Siehe auch

Mapper.persist_selectable.

Mapper.selectable.

attribut sqlalchemy.orm.Mapper.mapped_table¶: Veraltet seit Version 1.3: Verwenden Sie .persist_selectable

attribut sqlalchemy.orm.Mapper.mapper¶

Teil der Inspektions-API.

Gibt sich selbst zurück.

attribut sqlalchemy.orm.Mapper.non_primary: bool¶

Stellt True dar, wenn dieser Mapper ein "nicht primärer" Mapper ist, d. h. ein Mapper, der nur zur Auswahl von Zeilen, aber nicht zur Persistenzverwaltung verwendet wird.

Dies ist ein *schreibgeschütztes* Attribut, das während der Mapper-Konstruktion bestimmt wird. Das Verhalten ist undefiniert, wenn es direkt modifiziert wird.

attribut sqlalchemy.orm.Mapper.persist_selectable: FromClause¶

Die FromClause, auf die dieser Mapper zugeordnet ist.

Typischerweise eine Instanz von Table, kann jede FromClause sein.

Die Mapper.persist_selectable ähnelt Mapper.local_table, stellt jedoch die FromClause dar, die die vererbte Klassenhierarchie insgesamt in einem Vererbungsszenario darstellt.

:attr:`.Mapper.persist_selectable` ist auch getrennt vom Attribut Mapper.selectable, wobei letzteres eine alternative Unterabfrage zur Auswahl von Spalten sein kann. :attr:`.Mapper.persist_selectable` ist auf Spalten ausgerichtet, die bei einer Persistenzoperation geschrieben werden.

Siehe auch

Mapper.selectable.

Mapper.local_table.

attribut sqlalchemy.orm.Mapper.polymorphic_identity: Any | None¶

Stellt einen Bezeichner dar, der mit der Spalte Mapper.polymorphic_on während des Ladens von Ergebniszeilen abgeglichen wird.

Nur mit Vererbung verwendet, kann dieses Objekt jeden Typ haben, der mit dem Typ der Spalte vergleichbar ist, die von Mapper.polymorphic_on dargestellt wird.

Dies ist ein *schreibgeschütztes* Attribut, das während der Mapper-Konstruktion bestimmt wird. Das Verhalten ist undefiniert, wenn es direkt modifiziert wird.

methode sqlalchemy.orm.Mapper.polymorphic_iterator() → Iterator[Mapper[Any]]¶

Iterieren Sie durch die Sammlung, einschließlich dieses Mappers und aller abgeleiteten Mapper.

Dies schließt nicht nur die unmittelbar vererbenden Mapper ein, sondern auch alle deren vererbenden Mapper.

Um eine gesamte Hierarchie zu durchlaufen, verwenden Sie mapper.base_mapper.polymorphic_iterator().

attribut sqlalchemy.orm.Mapper.polymorphic_map: Dict[Any, Mapper[Any]]¶

Eine Zuordnung von "polymorphen Identitäts"-Bezeichnern zu Mapper-Instanzen innerhalb eines Vererbungsszenarios.

Die Bezeichner können jeden Typ haben, der mit dem Typ der Spalte vergleichbar ist, die von Mapper.polymorphic_on dargestellt wird.

Eine Vererbungskette von Mappern wird alle auf dasselbe polymorphe Kartenobjekt verweisen. Das Objekt wird verwendet, um eingehende Ergebniszeilen zu Ziel-Mappern zu korrelieren.

Dies ist ein *schreibgeschütztes* Attribut, das während der Mapper-Konstruktion bestimmt wird. Das Verhalten ist undefiniert, wenn es direkt modifiziert wird.

attribut sqlalchemy.orm.Mapper.polymorphic_on: KeyedColumnElement[Any] | None¶

Die Column oder die SQL-Ausdruck, die als polymorphic_on-Argument für diesen Mapper in einem Vererbungsszenario angegeben wurde.

Dieses Attribut ist normalerweise eine Column-Instanz, kann aber auch ein Ausdruck sein, wie z. B. einer, der von cast() abgeleitet wurde.

Dies ist ein *schreibgeschütztes* Attribut, das während der Mapper-Konstruktion bestimmt wird. Das Verhalten ist undefiniert, wenn es direkt modifiziert wird.

attribut sqlalchemy.orm.Mapper.primary_key: Tuple[Column[Any], ...]¶

Ein Iterable, das die Sammlung von Column-Objekten enthält, aus denen sich der „Primärschlüssel“ der zugeordneten Tabelle zusammensetzt, aus Sicht dieses Mapper.

Diese Liste steht im Gegensatz zum auswählbaren Element in Mapper.persist_selectable. Im Fall von vererbenden Mappern können einige Spalten von einem übergeordneten Mapper verwaltet werden. Im Fall eines Join wird der Primärschlüssel beispielsweise durch alle Primärschlüsselspalten aller Tabellen bestimmt, auf die vom Join verwiesen wird.

Die Liste ist auch nicht notwendigerweise identisch mit der Sammlung von Primärschlüsselspalten, die mit den zugrunde liegenden Tabellen verbunden ist; der Mapper verfügt über ein primary_key-Argument, das überschreiben kann, welche Spalten der Mapper als Primärschlüsselspalten betrachtet.

Dies ist ein *schreibgeschütztes* Attribut, das während der Mapper-Konstruktion bestimmt wird. Das Verhalten ist undefiniert, wenn es direkt modifiziert wird.

methode sqlalchemy.orm.Mapper.primary_key_from_instance(instance: _O) → Tuple[Any, ...]¶

Gibt die Liste der Primärschlüsselwerte für die gegebene Instanz zurück.

Wenn der Zustand der Instanz abgelaufen ist, führt der Aufruf dieser Methode zu einer Datenbankprüfung, ob das Objekt gelöscht wurde. Wenn die Zeile nicht mehr existiert, wird ObjectDeletedError ausgelöst.

methode sqlalchemy.orm.Mapper.primary_mapper() → Mapper[Any]¶: Gibt den primären Mapper zurück, der dem Klassen-Schlüssel (Klasse) dieses Mappers entspricht.

attribut sqlalchemy.orm.Mapper.relationships¶: Ein Namespace aller Relationship-Eigenschaften, die von diesem Mapper verwaltet werden.

Warnung

Der Zugriffsbereich Mapper.relationships ist eine Instanz von OrderedProperties. Dies ist ein wörterbuchähnliches Objekt, das eine kleine Anzahl benannter Methoden wie OrderedProperties.items() und OrderedProperties.values() enthält. Beim dynamischen Zugriff auf Attribute sollten Sie die Wörterbuch-Zugriffsschema bevorzugen, z. B. mapper.relationships[somename] anstelle von getattr(mapper.relationships, somename), um Namenskollisionen zu vermeiden.

Siehe auch

Mapper.attrs - Namespace aller MapperProperty-Objekte.

attribut sqlalchemy.orm.Mapper.selectable¶

Die FromClause, von der dieser Mapper standardmäßig auswählt.

Normalerweise ist dies äquivalent zu persist_selectable, es sei denn, die Funktion with_polymorphic wird verwendet, in welchem Fall der vollständige „polymorphe“ auswählbare Wert zurückgegeben wird.

attribut sqlalchemy.orm.Mapper.self_and_descendants¶

Die Sammlung, die diesen Mapper und alle nachfolgenden Mapper enthält.

Dies schließt nicht nur die unmittelbar vererbenden Mapper ein, sondern auch alle deren vererbenden Mapper.

attribut sqlalchemy.orm.Mapper.single: bool¶

Gibt True zurück, wenn dieser Mapper ein Single-Table-Inheritance-Mapper ist.

Mapper.local_table ist None, wenn dieses Flag gesetzt ist.

Dies ist ein *schreibgeschütztes* Attribut, das während der Mapper-Konstruktion bestimmt wird. Das Verhalten ist undefiniert, wenn es direkt modifiziert wird.

attribut sqlalchemy.orm.Mapper.synonyms¶: Gibt einen Namespace aller Synonym-Eigenschaften zurück, die von diesem Mapper verwaltet werden.

Siehe auch

Mapper.attrs - Namespace aller MapperProperty-Objekte.

attribut sqlalchemy.orm.Mapper.tables: Sequence[TableClause]¶

Eine Sequenz, die die Sammlung von Table- oder TableClause-Objekten enthält, von denen dieser Mapper Kenntnis hat.

Wenn der Mapper einer Join oder einem Alias zugeordnet ist, der einen Select darstellt, werden die einzelnen Table-Objekte, die das vollständige Konstrukt bilden, hier dargestellt.

Dies ist ein *schreibgeschütztes* Attribut, das während der Mapper-Konstruktion bestimmt wird. Das Verhalten ist undefiniert, wenn es direkt modifiziert wird.

attribut sqlalchemy.orm.Mapper.validators: util.immutabledict[str, Tuple[str, Dict[str, Any]]]¶

Ein unveränderliches Wörterbuch von Attributen, die mit dem Dekorator validates() dekoriert wurden.

Das Wörterbuch enthält Zeichenketten-Attributnamen als Schlüssel, die auf die eigentliche Validierungsmethode abgebildet sind.

attribut sqlalchemy.orm.Mapper.with_polymorphic_mappers¶: Die Liste der Mapper-Objekte, die in die standardmäßige „polymorphe“ Abfrage einbezogen werden.

klasse sqlalchemy.orm.MappedAsDataclass¶: Mixin-Klasse, die anzeigt, dass beim Mappen dieser Klasse diese auch in eine Dataclass umgewandelt wird.

Siehe auch

Deklaratives Mapping von Datenklassen - Vollständiger Hintergrund zum nativen Mapping von Datenklassen in SQLAlchemy

Neu in Version 2.0.

klasse sqlalchemy.orm.MappedClassProtocol¶

Ein Protokoll, das eine SQLAlchemy zugeordnete Klasse repräsentiert.

Das Protokoll ist generisch für den Typ der Klasse, verwenden Sie MappedClassProtocol[Any], um jede zugeordnete Klasse zuzulassen.

Klassensignatur

class sqlalchemy.orm.MappedClassProtocol (typing_extensions.Protocol)

SQLAlchemy 2.0 Dokumentation

SQLAlchemy 2.0 Dokumentation

SQLAlchemy ORM

Projektversionen

Class Mapping API¶