Session API¶

Session und sessionmaker()¶

Objektname	Beschreibung
ORMExecuteState	Repräsentiert einen Aufruf der Methode `Session.execute()`, wie sie an den `SessionEvents.do_orm_execute()` Event-Hook übergeben wird.
Session	Verwaltet Persistenzoperationen für ORM-abgebildete Objekte.
sessionmaker	Eine konfigurierbare `Session`-Factory.
SessionTransaction	Eine Transaktion auf `Session`-Ebene.
SessionTransactionOrigin	Zeigt den Ursprung einer `SessionTransaction` an.

class sqlalchemy.orm.sessionmaker¶

Eine konfigurierbare Session-Factory.

Die sessionmaker Factory generiert neue Session-Objekte, wenn sie aufgerufen wird, und erstellt diese anhand der hier festgelegten Konfigurationsargumente.

z. B.

from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker

# an Engine, which the Session will use for connection
# resources
engine = create_engine("postgresql+psycopg2://scott:tiger@localhost/")

Session = sessionmaker(engine)

with Session() as session:
    session.add(some_object)
    session.add(some_other_object)
    session.commit()

Die Verwendung als Context Manager ist optional; andernfalls kann das zurückgegebene Session-Objekt explizit über die Methode Session.close() geschlossen werden. Die Verwendung eines try:/finally: Blocks ist optional, stellt aber sicher, dass das Schließen auch bei Datenbankfehlern erfolgt.

session = Session()
try:
    session.add(some_object)
    session.add(some_other_object)
    session.commit()
finally:
    session.close()

sessionmaker fungiert als Factory für Session-Objekte, ähnlich wie eine Engine als Factory für Connection-Objekte fungiert. Auf diese Weise enthält sie auch eine Methode sessionmaker.begin(), die einen Context Manager bereitstellt, der sowohl eine Transaktion beginnt als auch committet, und die Session nach Abschluss schließt, wobei die Transaktion im Falle von Fehlern zurückgerollt wird.

Session = sessionmaker(engine)

with Session.begin() as session:
    session.add(some_object)
    session.add(some_other_object)
# commits transaction, closes session

Neu in Version 1.4.

Beim Aufruf von sessionmaker zur Erstellung einer Session können auch Schlüsselwortargumente an die Methode übergeben werden; diese Argumente überschreiben die global konfigurierten Parameter. Unten verwenden wir eine sessionmaker, die an eine bestimmte Engine gebunden ist, um eine Session zu erzeugen, die stattdessen an eine spezifische Connection gebunden ist, die von dieser Engine bezogen wurde.

Session = sessionmaker(engine)

# bind an individual session to a connection

with engine.connect() as connection:
    with Session(bind=connection) as session:
        ...  # work with session

Die Klasse enthält auch eine Methode sessionmaker.configure(), die verwendet werden kann, um zusätzliche Schlüsselwortargumente für die Factory anzugeben, die für nachfolgende generierte Session-Objekte wirksam werden. Dies wird normalerweise verwendet, um ein oder mehrere Engine-Objekte mit einer bestehenden sessionmaker-Factory zu verknüpfen, bevor sie zum ersten Mal verwendet wird.

# application starts, sessionmaker does not have
# an engine bound yet
Session = sessionmaker()

# ... later, when an engine URL is read from a configuration
# file or other events allow the engine to be created
engine = create_engine("sqlite:///foo.db")
Session.configure(bind=engine)

sess = Session()
# work with session

Siehe auch

Öffnen und Schließen einer Session - Einführender Text zur Erstellung von Sessions mit sessionmaker.

Mitglieder

__call__(), __init__(), begin(), close_all(), configure(), identity_key(), object_session()

Klassensignatur

class sqlalchemy.orm.sessionmaker (sqlalchemy.orm.session._SessionClassMethods, typing.Generic)

method sqlalchemy.orm.sessionmaker.__call__(**local_kw: Any) → _S¶

Produziert ein neues Session-Objekt unter Verwendung der in diesem sessionmaker festgelegten Konfiguration.

In Python wird die Methode __call__ aufgerufen, wenn ein Objekt auf die gleiche Weise wie eine Funktion "aufgerufen" wird.

Session = sessionmaker(some_engine)
session = Session()  # invokes sessionmaker.__call__()

method sqlalchemy.orm.sessionmaker.__init__(bind: Optional[_SessionBind] = None, *, class_: Type[_S] = <class 'sqlalchemy.orm.session.Session'>, autoflush: bool = True, expire_on_commit: bool = True, info: Optional[_InfoType] = None, **kw: Any)¶

Konstruiert einen neuen sessionmaker.

Alle hier aufgeführten Argumente, mit Ausnahme von class_, entsprechen Argumenten, die direkt von Session akzeptiert werden. Weitere Einzelheiten zu den Parametern finden Sie in der Dokumentation von Session.__init__().

Parameter:

bind¶ – Eine Engine oder eine andere Connectable, mit der neu erstellte Session-Objekte verknüpft werden.
class_¶ – Klasse, die zum Erstellen neuer Session-Objekte verwendet wird. Standardmäßig ist dies Session.
autoflush¶ –
Die Autoflush-Einstellung, die mit neu erstellten Session-Objekten verwendet wird.

Siehe auch

Flushing - Zusätzliche Hintergrundinformationen zu Autoflush
expire_on_commit=True¶ – Die Session.expire_on_commit-Einstellung, die mit neu erstellten Session-Objekten verwendet wird.
info¶ – Ein optionales Wörterbuch mit Informationen, die über Session.info verfügbar sind. Beachten Sie, dass dieses Wörterbuch aktualisiert und nicht ersetzt wird, wenn der Parameter info für den spezifischen Session-Konstruktionsvorgang angegeben wird.
**kw¶ – Alle anderen Schlüsselwortargumente werden an den Konstruktor der neu erstellten Session-Objekte übergeben.

method sqlalchemy.orm.sessionmaker.begin() → AbstractContextManager[_S]¶

Erzeugt einen Context Manager, der sowohl eine neue Session als auch eine Transaktion bereitstellt, die committet wird.

z. B.

Session = sessionmaker(some_engine)

with Session.begin() as session:
    session.add(some_object)

# commits transaction, closes session

Neu in Version 1.4.

classmethod sqlalchemy.orm.sessionmaker.close_all() → None¶: Geerbt von der sqlalchemy.orm.session._SessionClassMethods.close_all Methode von sqlalchemy.orm.session._SessionClassMethods

Schließt *alle* Sessions im Speicher.

Veraltet seit Version 1.3: Die Methode Session.close_all() ist veraltet und wird in einer zukünftigen Version entfernt. Bitte beziehen Sie sich auf close_all_sessions().

method sqlalchemy.orm.sessionmaker.configure(**new_kw: Any) → None¶

(Neu-)Konfigurieren der Argumente für diesen sessionmaker.

z. B.

Session = sessionmaker()

Session.configure(bind=create_engine("sqlite://"))

Geerbt von der sqlalchemy.orm.session._SessionClassMethods.identity_key Methode von sqlalchemy.orm.session._SessionClassMethods

Gibt einen Identitätsschlüssel zurück.

Dies ist ein Alias für identity_key().

classmethod sqlalchemy.orm.sessionmaker.object_session(instance: object) → Session | None¶

Geerbt von der sqlalchemy.orm.session._SessionClassMethods.object_session Methode von sqlalchemy.orm.session._SessionClassMethods

Gibt die Session zurück, zu der ein Objekt gehört.

Dies ist ein Alias für object_session().

class sqlalchemy.orm.ORMExecuteState¶

Repräsentiert einen Aufruf der Methode Session.execute(), wie sie an den SessionEvents.do_orm_execute() Event-Hook übergeben wird.

Neu in Version 1.4.

Siehe auch

Execute Events - Dokumentation auf oberster Ebene zur Verwendung von SessionEvents.do_orm_execute()

Klassensignatur

class sqlalchemy.orm.ORMExecuteState (sqlalchemy.util.langhelpers.MemoizedSlots)

method sqlalchemy.orm.ORMExecuteState.__init__(session: Session, statement: Executable, parameters: _CoreAnyExecuteParams | None, execution_options: _ExecuteOptions, bind_arguments: _BindArguments, compile_state_cls: Type[ORMCompileState] | None, events_todo: List[_InstanceLevelDispatch[Session]])¶

Konstruiert einen neuen ORMExecuteState.

Dieses Objekt wird intern konstruiert.

attribute sqlalchemy.orm.ORMExecuteState.all_mappers¶

Gibt eine Sequenz aller Mapper-Objekte zurück, die auf der obersten Ebene dieser Anweisung beteiligt sind.

Unter "oberster Ebene" verstehen wir die Mapper-Objekte, die in den Ergebnismengendatensätzen einer select()-Abfrage dargestellt werden, oder für eine update()- oder delete()-Abfrage, den Mapper, der das Hauptobjekt des UPDATE oder DELETE ist.

Neu ab Version 1.4.0b2.

Siehe auch

ORMExecuteState.bind_mapper

attribute sqlalchemy.orm.ORMExecuteState.bind_arguments: _BindArguments¶

Das als Session.execute.bind_arguments-Wörterbuch übergebene Wörterbuch.

Dieses Wörterbuch kann von Erweiterungen für Session verwendet werden, um Argumente zu übergeben, die bei der Auswahl einer Datenbankverbindung aus einer Reihe von Datenbankverbindungen helfen, die zur Ausführung dieser Anweisung verwendet werden soll.

attribute sqlalchemy.orm.ORMExecuteState.bind_mapper¶

Gibt den Mapper zurück, der der primäre "Bind"-Mapper ist.

Für ein ORMExecuteState-Objekt, das eine ORM-Anweisung aufruft, d.h. das Attribut ORMExecuteState.is_orm_statement ist True, gibt dieses Attribut den Mapper zurück, der als "primärer" Mapper der Anweisung gilt. Der Begriff "Bind-Mapper" bezieht sich auf die Tatsache, dass ein Session-Objekt an mehrere Engine-Objekte gebunden sein kann, die nach abgebildeten Klassen indiziert sind, und der "Bind-Mapper" bestimmt, welche dieser Engine-Objekte ausgewählt werden.

Für eine Anweisung, die gegen eine einzelne abgebildete Klasse aufgerufen wird, ist ORMExecuteState.bind_mapper eine zuverlässige Methode, um diesen Mapper zu erhalten.

Neu ab Version 1.4.0b2.

Siehe auch

ORMExecuteState.all_mappers

attribute sqlalchemy.orm.ORMExecuteState.execution_options: _ExecuteOptions¶

Das vollständige Wörterbuch der aktuellen Ausführungsoptionen.

Dies ist eine Zusammenführung der Optionen auf Anweisungsebene mit den lokal übergebenen Ausführungsoptionen.

Siehe auch

ORMExecuteState.local_execution_options

Executable.execution_options()

ORM Ausführungsoptionen

method sqlalchemy.orm.ORMExecuteState.invoke_statement(statement: Executable | None = None, params: _CoreAnyExecuteParams | None = None, execution_options: OrmExecuteOptionsParameter | None = None, bind_arguments: _BindArguments | None = None) → Result[Any]¶

Führt die Anweisung aus, die durch diesen ORMExecuteState repräsentiert wird, ohne Ereignisse erneut auszulösen, die bereits fortgeschritten sind.

Diese Methode führt im Wesentlichen eine re-entrant Ausführung der aktuellen Anweisung aus, für die das Ereignis SessionEvents.do_orm_execute() gerade aufgerufen wird. Der Anwendungsfall hierfür sind Ereignisbehandler, die überschreiben möchten, wie das endgültige Result-Objekt zurückgegeben wird, z. B. für Schemata, die Ergebnisse aus einem Offline-Cache abrufen oder Ergebnisse aus mehreren Ausführungen verketten.

Wenn das Result-Objekt von der tatsächlichen Handler-Funktion innerhalb von SessionEvents.do_orm_execute() zurückgegeben und an die aufrufende Methode Session.execute() weitergeleitet wird, wird der Rest der Methode Session.execute() unterbrochen und das Result-Objekt sofort an den Aufrufer von Session.execute() zurückgegeben.

Parameter:

statement¶ – optionale Anweisung, die aufgerufen werden soll, anstelle der Anweisung, die derzeit von ORMExecuteState.statement repräsentiert wird.
params¶ –
optionales Wörterbuch von Parametern oder Liste von Parametern, die in die bestehenden ORMExecuteState.parameters dieses ORMExecuteState integriert werden.

Geändert in Version 2.0: eine Liste von Parameter-Wörterbüchern wird für executemany-Aufrufe akzeptiert.
execution_options¶ – optionales Wörterbuch von Ausführungsoptionen, das in die bestehenden ORMExecuteState.execution_options dieses ORMExecuteState integriert wird.
bind_arguments¶ – optionales Wörterbuch von bind_arguments, das mit den aktuellen ORMExecuteState.bind_arguments dieses ORMExecuteState zusammengeführt wird.

Gibt zurück:

ein Result-Objekt mit ORM-Level-Ergebnissen.

Siehe auch

Anweisungen neu ausführen - Hintergrund und Beispiele für die geeignete Verwendung von ORMExecuteState.invoke_statement().

attribute sqlalchemy.orm.ORMExecuteState.is_column_load¶

Gibt True zurück, wenn die Operation spaltenorientierte Attribute auf einem bestehenden ORM-Objekt aktualisiert.

Dies geschieht während Operationen wie Session.refresh(), sowie wenn ein durch defer() verzögertes Attribut geladen wird oder ein Attribut, das entweder direkt durch Session.expire() oder durch eine Commit-Operation abgelaufen ist, geladen wird.

Handler möchten wahrscheinlich keine Optionen zu Abfragen hinzufügen, wenn eine solche Operation stattfindet, da die Abfrage ein einfacher Primärschlüsselabruf sein sollte, der keine zusätzlichen WHERE-Kriterien aufweist, und Loader-Optionen, die mit der Instanz reisen, bereits zur Abfrage hinzugefügt wurden.

Neu ab Version 1.4.0b2.

Siehe auch

ORMExecuteState.is_relationship_load

attribute sqlalchemy.orm.ORMExecuteState.is_delete¶: Gibt True zurück, wenn dies eine DELETE-Operation ist.

Geändert in Version 2.0.30: - das Attribut ist auch True für ein Select.from_statement()-Konstrukt, das selbst gegen ein Delete-Konstrukt gerichtet ist, wie z.B. select(Entity).from_statement(delete(..))

attribute sqlalchemy.orm.ORMExecuteState.is_executemany¶: Gibt True zurück, wenn die Parameter eine mehrteilige Liste von Wörterbüchern mit mehr als einem Wörterbuch sind.

Neu in Version 2.0.

attribute sqlalchemy.orm.ORMExecuteState.is_from_statement¶

Gibt True zurück, wenn diese Operation eine Select.from_statement()-Operation ist.

Dies ist unabhängig von ORMExecuteState.is_select, da ein select().from_statement()-Konstrukt auch mit INSERT/UPDATE/DELETE RETURNING-Arten von Anweisungen verwendet werden kann. ORMExecuteState.is_select wird nur gesetzt, wenn die Select.from_statement() selbst gegen ein Select-Konstrukt gerichtet ist.

Neu in Version 2.0.30.

attribute sqlalchemy.orm.ORMExecuteState.is_insert¶: Gibt True zurück, wenn dies eine INSERT-Operation ist.

Geändert in Version 2.0.30: - das Attribut ist auch True für ein Select.from_statement()-Konstrukt, das selbst gegen ein Insert-Konstrukt gerichtet ist, wie z.B. select(Entity).from_statement(insert(..))

attribute sqlalchemy.orm.ORMExecuteState.is_orm_statement¶

Gibt True zurück, wenn die Operation eine ORM-Anweisung ist.

Dies zeigt an, dass das aufgerufene select(), insert(), update() oder delete() ORM-Entitäten als Subjekte enthält. Für eine Anweisung, die keine ORM-Entitäten hat und stattdessen nur auf Table-Metadaten verweist, wird sie als Core-SQL-Anweisung aufgerufen und es findet keine ORM-Level-Automatisierung statt.

attribute sqlalchemy.orm.ORMExecuteState.is_relationship_load¶

Gibt True zurück, wenn diese Ladung Objekte im Auftrag einer Beziehung lädt.

Dies bedeutet, dass der wirksame Loader entweder ein LazyLoader, SelectInLoader, SubqueryLoader oder ähnliches ist und die gesamte ausgegebene SELECT-Anweisung im Auftrag eines Beziehungs-Loads erfolgt.

Handler möchten wahrscheinlich keine Optionen zu Abfragen hinzufügen, wenn eine solche Operation stattfindet, da Loader-Optionen bereits auf Beziehungs-Loader übertragen werden können und bereits vorhanden sein sollten.

Siehe auch

ORMExecuteState.is_column_load

attribute sqlalchemy.orm.ORMExecuteState.is_select¶: Gibt True zurück, wenn dies eine SELECT-Operation ist.

Geändert in Version 2.0.30: - das Attribut ist auch True für ein Select.from_statement()-Konstrukt, das selbst gegen ein Select-Konstrukt gerichtet ist, wie z.B. select(Entity).from_statement(select(..))

attribute sqlalchemy.orm.ORMExecuteState.is_update¶: Gibt True zurück, wenn dies eine UPDATE-Operation ist.

Geändert in Version 2.0.30: - das Attribut ist auch True für ein Select.from_statement()-Konstrukt, das selbst gegen ein Update-Konstrukt gerichtet ist, wie z.B. select(Entity).from_statement(update(..))

attribute sqlalchemy.orm.ORMExecuteState.lazy_loaded_from¶

Ein InstanceState, das diese Anweisungsausführung für eine Lazy-Load-Operation verwendet.

Der Hauptgrund für dieses Attribut ist die Unterstützung der horizontalen Sharding-Erweiterung, wo es innerhalb spezifischer Hooks für die Abfrageausführung, die von dieser Erweiterung erstellt werden, verfügbar ist. Zu diesem Zweck ist das Attribut nur zur **Abfrageausführungszeit** aussagekräftig und insbesondere nicht zu irgendeiner Zeit davor, einschließlich der Abfragekompilierungszeit.

attribute sqlalchemy.orm.ORMExecuteState.load_options¶: Gibt die für diese Ausführung zu verwendenden load_options zurück.

attribute sqlalchemy.orm.ORMExecuteState.loader_strategy_path¶

Gibt die PathRegistry für den aktuellen Lade Pfad zurück.

Dieses Objekt repräsentiert den „Pfad“ in einer Abfrage entlang von Beziehungen, wenn ein bestimmtes Objekt oder eine Sammlung geladen wird.

attribute sqlalchemy.orm.ORMExecuteState.local_execution_options: _ExecuteOptions¶

Dictionary-Ansicht der Ausführungsoptionen, die an die Methode Session.execute() übergeben wurden.

Dies enthält keine Optionen, die mit der aufgerufenen Anweisung verbunden sein könnten.

Siehe auch

ORMExecuteState.execution_options

attribute sqlalchemy.orm.ORMExecuteState.parameters: _CoreAnyExecuteParams | None¶: Wörterbuch der Parameter, das an Session.execute() übergeben wurde.

attribute sqlalchemy.orm.ORMExecuteState.session: Session¶: Die verwendete Session.

attribute sqlalchemy.orm.ORMExecuteState.statement: Executable¶

Die aufgerufene SQL-Anweisung.

Für eine ORM-Auswahl, wie sie von Query abgerufen würde, ist dies eine Instanz von select, die aus der ORM-Abfrage generiert wurde.

attribute sqlalchemy.orm.ORMExecuteState.update_delete_options¶: Gibt die für diese Ausführung zu verwendenden update_delete_options zurück.

method sqlalchemy.orm.ORMExecuteState.update_execution_options(**opts: Any) → None¶: Aktualisiert die lokalen Ausführungsoptionen mit neuen Werten.

attribute sqlalchemy.orm.ORMExecuteState.user_defined_options¶: Die Sequenz von UserDefinedOptions, die der aufgerufenen Anweisung zugeordnet wurden.

class sqlalchemy.orm.Session¶

Verwaltet Persistenzoperationen für ORM-abgebildete Objekte.

Die Session ist **nicht threadsicher**. Siehe Ist die Session threadsicher? Ist AsyncSession sicher für gemeinsame Nutzung in gleichzeitigen Aufgaben? für Hintergrundinformationen.

Das Verwendungsparadigma der Session wird unter Verwendung der Session beschrieben.

Klassensignatur

class sqlalchemy.orm.Session (sqlalchemy.orm.session._SessionClassMethods, sqlalchemy.event.registry.EventTarget)

Methode sqlalchemy.orm.Session.__init__(bind: _SessionBind | None = None, *, autoflush: bool = True, future: Literal[True] = True, expire_on_commit: bool = True, autobegin: bool = True, twophase: bool = False, binds: Dict[_SessionBindKey, _SessionBind] | None = None, enable_baked_queries: bool = True, info: _InfoType | None = None, query_cls: Type[Query[Any]] | None = None, autocommit: Literal[False] = False, join_transaction_mode: JoinTransactionMode = 'conditional_savepoint', close_resets_only: bool | _NoArg = _NoArg.NO_ARG)¶

Konstruiert eine neue Session.

Siehe auch die Funktion sessionmaker, die verwendet wird, um einen Session-erzeugenden Aufrufer mit einem gegebenen Satz von Argumenten zu erzeugen.

Parameter:

autoflush¶ –
Wenn True, geben alle Abfrageoperationen einen Session.flush()-Aufruf an diese Session aus, bevor sie fortfährt. Dies ist eine Komfortfunktion, damit Session.flush() nicht wiederholt aufgerufen werden muss, damit Datenbankabfragen Ergebnisse liefern.

Siehe auch

Flushing - Zusätzliche Hintergrundinformationen zu Autoflush
autobegin¶ –
Startet automatisch Transaktionen (d. h. äquivalent zum Aufrufen von Session.begin()), wenn Datenbankzugriff von einer Operation angefordert wird. Standardmäßig True. Auf False gesetzt, um zu verhindern, dass eine Session nach der Konstruktion sowie nach jedem Aufruf der Methoden Session.rollback(), Session.commit() oder Session.close() implizit Transaktionen beginnt.

Neu in Version 2.0.

Siehe auch

Deaktivieren von Autobegin, um implizite Transaktionen zu verhindern
bind¶ – Ein optionales Engine oder Connection, an das diese Session gebunden werden soll. Wenn angegeben, werden alle von dieser Sitzung ausgeführten SQL-Operationen über diesen Connectable ausgeführt.
binds¶ –
Ein Wörterbuch, das eine beliebige Anzahl von Engine- oder Connection-Objekten als Quelle für die Konnektivität für SQL-Operationen auf pro-Entitäts-Basis angeben kann. Die Schlüssel des Wörterbuchs bestehen aus beliebigen Abbildklassen, beliebigen Python-Klassen, die Basen für Abbildklassen sind, Table-Objekten und Mapper-Objekten. Die Werte des Wörterbuchs sind dann Instanzen von Engine oder seltener Connection-Objekten. Operationen, die sich auf eine bestimmte Abbildklasse beziehen, konsultieren dieses Wörterbuch, um die am besten passende Entität zu ermitteln, die für eine bestimmte SQL-Operation verwendet werden soll. Die vollständige Heuristik für die Auflösung ist unter Session.get_bind() beschrieben. Die Verwendung sieht wie folgt aus:
```
Session = sessionmaker(
    binds={
        SomeMappedClass: create_engine("postgresql+psycopg2://engine1"),
        SomeDeclarativeBase: create_engine(
            "postgresql+psycopg2://engine2"
        ),
        some_mapper: create_engine("postgresql+psycopg2://engine3"),
        some_table: create_engine("postgresql+psycopg2://engine4"),
    }
)
```
Siehe auch

Partitionierungsstrategien (z. B. mehrere Datenbank-Backends pro Session)

Session.bind_mapper()

Session.bind_table()

Session.get_bind()
class_¶ – Gibt eine alternative Klasse anstelle von sqlalchemy.orm.session.Session, die von der zurückgegebenen Klasse verwendet werden soll. Dies ist das einzige Argument, das lokal für die Funktion sessionmaker ist und nicht direkt an den Konstruktor für Session gesendet wird.
enable_baked_queries¶ –
veraltet; Standard ist True. Ein Parameter, der von der Erweiterung sqlalchemy.ext.baked verbraucht wird, um zu bestimmen, ob "baked queries" zwischengespeichert werden sollen, was die normale Funktionsweise dieser Erweiterung ist. Wenn auf False gesetzt, wird das Caching, wie es von dieser Erweiterung verwendet wird, deaktiviert.

Geändert in Version 1.4: Die Erweiterung sqlalchemy.ext.baked ist veraltet und wird von keinem der internen Bestandteile von SQLAlchemy verwendet. Dieses Flag wirkt sich daher nur auf Anwendungen aus, die diese Erweiterung explizit in ihrem eigenen Code verwenden.
expire_on_commit¶ –
Standardmäßig True. Wenn True, werden alle Instanzen nach jedem commit() vollständig abgelaufen (expired), sodass jeder Attribut-/Objektzugriff nach einer abgeschlossenen Transaktion aus dem aktuellsten Datenbankzustand geladen wird.

Siehe auch

Commit
future¶ –
Veraltet; dieses Flag ist immer True.

Siehe auch

SQLAlchemy 2.0 - Major Migration Guide
info¶ – Optionales Wörterbuch mit beliebigen Daten, die dieser Session zugeordnet werden sollen. Ist über das Attribut Session.info verfügbar. Beachten Sie, dass das Wörterbuch zur Konstruktionszeit kopiert wird, sodass Modifikationen am pro- Session-Wörterbuch lokal für diese Session sind.
query_cls¶ – Klasse, die zum Erstellen neuer Query-Objekte verwendet werden soll, wie sie von der Methode Session.query() zurückgegeben werden. Standardmäßig Query.
twophase¶ – Wenn True, werden alle Transaktionen als "Two-Phase"-Transaktion gestartet, d. h. unter Verwendung der "Two-Phase"-Semantik der verwendeten Datenbank zusammen mit einer XID. Während eines commit() wird nach Ausgabe von flush() für alle angeschlossenen Datenbanken die Methode TwoPhaseTransaction.prepare() jeder Datenbank- TwoPhaseTransaction aufgerufen. Dies ermöglicht es jeder Datenbank, die gesamte Transaktion zurückzurollen, bevor jede Transaktion committet wird.
autocommit¶ – das Schlüsselwort "autocommit" ist aus Kompatibilitätsgründen vorhanden, muss aber bei seinem Standardwert von False bleiben.
join_transaction_mode¶ –
Beschreibt das transaktionale Verhalten, das eingenommen wird, wenn ein gegebener Bind eine Connection ist, die bereits eine Transaktion außerhalb des Geltungsbereichs dieser Session begonnen hat; mit anderen Worten, die Methode Connection.in_transaction() gibt True zurück.

Die folgenden Verhaltensweisen treten nur in Kraft, wenn die Session **die gegebene Verbindung tatsächlich verwendet**; d. h. eine Methode wie Session.execute(), Session.connection() usw. tatsächlich aufgerufen werden.
- "conditional_savepoint" - dies ist der Standard. Wenn die gegebene Connection innerhalb einer Transaktion gestartet wird, aber keinen SAVEPOINT hat, dann wird "rollback_only" verwendet. Wenn die Connection sich zusätzlich innerhalb eines SAVEPOINTs befindet, d. h. die Methode Connection.in_nested_transaction() True zurückgibt, dann wird "create_savepoint" verwendet.
  
  "conditional_savepoint" - das Verhalten versucht, Savepoints zu nutzen, um den Zustand der bestehenden Transaktion unverändert zu lassen, aber nur, wenn bereits ein Savepoint aktiv ist; andernfalls wird nicht davon ausgegangen, dass das verwendete Backend angemessene Unterstützung für SAVEPOINT hat, da die Verfügbarkeit dieser Funktion variiert. "conditional_savepoint" versucht auch, eine ungefähre Abwärtskompatibilität mit früheren Session-Verhaltensweisen herzustellen, für Anwendungen, die keinen spezifischen Modus einstellen. Es wird empfohlen, eine der expliziten Einstellungen zu verwenden.
- "create_savepoint" - die Session verwendet in allen Fällen Connection.begin_nested(), um ihre eigene Transaktion zu erstellen. Diese Transaktion "reitet" von Natur aus "auf" jeder bestehenden Transaktion, die auf der gegebenen Connection geöffnet ist; wenn die zugrunde liegende Datenbank und der verwendete Treiber volle, fehlerfreie Unterstützung für SAVEPOINT haben, bleibt die externe Transaktion während der Lebensdauer der Session unberührt.
  
  Der Modus "create_savepoint" ist am nützlichsten, um eine Session in eine Testsuite zu integrieren, in der eine extern initiierte Transaktion unberührt bleiben soll; er ist jedoch auf eine ordnungsgemäße SAVEPOINT-Unterstützung durch den zugrunde liegenden Treiber und die Datenbank angewiesen.
  
  Tipp
  
  Bei Verwendung von SQLite behandelt der in Python 3.11 enthaltene SQLite-Treiber SAVEPOINTs nicht in allen Fällen korrekt ohne Workarounds. Siehe die Abschnitte Serielle Isolation / Savepoints / Transaktionales DDL und Serielle Isolation / Savepoints / Transaktionales DDL (asyncio-Version) für Details zu aktuellen Workarounds.
- "control_fully" - die Session übernimmt die Kontrolle über die gegebene Transaktion als ihre eigene; Session.commit() ruft .commit() auf der Transaktion auf, Session.rollback() ruft .rollback() auf der Transaktion auf, Session.close() ruft .rollback auf der Transaktion auf.
  
  Tipp
  
  Dieser Nutzungsmodus entspricht dem Verhalten von SQLAlchemy 1.4 bei einer Connection, die mit einem bestehenden SAVEPOINT übergeben wurde (d. h. Connection.begin_nested()); die Session würde die volle Kontrolle über den bestehenden SAVEPOINT übernehmen.
- "rollback_only" - die Session übernimmt die Kontrolle über die gegebene Transaktion nur für .rollback()-Aufrufe; .commit()-Aufrufe werden nicht an die gegebene Transaktion weitergegeben. .close()-Aufrufe haben keine Auswirkung auf die gegebene Transaktion.
  
  Tipp
  
  Dieser Nutzungsmodus entspricht dem Verhalten von SQLAlchemy 1.4 bei einer Connection, die mit einer bestehenden regulären Datenbanktransaktion übergeben wurde (d. h. Connection.begin()); die Session würde Session.rollback()-Aufrufe an die zugrunde liegende Transaktion weitergeben, aber keine Session.commit()- oder Session.close()-Aufrufe.
Neu in Version 2.0.0rc1.
close_resets_only¶ –
Standardmäßig True. Bestimmt, ob die Sitzung sich nach dem Aufrufen von .close() zurücksetzen soll oder in einem nicht mehr verwendbaren Zustand übergeben wird, was die Wiederverwendung deaktiviert.

Neu in Version 2.0.22: Flag close_resets_only hinzugefügt. Eine zukünftige SQLAlchemy-Version kann den Standardwert dieses Flags auf False ändern.

Siehe auch

Schließen - Details zu den Semantiken von Session.close() und Session.reset().

Methode sqlalchemy.orm.Session.add(instance: object, _warn: bool = True) → None¶

Platziert ein Objekt in dieser Session.

Objekte, die sich im transient-Zustand befinden, wenn sie an die Methode Session.add() übergeben werden, wechseln in den pending-Zustand, bis zum nächsten Flush, an dem sie in den persistent-Zustand wechseln.

Objekte, die sich im detached-Zustand befinden, wenn sie an die Methode Session.add() übergeben werden, wechseln direkt in den persistent-Zustand.

Wenn die von der Session verwendete Transaktion zurückgerollt wird, werden Objekte, die beim Übergeben an Session.add() transient waren, zurück in den transient-Zustand versetzt und sind nicht mehr in dieser Session vorhanden.

Siehe auch

Session.add_all()

Hinzufügen neuer oder vorhandener Elemente - bei Grundlagen der Verwendung einer Session

Methode sqlalchemy.orm.Session.add_all(instances: Iterable[object]) → None¶

Fügt die gegebene Sammlung von Instanzen dieser Session hinzu.

Siehe die Dokumentation für Session.add() für eine allgemeine Verhaltensbeschreibung.

Siehe auch

Session.add()

Hinzufügen neuer oder vorhandener Elemente - bei Grundlagen der Verwendung einer Session

Methode sqlalchemy.orm.Session.begin(nested: bool = False) → SessionTransaction¶

Beginnt eine Transaktion oder eine verschachtelte Transaktion in dieser Session, falls noch keine gestartet wurde.

Das Session-Objekt verfügt über das autobegin-Verhalten, sodass es normalerweise nicht notwendig ist, die Session.begin()-Methode explizit aufzurufen. Sie kann jedoch verwendet werden, um den Geltungsbereich zu steuern, wann der transaktionale Zustand beginnt.

Wenn sie verwendet wird, um die äußerste Transaktion zu beginnen, wird ein Fehler ausgelöst, wenn diese Session bereits innerhalb einer Transaktion liegt.

Parameter:: nested¶ – Wenn True, beginnt eine SAVEPOINT-Transaktion und ist äquivalent zum Aufrufen von Session.begin_nested(). Dokumentation zu SAVEPOINT-Transaktionen finden Sie unter Verwendung von SAVEPOINT.
Gibt zurück:: Das SessionTransaction-Objekt. Beachten Sie, dass SessionTransaction als Python-Kontextmanager fungiert, wodurch Session.begin() in einem "with"-Block verwendet werden kann. Ein Beispiel finden Sie unter Explizites Beginnen.

Siehe auch

Automatisches Beginnen

Transaktionen verwalten

Session.begin_nested()

method sqlalchemy.orm.Session.begin_nested() → SessionTransaction¶

Beginnt eine "verschachtelte" Transaktion auf dieser Session, z. B. SAVEPOINT.

Die Ziel-Datenbank(en) und zugehörige Treiber müssen SQL SAVEPOINT unterstützen, damit diese Methode korrekt funktioniert.

Dokumentation zu SAVEPOINT-Transaktionen finden Sie unter Verwendung von SAVEPOINT.

Gibt zurück:: das SessionTransaction-Objekt. Beachten Sie, dass SessionTransaction als Kontextmanager fungiert, wodurch Session.begin_nested() in einem "with"-Block verwendet werden kann. Ein Anwendungsbeispiel finden Sie unter Verwendung von SAVEPOINT.

Siehe auch

SAVEPOINT verwenden

Serielle Isolierung / Savepoints / Transaktionale DDL - Spezielle Workarounds, die mit dem SQLite-Treiber erforderlich sind, damit SAVEPOINT korrekt funktioniert. Für asyncio-Anwendungsfälle siehe den Abschnitt Serielle Isolierung / Savepoints / Transaktionale DDL (asyncio-Version).

method sqlalchemy.orm.Session.bind_mapper(mapper: _EntityBindKey[_O], bind: _SessionBind) → None¶

Ordnet eine Mapper oder eine beliebige Python-Klasse einem "Bind" zu, z. B. einer Engine oder Connection.

Die angegebene Entität wird einer Suche hinzugefügt, die von der Methode Session.get_bind() verwendet wird.

Parameter:

mapper¶ – ein Mapper-Objekt oder eine Instanz einer gemappten Klasse oder jede Python-Klasse, die die Basis für eine Menge von gemappten Klassen ist.
bind¶ – ein Engine- oder Connection-Objekt.

Siehe auch

Partitionierungsstrategien (z. B. mehrere Datenbank-Backends pro Session)

Session.binds

Session.bind_table()

method sqlalchemy.orm.Session.bind_table(table: TableClause, bind: Engine | Connection) → None¶

Ordnet eine Table einem "Bind" zu, z. B. einer Engine oder Connection.

Die angegebene Table wird einer Suche hinzugefügt, die von der Methode Session.get_bind() verwendet wird.

Parameter:

table¶ – ein Table-Objekt, das typischerweise das Ziel einer ORM-Zuordnung ist oder innerhalb eines gemappten Selektors vorhanden ist.
bind¶ – ein Engine- oder Connection-Objekt.

Siehe auch

Partitionierungsstrategien (z. B. mehrere Datenbank-Backends pro Session)

Session.binds

Session.bind_mapper()

method sqlalchemy.orm.Session.bulk_insert_mappings(mapper: Mapper[Any], mappings: Iterable[Dict[str, Any]], return_defaults: bool = False, render_nulls: bool = False) → None¶

Führt eine Masseneinfügung der angegebenen Liste von Mapping-Dictionaries durch.

Legacy-Funktion

Diese Methode ist ab der SQLAlchemy-Serie 2.0 ein Legacy-Feature. Für moderne Massen-INSERT- und UPDATE-Operationen siehe die Abschnitte ORM Massen-INSERT-Anweisungen und ORM Massen-UPDATE nach Primärschlüssel. Die API 2.0 teilt Implementierungsdetails mit dieser Methode und fügt neue Funktionen hinzu.

Parameter:

mapper¶ – eine gemappte Klasse oder das tatsächliche Mapper-Objekt, das die einzige Art von Objekt repräsentiert, die in der Mapping-Liste enthalten ist.
mappings¶ – eine Sequenz von Dictionaries, von denen jedes den Zustand der zu einzufügenden gemappten Zeile im Hinblick auf die Attributnamen der gemappten Klasse enthält. Wenn das Mapping mehrere Tabellen bezieht, wie z. B. ein Joined-Inheritance-Mapping, muss jedes Dictionary alle Schlüssel enthalten, die in allen Tabellen gefüllt werden sollen.
return_defaults¶ –
Wenn True, wird der INSERT-Prozess so geändert, dass sichergestellt wird, dass neu generierte Primärschlüsselwerte abgerufen werden. Der Grund für diesen Parameter ist typischerweise die Aktivierung von Bulk-INSERTs für Joined-Table-Inheritance-Mappings.

Hinweis

Für Backends, die RETURNING nicht unterstützen, kann der Parameter Session.bulk_insert_mappings.return_defaults die Leistung erheblich verringern, da INSERT-Anweisungen nicht mehr gebündelt werden können. Hintergrundinformationen dazu, welche Backends betroffen sind, finden Sie unter Verhalten von „Insert Many Values“ für INSERT-Anweisungen.
render_nulls¶ –
Wenn True, führt ein Wert von None dazu, dass ein NULL-Wert in die INSERT-Anweisung aufgenommen wird, anstatt dass die Spalte aus dem INSERT weggelassen wird. Dies ermöglicht es allen Zeilen, die eingefügt werden, denselben Satz von Spalten zu haben, was die Bündelung der vollständigen Zeilen an den DBAPI ermöglicht. Normalerweise muss jede Spaltensammlung, die eine andere Kombination von NULL-Werten als die vorherige Zeile enthält, eine andere Reihe von Spalten aus der gerenderten INSERT-Anweisung weglassen, was bedeutet, dass sie als separate Anweisung ausgegeben werden muss. Durch die Übergabe dieses Flags wird garantiert, dass der vollständige Satz von Zeilen in einen Stapel gebündelt werden kann; der Nachteil ist jedoch, dass serverseitige Standardwerte, die durch eine weggelassene Spalte aufgerufen werden, übersprungen werden. Daher muss darauf geachtet werden, dass diese nicht erforderlich sind.

Warnung

Wenn dieses Flag gesetzt ist, werden serverseitige Standard-SQL-Werte nicht aufgerufen für Spalten, die als NULL eingefügt werden; der NULL-Wert wird explizit gesendet. Es muss darauf geachtet werden, dass keine serverseitigen Standardfunktionen für den gesamten Vorgang aufgerufen werden müssen.

Siehe auch

ORM-aktivierte INSERT-, UPDATE- und DELETE-Anweisungen

Session.bulk_save_objects()

Session.bulk_update_mappings()

method sqlalchemy.orm.Session.bulk_save_objects(objects: Iterable[object], return_defaults: bool = False, update_changed_only: bool = True, preserve_order: bool = True) → None¶

Führt eine Massenspeicherung der angegebenen Objektliste durch.

Legacy-Funktion

Diese Methode ist ab der SQLAlchemy-Serie 2.0 ein Legacy-Feature. Für moderne Massen-INSERT- und UPDATE-Operationen siehe die Abschnitte ORM Massen-INSERT-Anweisungen und ORM Massen-UPDATE nach Primärschlüssel.

Für allgemeine INSERT- und UPDATE-Operationen auf vorhandenen ORM-gemappten Objekten bevorzugen Sie Standardmuster für die Datenverwaltung der Arbeitseinheit, eingeführt im Unified Tutorial von SQLAlchemy unter Datenmanipulation mit dem ORM. SQLAlchemy 2.0 verwendet jetzt das Verhalten von „Insert Many Values“ für INSERT-Anweisungen mit modernen Dialekten, was frühere Probleme mit langsamen Massen-INSERTs löst.

Parameter:

objects¶ –
eine Sequenz von gemappten Objektinstanzen. Die gemappten Objekte werden unverändert gespeichert und werden danach nicht mit der Session verknüpft.

Für jedes Objekt hängt davon, ob das Objekt als INSERT oder UPDATE gesendet wird, von denselben Regeln ab, die die Session in der herkömmlichen Operation verwendet; wenn das Objekt das Attribut InstanceState.key gesetzt hat, wird angenommen, dass das Objekt "detached" ist und ein UPDATE zur Folge hat. Andernfalls wird ein INSERT verwendet.

Im Falle eines UPDATEs werden Anweisungen danach gruppiert, welche Attribute geändert wurden und somit Gegenstand jeder SET-Klausel sind. Wenn update_changed_only False ist, werden alle in jedem Objekt vorhandenen Attribute auf die UPDATE-Anweisung angewendet, was dazu beitragen kann, dass die Anweisungen zu einem größeren executemany() gruppiert werden können und den Aufwand für die Überprüfung des Verlaufs von Attributen reduziert.
return_defaults¶ – Wenn True, werden Zeilen, denen Werte fehlen, die Standardwerte generieren, insbesondere ganzzahlige Primärschlüssel-Standardwerte und Sequenzen, einzeln eingefügt, damit der Primärschlüsselwert verfügbar ist. Insbesondere ermöglicht dies, dass joined-inheritance- und andere Multi-Table-Mappings korrekt eingefügt werden können, ohne dass Primärschlüsselwerte im Voraus angegeben werden müssen; jedoch reduziert Session.bulk_save_objects.return_defaults die Leistungssteigerung der Methode insgesamt erheblich. Es wird dringend empfohlen, stattdessen den Standardansatz Session.add_all() zu verwenden.
update_changed_only¶ – Wenn True, werden UPDATE-Anweisungen basierend auf den Attributen in jedem Zustand, die Änderungen protokolliert haben, gerendert. Wenn False, werden alle vorhandenen Attribute in die SET-Klausel gerendert, mit Ausnahme von Primärschlüsselattributen.
preserve_order¶ – Wenn True, entspricht die Reihenfolge von Einfügungen und Aktualisierungen exakt der Reihenfolge, in der die Objekte übergeben werden. Wenn False, werden übliche Objekttypen in Einfügungen und Aktualisierungen gruppiert, um mehr Bündelungsmöglichkeiten zu ermöglichen.

Siehe auch

ORM-aktivierte INSERT-, UPDATE- und DELETE-Anweisungen

Session.bulk_insert_mappings()

Session.bulk_update_mappings()

method sqlalchemy.orm.Session.bulk_update_mappings(mapper: Mapper[Any], mappings: Iterable[Dict[str, Any]]) → None¶

Führt eine Massenaktualisierung der angegebenen Liste von Mapping-Dictionaries durch.

Legacy-Funktion

Diese Methode ist ab der SQLAlchemy-Serie 2.0 ein Legacy-Feature. Für moderne Massen-INSERT- und UPDATE-Operationen siehe die Abschnitte ORM Massen-INSERT-Anweisungen und ORM Massen-UPDATE nach Primärschlüssel. Die API 2.0 teilt Implementierungsdetails mit dieser Methode und fügt neue Funktionen hinzu.

Parameter:

mapper¶ – eine gemappte Klasse oder das tatsächliche Mapper-Objekt, das die einzige Art von Objekt repräsentiert, die in der Mapping-Liste enthalten ist.
mappings¶ – eine Sequenz von Dictionaries, von denen jedes den Zustand der zu aktualisierenden gemappten Zeile im Hinblick auf die Attributnamen der gemappten Klasse enthält. Wenn das Mapping mehrere Tabellen bezieht, wie z. B. ein Joined-Inheritance-Mapping, kann jedes Dictionary Schlüssel enthalten, die sich auf alle Tabellen beziehen. Alle Schlüssel, die vorhanden sind und nicht Teil des Primärschlüssels sind, werden der SET-Klausel der UPDATE-Anweisung hinzugefügt; die erforderlichen Primärschlüsselwerte werden der WHERE-Klausel hinzugefügt.

Siehe auch

ORM-aktivierte INSERT-, UPDATE- und DELETE-Anweisungen

Session.bulk_insert_mappings()

Session.bulk_save_objects()

method sqlalchemy.orm.Session.close() → None¶

Schließt die transaktionalen Ressourcen und ORM-Objekte, die von dieser Session verwendet werden.

Dies expungiert alle ORM-Objekte, die mit dieser Session verbunden sind, beendet alle laufenden Transaktionen und gibt alle Connection-Objekte frei, die diese Session selbst von zugehörigen Engine-Objekten ausgecheckt hat. Die Operation versetzt die Session dann in einen Zustand, in dem sie wieder verwendet werden kann.

Tipp

Im Standardbetriebsmodus verhindert die Methode Session.close() nicht, dass die Session wieder verwendet wird. Die Session selbst hat keinen eindeutigen "geschlossenen" Zustand; sie bedeutet lediglich, dass die Session alle Datenbankverbindungen und ORM-Objekte freigibt.

Wenn der Parameter Session.close_resets_only auf False gesetzt wird, wird close endgültig, was bedeutet, dass jede weitere Aktion auf der Session verboten ist.

Geändert in Version 1.4: Die Methode Session.close() erstellt nicht sofort ein neues SessionTransaction-Objekt; stattdessen wird das neue SessionTransaction nur erstellt, wenn die Session für eine Datenbankoperation erneut verwendet wird.

Siehe auch

Schließen - Details zu den Semantiken von Session.close() und Session.reset().

Session.reset() - eine ähnliche Methode, die wie close() mit dem Parameter Session.close_resets_only auf True gesetzt funktioniert.

classmethod sqlalchemy.orm.Session.close_all() → None¶: Geerbt von der sqlalchemy.orm.session._SessionClassMethods.close_all Methode von sqlalchemy.orm.session._SessionClassMethods

Schließt *alle* Sessions im Speicher.

Veraltet seit Version 1.3: Die Methode Session.close_all() ist veraltet und wird in einer zukünftigen Version entfernt. Bitte beziehen Sie sich auf close_all_sessions().

method sqlalchemy.orm.Session.commit() → None¶

Bestätigt ausstehende Änderungen und committet die aktuelle Transaktion.

Wenn die COMMIT-Operation abgeschlossen ist, werden alle Objekte vollständig abgelaufen sein, wodurch ihr interner Inhalt gelöscht wird. Dieser wird automatisch neu geladen, wenn auf die Objekte das nächste Mal zugegriffen wird. In der Zwischenzeit befinden sich diese Objekte in einem abgelaufenen Zustand und funktionieren nicht, wenn sie von der Session detached sind. Darüber hinaus wird dieser Neu-Ladevorgang nicht unterstützt, wenn asyncio-orientierte APIs verwendet werden. Der Parameter Session.expire_on_commit kann verwendet werden, um dieses Verhalten zu deaktivieren.

Wenn keine Transaktion für die Session aktiv ist, was bedeutet, dass seit dem letzten Aufruf von Session.commit() keine Operationen auf dieser Session aufgerufen wurden, beginnt die Methode eine interne "logische" Transaktion und committet sie. Diese beeinflusst die Datenbank normalerweise nicht, es sei denn, es wurden ausstehende Flush-Änderungen erkannt, aber sie ruft dennoch Event-Handler und Objekt-Ablaufregeln auf.

Die äußerste Datenbanktransaktion wird bedingungslos committet, wobei alle aktiven SAVEPOINTs automatisch freigegeben werden.

Siehe auch

Commit

Transaktionen verwalten

Verhindern von impliziten E/A bei Verwendung von AsyncSession

method sqlalchemy.orm.Session.connection(bind_arguments: _BindArguments | None = None, execution_options: CoreExecuteOptionsParameter | None = None) → Connection¶

Gibt ein Connection-Objekt zurück, das dem transaktionalen Zustand dieses Session-Objekts entspricht.

Entweder wird die Connection, die der aktuellen Transaktion entspricht, zurückgegeben, oder wenn keine Transaktion aktiv ist, wird eine neue gestartet und die Connection zurückgegeben (beachten Sie, dass bis zur ersten SQL-Anweisung kein transaktionaler Zustand mit DBAPI hergestellt wird).

Mehrdeutigkeiten bei Multi-Bind- oder ungebundenen Session-Objekten können durch beliebige der optionalen Schlüsselwortargumente aufgelöst werden. Dies führt letztendlich zur Verwendung der get_bind()-Methode zur Auflösung.

Parameter:

bind_arguments¶ – Wörterbuch mit Bindungsargumenten. Kann "mapper", "bind", "clause" und andere benutzerdefinierte Argumente enthalten, die an Session.get_bind() übergeben werden.
execution_options¶ –
ein Wörterbuch mit Ausführungsoptionen, die an Connection.execution_options() übergeben werden, nur wenn die Verbindung zum ersten Mal beschafft wird. Wenn die Verbindung bereits innerhalb der Session vorhanden ist, wird eine Warnung ausgegeben und die Argumente werden ignoriert.

Siehe auch

Transaktionsisolationslevel / DBAPI AUTOCOMMIT einstellen

method sqlalchemy.orm.Session.delete(instance: object) → None¶

Markiert eine Instanz als gelöscht.

Es wird angenommen, dass das Objekt bei der Übergabe entweder persistent oder detached ist. Nach dem Aufruf der Methode verbleibt das Objekt im persistent Zustand bis zum nächsten Flush. Während dieser Zeit ist das Objekt auch Mitglied der Sammlung Session.deleted.

Beim nächsten Flush wechselt das Objekt in den deleted-Zustand, was darauf hinweist, dass eine DELETE-Anweisung für seine Zeile innerhalb der aktuellen Transaktion ausgegeben wurde. Wenn die Transaktion erfolgreich committet wird, wechselt das gelöschte Objekt in den detached-Zustand und ist in dieser Session nicht mehr vorhanden.

Siehe auch

Löschen - in Grundlagen der Verwendung einer Session

attribute sqlalchemy.orm.Session.deleted¶: Die Menge aller Instanzen, die in dieser Session als „gelöscht“ markiert sind.

attribute sqlalchemy.orm.Session.dirty¶

Die Menge aller persistenten Instanzen, die als schmutzig gelten.

Z. B.

some_mapped_object in session.dirty

Instanzen gelten als schmutzig, wenn sie modifiziert, aber nicht gelöscht wurden.

Beachten Sie, dass diese „schmutzige“ Berechnung „optimistisch“ ist; die meisten Attributsetz- oder Sammlungsmodifikationsoperationen markieren eine Instanz als „schmutzig“ und platzieren sie in dieser Menge, auch wenn keine Nettoänderung am Attributwert vorliegt. Beim Flush wird der Wert jedes Attributs mit seinem zuvor gespeicherten Wert verglichen, und wenn keine Nettoänderung vorliegt, wird keine SQL-Operation durchgeführt (dies ist eine aufwändigere Operation, daher wird sie nur beim Flush durchgeführt).

Um zu prüfen, ob eine Instanz wirksame Nettchanges an ihren Attributen hat, verwenden Sie die Methode Session.is_modified().

method sqlalchemy.orm.Session.enable_relationship_loading(obj: object) → None¶

Ordnet ein Objekt dieser Session für das Laden von zugehörigen Objekten zu.

Warnung

enable_relationship_loading() dient speziellen Anwendungsfällen und wird nicht für den allgemeinen Gebrauch empfohlen.

Zugriffe auf Attribute, die mit relationship() abgebildet sind, versuchen, einen Wert aus der Datenbank zu laden, indem sie diese Session als Quelle für die Konnektivität verwenden. Die Werte werden basierend auf den Fremdschlüssel- und Primärschlüsselwerten dieses Objekts geladen – wenn diese nicht vorhanden sind, sind diese Beziehungen nicht verfügbar.

Das Objekt wird an diese Session angehängt, nimmt aber **nicht** an Persistenzoperationen teil; sein Zustand bleibt für fast alle Zwecke "transient" oder "detached", außer im Fall des Ladens von Beziehungen.

Beachten Sie auch, dass Backrefs oft nicht wie erwartet funktionieren. Das Ändern eines beziehungsgebundenen Attributs des Zielobjekts löst möglicherweise kein Backref-Ereignis aus, wenn der effektive Wert derjenige ist, der bereits aus einem Fremdschlüsselwert geladen wurde.

Die Methode Session.enable_relationship_loading() ist ähnlich dem Flag load_on_pending in relationship(). Im Gegensatz zu diesem Flag ermöglicht Session.enable_relationship_loading() einem Objekt, transient zu bleiben und trotzdem verwandte Elemente laden zu können.

Um ein transienten Objekt, das über Session.enable_relationship_loading() mit einer Session verbunden ist, als ausstehend zu markieren, fügen Sie es normal mit Session.add() zur Session hinzu. Wenn das Objekt stattdessen eine bestehende Identität in der Datenbank darstellt, sollte es mit Session.merge() gemergt werden.

Session.enable_relationship_loading() verbessert das Verhalten nicht, wenn das ORM normal verwendet wird - Objektverweise sollten auf Objektebene und nicht auf Fremdschlüsselebene konstruiert werden, damit sie vor dem Flush() auf normale Weise vorhanden sind. Diese Methode ist nicht für den allgemeinen Gebrauch bestimmt.

Siehe auch

relationship.load_on_pending - dieses Flag ermöglicht das Laden von Many-to-Ones für Elemente, die ausstehend sind, pro Beziehung.

make_transient_to_detached() - ermöglicht es, ein Objekt ohne SQL-Ausgabe zu einer Session hinzuzufügen, was dann beim Zugriff auf Attribute, die abgelaufen sind, wieder aktiv wird.

method sqlalchemy.orm.Session.execute(statement: Executable, params: _CoreAnyExecuteParams | None = None, *, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: _BindArguments | None = None, _parent_execute_state: Any | None = None, _add_event: Any | None = None) → Result[Any]¶

Führt eine SQL-Ausdruckskonstruktion aus.

Gibt ein Result-Objekt zurück, das die Ergebnisse der Ausführung der Anweisung darstellt.

Z. B.

from sqlalchemy import select

result = session.execute(select(User).where(User.id == 5))

Der API-Vertrag von Session.execute() ähnelt dem von Connection.execute(), der 2.0-Stil von Connection.

Geändert in Version 1.4: Die Methode Session.execute() ist nun der primäre Punkt für die ORM-Anweisungsausführung bei der Verwendung des 2.0-Stils.

Parameter:

statement¶ – Eine ausführbare Anweisung (d. h. ein Executable-Ausdruck wie select()).
params¶ – Optionales Wörterbuch oder Liste von Wörterbüchern mit gebundenen Parametern. Wenn es sich um ein einzelnes Wörterbuch handelt, wird eine Einzelzeilenausführung durchgeführt; wenn es sich um eine Liste von Wörterbüchern handelt, wird ein "executemany" aufgerufen. Die Schlüssel in jedem Wörterbuch müssen den Parameternamen entsprechen, die in der Anweisung vorhanden sind.
execution_options¶ –
optionales Wörterbuch mit Ausführungsoptionen, die der Ausführung der Anweisung zugeordnet werden. Dieses Wörterbuch kann eine Teilmenge der Optionen bereitstellen, die von Connection.execution_options() akzeptiert werden, und kann auch zusätzliche Optionen bereitstellen, die nur im ORM-Kontext verstanden werden.

Siehe auch

ORM-Ausführungsoptionen - ORM-spezifische Ausführungsoptionen
bind_arguments¶ – Wörterbuch mit zusätzlichen Argumenten zur Bestimmung der Bindung. Kann "mapper", "bind" oder andere benutzerdefinierte Argumente enthalten. Der Inhalt dieses Wörterbuchs wird an die Methode Session.get_bind() übergeben.

Gibt zurück:

ein Result-Objekt.

method sqlalchemy.orm.Session.expire(instance: object, attribute_names: Iterable[str] | None = None) → None¶

Lässt die Attribute einer Instanz verfallen.

Markiert die Attribute einer Instanz als veraltet. Wenn auf ein abgelaufenes Attribut zugegriffen wird, wird eine Abfrage im aktuellen Transaktionskontext des Session-Objekts ausgeführt, um alle abgelaufenen Attribute für die gegebene Instanz zu laden. Beachten Sie, dass eine stark isolierte Transaktion dieselben Werte zurückgibt, die in derselben Transaktion zuvor gelesen wurden, unabhängig von Änderungen im Datenbankzustand außerhalb dieser Transaktion.

Um alle Objekte in der Session gleichzeitig ablaufen zu lassen, verwenden Sie Session.expire_all().

Das Standardverhalten des Session-Objekts ist, allen Zustand ablaufen zu lassen, wenn die Methoden Session.rollback() oder Session.commit() aufgerufen werden, damit für die neue Transaktion neue Zustände geladen werden können. Aus diesem Grund ist der Aufruf von Session.expire() nur für den spezifischen Fall sinnvoll, dass in der aktuellen Transaktion eine Nicht-ORM-SQL-Anweisung ausgegeben wurde.

Parameter:

instance¶ – Die zu aktualisierende Instanz.
attribute_names¶ – optionales Liste von Zeichenketten-Attributnamen, die eine Teilmenge der ablaufenden Attribute angeben.

Siehe auch

Aktualisieren / Ablaufen lassen - einführendes Material

Session.expire()

Session.refresh()

Query.populate_existing()

method sqlalchemy.orm.Session.expire_all() → None¶

Lässt alle persistenten Instanzen innerhalb dieser Session verfallen.

Wenn auf ein beliebiges Attribut einer persistenten Instanz zugegriffen wird, wird eine Abfrage mit dem aktuellen Transaktionskontext des Session-Objekts ausgeführt, um alle abgelaufenen Attribute für die gegebene Instanz zu laden. Beachten Sie, dass eine stark isolierte Transaktion dieselben Werte zurückgibt, die in derselben Transaktion zuvor gelesen wurden, unabhängig von Änderungen im Datenbankzustand außerhalb dieser Transaktion.

Um einzelne Objekte und einzelne Attribute auf diesen Objekten ablaufen zu lassen, verwenden Sie Session.expire().

Das Standardverhalten des Session-Objekts ist, allen Zustand ablaufen zu lassen, wenn die Methoden Session.rollback() oder Session.commit() aufgerufen werden, damit für die neue Transaktion neue Zustände geladen werden können. Aus diesem Grund ist der Aufruf von Session.expire_all() normalerweise nicht erforderlich, vorausgesetzt, die Transaktion ist isoliert.

Siehe auch

Aktualisieren / Ablaufen lassen - einführendes Material

Session.expire()

Session.refresh()

Query.populate_existing()

method sqlalchemy.orm.Session.expunge(instance: object) → None¶

Entfernt die instance aus dieser Session.

Dies gibt alle internen Referenzen auf die Instanz frei. Kaskadierung wird gemäß der *expunge*-Kaskadenregel angewendet.

method sqlalchemy.orm.Session.expunge_all() → None¶

Entfernt alle Objektinstanzen aus dieser Session.

Dies entspricht dem Aufruf von expunge(obj) für alle Objekte in dieser Session.

method sqlalchemy.orm.Session.flush(objects: Sequence[Any] | None = None) → None¶

Flush aller Objektänderungen an die Datenbank.

Schreibt alle ausstehenden Objekterstellungen, Löschungen und Modifikationen als INSERTs, DELETEs, UPDATEs usw. in die Datenbank. Operationen werden automatisch vom Abhängigkeitslöser der Session-Einheit durchgeführt.

Datenbankoperationen werden im aktuellen Transaktionskontext ausgegeben und wirken sich nicht auf den Zustand der Transaktion aus, es sei denn, es tritt ein Fehler auf, in diesem Fall wird die gesamte Transaktion zurückgerollt. Sie können flush() beliebig oft innerhalb einer Transaktion aufrufen, um Änderungen von Python in den Transaktionspuffer der Datenbank zu verschieben.

Parameter:

objects¶ –

Optional; beschränkt die Flush-Operation auf Elemente, die sich in der angegebenen Sammlung befinden.

Diese Funktion ist für eine extrem geringe Anzahl von Anwendungsfällen gedacht, bei denen bestimmte Objekte vor dem vollständigen Flush() bearbeitet werden müssen. Sie ist nicht für den allgemeinen Gebrauch bestimmt.

method sqlalchemy.orm.Session.get(entity: _EntityBindKey[_O], ident: _PKIdentityArgument, *, options: Sequence[ORMOption] | None = None, populate_existing: bool = False, with_for_update: ForUpdateParameter = None, identity_token: Any | None = None, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: _BindArguments | None = None) → _O | None¶

Gibt eine Instanz basierend auf der angegebenen Primärschlüssel-ID zurück, oder None, wenn sie nicht gefunden wurde.

Z. B.

my_user = session.get(User, 5)

some_object = session.get(VersionedFoo, (5, 10))

some_object = session.get(VersionedFoo, {"id": 5, "version_id": 10})

Neu in Version 1.4: Session.get() hinzugefügt, das aus der nun veralteten Methode Query.get() verschoben wurde.

Session.get() ist besonders, da es direkten Zugriff auf die Identitätskarte der Session bietet. Wenn der angegebene Primärschlüsselidentifikator in der lokalen Identitätskarte vorhanden ist, wird das Objekt direkt aus dieser Sammlung zurückgegeben und es wird kein SQL ausgegeben, es sei denn, das Objekt wurde als vollständig abgelaufen markiert. Wenn es nicht vorhanden ist, wird eine SELECT-Abfrage durchgeführt, um das Objekt zu lokalisieren.

Session.get() prüft auch, ob das Objekt in der Identitätskarte vorhanden und als abgelaufen markiert ist - eine SELECT-Abfrage wird ausgegeben, um das Objekt zu aktualisieren und sicherzustellen, dass die Zeile noch vorhanden ist. Wenn nicht, wird ObjectDeletedError ausgelöst.

Parameter:

entity¶ – eine gemappte Klasse oder ein Mapper, die den Typ der zu ladenden Entität angibt.
ident¶ –
Ein Skalar, Tupel oder Wörterbuch, das den Primärschlüssel darstellt. Für einen zusammengesetzten (z. B. mehrspaltigen) Primärschlüssel sollte ein Tupel oder Wörterbuch übergeben werden.

Für einen einspaltigen Primärschlüssel ist die skalare Aufrufform in der Regel die praktikabelste. Wenn der Primärschlüssel einer Zeile der Wert „5“ ist, sieht der Aufruf wie folgt aus
```
my_object = session.get(SomeClass, 5)
```
Die Tupelform enthält Primärschlüsselwerte, typischerweise in der Reihenfolge, in der sie den Spalten des gemappten Table-Objekts entsprechen, oder, wenn der Parameter Mapper.primary_key verwendet wurde, in der für diesen Parameter verwendeten Reihenfolge. Zum Beispiel, wenn der Primärschlüssel einer Zeile durch die Ganzzahlen "5, 10" dargestellt wird, würde der Aufruf so aussehen
```
my_object = session.get(SomeClass, (5, 10))
```
Die Wörterbuchform sollte als Schlüssel die zugeordneten Attributnamen enthalten, die jedem Element des Primärschlüssels entsprechen. Wenn die zugeordnete Klasse die Attribute id und version_id als Attribute hat, die den Primärschlüsselwert des Objekts speichern, sähe der Aufruf wie folgt aus
```
my_object = session.get(SomeClass, {"id": 5, "version_id": 10})
```
options¶ – optionale Sequenz von Ladeoptionen, die auf die Abfrage angewendet werden, falls eine solche ausgegeben wird.
populate_existing¶ – bewirkt, dass die Methode bedingungslos eine SQL-Abfrage ausgibt und das Objekt mit den neu geladenen Daten aktualisiert, unabhängig davon, ob das Objekt bereits vorhanden ist oder nicht.
with_for_update¶ – optionales boolesches True, das angibt, dass FOR UPDATE verwendet werden soll, oder ein Wörterbuch mit Flags, das eine spezifischere Menge von FOR UPDATE-Flags für das SELECT angibt; Flags sollten mit den Parametern von Query.with_for_update() übereinstimmen. Überschreibt den Parameter Session.refresh.lockmode.
execution_options¶ –
optionales Wörterbuch von Ausführungsoptionen, die der Abfrageausführung zugeordnet werden, falls eine solche ausgegeben wird. Dieses Wörterbuch kann eine Teilmenge der Optionen bereitstellen, die von Connection.execution_options() akzeptiert werden, und kann auch zusätzliche Optionen bereitstellen, die nur in einem ORM-Kontext verstanden werden.

Neu in Version 1.4.29.

Siehe auch

ORM-Ausführungsoptionen - ORM-spezifische Ausführungsoptionen
bind_arguments¶ –
Wörterbuch zusätzlicher Argumente zur Bestimmung der Bindung. Kann "mapper", "bind" oder andere benutzerdefinierte Argumente enthalten. Der Inhalt dieses Wörterbuchs wird an die Methode Session.get_bind() übergeben.

Gibt zurück:

Die Objektinstanz oder None.

method sqlalchemy.orm.Session.get_bind(mapper: _EntityBindKey[_O] | None = None, *, clause: ClauseElement | None = None, bind: _SessionBind | None = None, _sa_skip_events: bool | None = None, _sa_skip_for_implicit_returning: bool = False, **kw: Any) → Engine | Connection¶

Gibt eine "Bindung" zurück, an die diese Session gebunden ist.

Die "Bindung" ist normalerweise eine Instanz von Engine, außer wenn die Session explizit an eine Connection gebunden wurde.

Bei einer mehrfach gebundenen oder ungebundenen Session werden die Argumente mapper oder clause verwendet, um die entsprechende Bindung zu ermitteln, die zurückgegeben werden soll.

Beachten Sie, dass das Argument "mapper" normalerweise vorhanden ist, wenn Session.get_bind() über eine ORM-Operation wie eine Session.query(), jede einzelne INSERT/UPDATE/DELETE-Operation innerhalb einer Session.flush(), einen Aufruf usw. aufgerufen wird.

Die Reihenfolge der Auflösung ist

Wenn ein Mapper gegeben ist und Session.binds vorhanden ist, wird eine Bindung basierend auf dem verwendeten Mapper, dann auf der verwendeten gemappten Klasse und dann auf allen Basisklassen, die in der __mro__ der gemappten Klasse vorhanden sind, von spezifischeren zu allgemeineren Oberklassen ermittelt.
Wenn eine Klausel gegeben ist und Session.binds vorhanden ist, wird eine Bindung basierend auf Table-Objekten ermittelt, die in der gegebenen Klausel vorhanden sind und sich in Session.binds befinden.
Wenn Session.binds vorhanden ist, geben Sie diese zurück.
Wenn eine Klausel gegeben ist, wird versucht, eine Bindung zurückzugeben, die mit der MetaData verbunden ist, die letztendlich mit der Klausel verbunden ist.
Wenn ein Mapper gegeben ist, wird versucht, eine Bindung zurückzugeben, die mit der MetaData verbunden ist, die letztendlich mit der Table oder einem anderen Selektierbaren verbunden ist, zu dem der Mapper zugeordnet ist.
Es kann keine Bindung gefunden werden, es wird UnboundExecutionError ausgelöst.

Beachten Sie, dass die Methode Session.get_bind() in einer benutzerdefinierten Unterklasse von Session überschrieben werden kann, um beliebige Bindungsauflösungsschemata bereitzustellen. Siehe das Beispiel unter Benutzerdefinierte vertikale Partitionierung.

Parameter:

mapper¶ – Optionale gemappte Klasse oder entsprechende Mapper-Instanz. Die Bindung kann von einem Mapper abgeleitet werden, indem zuerst die "binds"-Map konsultiert wird, die dieser Session zugeordnet ist, und zweitens durch Konsultation der MetaData, die der Table zugeordnet ist, zu der der Mapper zugeordnet ist, um eine Bindung zu finden.
clause¶ – Ein ClauseElement (d. h. select(), text(), usw.). Wenn das Argument mapper nicht vorhanden ist oder keine Bindung erzeugen konnte, wird der gegebene Ausdruckskonstrukt nach einem gebundenen Element durchsucht, typischerweise einer Table, die mit einer gebundenen MetaData verbunden ist.

Siehe auch

Partitionierungsstrategien (z. B. mehrere Datenbank-Backends pro Session)

Session.binds

Session.bind_mapper()

Session.bind_table()

method sqlalchemy.orm.Session.get_nested_transaction() → SessionTransaction | None¶: Gibt die aktuelle verschachtelte Transaktion zurück, falls vorhanden.

Neu in Version 1.4.

method sqlalchemy.orm.Session.get_one(entity: _EntityBindKey[_O], ident: _PKIdentityArgument, *, options: Sequence[ORMOption] | None = None, populate_existing: bool = False, with_for_update: ForUpdateParameter = None, identity_token: Any | None = None, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: _BindArguments | None = None) → _O¶

Gibt genau eine Instanz basierend auf dem angegebenen Primärschlüssel-Identifikator zurück, oder löst eine Ausnahme aus, wenn sie nicht gefunden wird.

Löst sqlalchemy.orm.exc.NoResultFound aus, wenn die Abfrage keine Zeilen auswählt.

Für eine detaillierte Dokumentation der Argumente siehe die Methode Session.get().

Neu in Version 2.0.22.

Gibt zurück:: Die Objektinstanz.

Siehe auch

Session.get() - äquivalente Methode, die stattdessen: gibt None zurück, wenn keine Zeile mit dem angegebenen Primärschlüssel gefunden wurde

method sqlalchemy.orm.Session.get_transaction() → SessionTransaction | None¶: Gibt die aktuelle Root-Transaktion zurück, falls vorhanden.

Neu in Version 1.4.

Geerbt von der sqlalchemy.orm.session._SessionClassMethods.identity_key Methode von sqlalchemy.orm.session._SessionClassMethods

Gibt einen Identitätsschlüssel zurück.

Dies ist ein Alias für identity_key().

attribute sqlalchemy.orm.Session.identity_map: IdentityMap¶

Eine Zuordnung von Objektidentitäten zu Objekten selbst.

Die Iteration durch Session.identity_map.values() ermöglicht den Zugriff auf die gesamte Menge der persistenten Objekte (d. h. solche mit Zeilenidentität), die sich derzeit in der Sitzung befinden.

Siehe auch

identity_key() - Hilfsfunktion zur Erzeugung der Schlüssel, die in diesem Wörterbuch verwendet werden.

method sqlalchemy.orm.Session.in_nested_transaction() → bool¶: Gibt True zurück, wenn diese Session eine verschachtelte Transaktion begonnen hat, z. B. SAVEPOINT.

Neu in Version 1.4.

method sqlalchemy.orm.Session.in_transaction() → bool¶: Gibt True zurück, wenn diese Session eine Transaktion begonnen hat.

Neu in Version 1.4.

Siehe auch

Session.is_active

attribute sqlalchemy.orm.Session.info¶

Ein benutzerdefinierbares Dictionary.

Der Anfangswert dieses Wörterbuchs kann über das Argument info für den Konstruktor Session oder den Konstruktor sessionmaker oder Factory-Methoden gefüllt werden. Das hier verwendete Wörterbuch ist immer lokal für diese Session und kann unabhängig von allen anderen Session-Objekten geändert werden.

method sqlalchemy.orm.Session.invalidate() → None¶

Schließt diese Sitzung und verwendet die Invalidation der Verbindung.

Dies ist eine Variante von Session.close(), die zusätzlich sicherstellt, dass die Methode Connection.invalidate() für jede Connection-Instanz aufgerufen wird, die sich derzeit in einer Transaktion in Verwendung befindet (typischerweise gibt es nur eine Verbindung, es sei denn, die Session wird mit mehreren Engines verwendet).

Dies kann aufgerufen werden, wenn die Datenbank bekanntermaßen in einem Zustand ist, in dem die Verbindungen nicht mehr sicher verwendet werden können.

Das Folgende veranschaulicht ein Szenario bei der Verwendung von gevent, das Timeout-Ausnahmen erzeugen kann, was bedeuten kann, dass die zugrunde liegende Verbindung verworfen werden sollte

import gevent

try:
    sess = Session()
    sess.add(User())
    sess.commit()
except gevent.Timeout:
    sess.invalidate()
    raise
except:
    sess.rollback()
    raise

Die Methode tut zusätzlich alles, was Session.close() tut, einschließlich der Tatsache, dass alle ORM-Objekte gelöscht werden.

attribute sqlalchemy.orm.Session.is_active¶

True, wenn sich diese Session nicht im Zustand "partielles Rollback" befindet.

Geändert in Version 1.4: Die Session beginnt keine Transaktion mehr sofort, daher ist dieses Attribut False, wenn die Session zum ersten Mal instanziiert wird.

Der Zustand "partielles Rollback" zeigt typischerweise an, dass der Flush-Prozess der Session fehlgeschlagen ist und dass die Methode Session.rollback() aufgerufen werden muss, um die Transaktion vollständig zurückzurollen.

Wenn diese Session überhaupt nicht in einer Transaktion ist, wird die Session automatisch gestartet, wenn sie zum ersten Mal verwendet wird. In diesem Fall gibt Session.is_active True zurück.

Andernfalls, wenn sich diese Session innerhalb einer Transaktion befindet und diese Transaktion nicht intern zurückgerollt wurde, gibt Session.is_active ebenfalls True zurück.

Siehe auch

„Die Transaktion dieser Session wurde aufgrund einer vorherigen Ausnahme während des Flushens zurückgerollt.“ (oder ähnlich)

Session.in_transaction()

method sqlalchemy.orm.Session.is_modified(instance: object, include_collections: bool = True) → bool¶

Gibt True zurück, wenn die gegebene Instanz lokal geänderte Attribute hat.

Diese Methode ruft die Historie für jedes instrumentierte Attribut der Instanz ab und vergleicht den aktuellen Wert mit seinem zuvor geleerten oder committeten Wert, falls vorhanden.

Es handelt sich im Wesentlichen um eine teurere und genauere Version der Prüfung auf die gegebene Instanz in der Sammlung Session.dirty; es wird eine vollständige Prüfung des Netto-"Dirty"-Status jedes Attributs durchgeführt.

Z. B.

return session.is_modified(someobject)

Einige Vorbehalte zu dieser Methode gelten:

Instanzen, die in der Sammlung Session.dirty vorhanden sind, können bei der Prüfung mit dieser Methode False zurückgeben. Dies liegt daran, dass das Objekt möglicherweise Änderungsereignisse durch Attributmutationen erhalten hat, wodurch es in Session.dirty aufgenommen wurde, aber letztendlich ist der Zustand derselbe wie der aus der Datenbank geladene, was hier zu keiner Nettänderung führt.
Skalare Attribute haben möglicherweise nicht den zuvor gesetzten Wert aufgezeichnet, wenn ein neuer Wert angewendet wurde, falls das Attribut zum Zeitpunkt des Empfangs des neuen Wertes nicht geladen war oder abgelaufen war. In diesen Fällen wird angenommen, dass das Attribut eine Änderung erfahren hat, auch wenn es letztendlich keine Nettobewegung gegenüber seinem Datenbankwert gibt. SQLAlchemy benötigt in den meisten Fällen nicht den „alten“ Wert, wenn ein Set-Ereignis auftritt, und überspringt daher die Kosten eines SQL-Aufrufs, wenn der alte Wert nicht vorhanden ist, basierend auf der Annahme, dass ein UPDATE des skalaren Werts normalerweise erforderlich ist und in den wenigen Fällen, in denen dies nicht der Fall ist, im Durchschnitt weniger kostspielig ist als die Ausgabe eines defensiven SELECTs.

Der „alte“ Wert wird nur dann bedingungslos beim Setzen abgerufen, wenn der Attributcontainer das Flag active_history auf True gesetzt hat. Dieses Flag wird typischerweise für Primärschlüsselattribute und skalare Objektverweise gesetzt, die keine einfachen Many-to-One-Beziehungen sind. Um dieses Flag für eine beliebige zugeordnete Spalte zu setzen, verwenden Sie das Argument active_history mit column_property().

Parameter:

instance¶ – abgebildete Instanz, die auf ausstehende Änderungen geprüft werden soll.
include_collections¶ – Gibt an, ob mehrwertige Sammlungen in die Operation einbezogen werden sollen. Das Setzen auf False ist eine Möglichkeit, nur lokale spaltenbasierte Eigenschaften (d. h. skalare Spalten oder Many-to-One-Fremdschlüssel) zu erkennen, die bei einem Flush zu einem UPDATE für diese Instanz führen würden.

method sqlalchemy.orm.Session.merge(instance: _O, *, load: bool = True, options: Sequence[ORMOption] | None = None) → _O¶

Kopieren Sie den Zustand einer gegebenen Instanz in eine entsprechende Instanz innerhalb dieser Session.

Session.merge() untersucht die Primärschlüsselattribute der Quellinstanz und versucht, sie mit einer Instanz desselben Primärschlüssels in der Sitzung abzugleichen. Wenn sie lokal nicht gefunden wird, versucht sie, das Objekt anhand des Primärschlüssels aus der Datenbank zu laden, und wenn keines gefunden werden kann, wird eine neue Instanz erstellt. Der Zustand jedes Attributs auf der Quellinstanz wird dann auf die Zielinstanz kopiert. Die resultierende Zielinstanz wird dann von der Methode zurückgegeben; die ursprüngliche Quellinstanz bleibt unverändert und von der Session getrennt, falls sie nicht bereits damit verbunden war.

Diese Operation wird auf zugeordnete Instanzen kaskadiert, wenn die Zuordnung mit cascade="merge" zugeordnet ist.

Siehe Merging für eine detaillierte Diskussion des Mergings.

Parameter:

instance¶ – Zu mergende Instanz.
load¶ –
Boolescher Wert, wenn False, schaltet merge() in einen „Hochleistungsmodus“, der dazu führt, dass keine Historienereignisse und kein Datenbankzugriff mehr emittiert werden. Dieses Flag wird für Fälle wie die Übertragung von Objektgraphen in eine Session aus einem Cache zweiter Ebene oder die Übertragung gerade geladener Objekte in die von einem Worker-Thread oder -Prozess besessene Session verwendet, ohne die Datenbank erneut abzufragen.

Der Anwendungsfall load=False fügt die Einschränkung hinzu, dass das gegebene Objekt in einem „sauberen“ Zustand sein muss, d. h. keine ausstehenden Änderungen zur Ausführung hat – auch wenn das eingehende Objekt von jeder Session getrennt ist. Dies liegt daran, dass die Werte beim Mergen, die lokale Attribute füllen und zu verwandten Objekten und Sammlungen kaskadieren, „gestempelt“ auf das Zielobjekt angewendet werden können, ohne dass Historien- oder Attributereignisse generiert werden und ohne die Notwendigkeit, die eingehenden Daten mit vorhandenen verwandten Objekten oder Sammlungen abzugleichen, die möglicherweise nicht geladen sind. Die resultierenden Objekte von load=False werden immer als „sauber“ produziert, daher ist es nur angemessen, dass die gegebenen Objekte ebenfalls „sauber“ sind, andernfalls deutet dies auf eine Fehlverwendung der Methode hin.
options¶ –
optionale Sequenz von Ladeoptionen, die auf die Methode Session.get() angewendet werden, wenn die Merge-Operation die bestehende Version des Objekts aus der Datenbank lädt.

Neu in Version 1.4.24.

Siehe auch

make_transient_to_detached() - bietet ein alternatives Mittel, um ein einzelnes Objekt in die Session zu "mergen"

attribute sqlalchemy.orm.Session.new¶: Die Menge aller Instanzen, die in dieser Session als 'new' markiert sind.

attribute sqlalchemy.orm.Session.no_autoflush¶

Gibt einen Kontextmanager zurück, der Autoflush deaktiviert.

z. B.

with session.no_autoflush:

    some_object = SomeClass()
    session.add(some_object)
    # won't autoflush
    some_object.related_thing = session.query(SomeRelated).first()

Operationen, die innerhalb des with: Blocks ausgeführt werden, unterliegen keinen Flushes, die beim Zugriff auf Abfragen erfolgen. Dies ist nützlich, wenn eine Reihe von Objekten initialisiert wird, die bestehende Datenbankabfragen beinhalten, wobei das unvollständige Objekt noch nicht geflusht werden soll.

classmethod sqlalchemy.orm.Session.object_session(instance: object) → Session | None¶

Geerbt von der sqlalchemy.orm.session._SessionClassMethods.object_session Methode von sqlalchemy.orm.session._SessionClassMethods

Gibt die Session zurück, zu der ein Objekt gehört.

Dies ist ein Alias für object_session().

method sqlalchemy.orm.Session.prepare() → None¶

Bereiten Sie die laufende Transaktion für die Zweiphasen-Commit vor.

Wenn keine Transaktion läuft, löst diese Methode eine InvalidRequestError aus.

Nur Wurzeltransaktionen von Zweiphasen-Sessions können vorbereitet werden. Wenn die aktuelle Transaktion keine solche ist, wird eine InvalidRequestError ausgelöst.

method sqlalchemy.orm.Session.query(*entities: _ColumnsClauseArgument[Any], **kwargs: Any) → Query[Any]¶

Gibt ein neues Query-Objekt zurück, das dieser Session entspricht.

Beachten Sie, dass das Query-Objekt ab SQLAlchemy 2.0 veraltet ist; die select()-Konstruktion wird nun zum Erstellen von ORM-Abfragen verwendet.

Siehe auch

SQLAlchemy Unified Tutorial

ORM Abfragehandbuch

Legacy Query API - Dokumentation der veralteten API

method sqlalchemy.orm.Session.refresh(instance: object, attribute_names: Iterable[str] | None = None, with_for_update: ForUpdateParameter = None) → None¶

Attribute des gegebenen Instanz ablaufen lassen und neu laden.

Die ausgewählten Attribute werden zuerst abgelaufen, wie bei Verwendung von Session.expire(); dann wird eine SELECT-Anweisung an die Datenbank ausgegeben, um spaltenorientierte Attribute mit dem aktuellen Wert zu aktualisieren, der in der aktuellen Transaktion verfügbar ist.

relationship()-orientierte Attribute werden ebenfalls sofort geladen, wenn sie bereits auf dem Objekt eager geladen waren, und zwar mit derselben Eager-Loading-Strategie, mit der sie ursprünglich geladen wurden.

Neu in Version 1.4: - Die Methode Session.refresh() kann auch eager geladene Attribute neu laden.

relationship()-orientierte Attribute, die normalerweise mit der select- (oder "lazy") Loader-Strategie geladen würden, werden ebenfalls geladen, **wenn sie explizit in der Attributsammlung angegeben sind** und eine SELECT-Anweisung für das Attribut unter Verwendung der immediate-Loader-Strategie ausgeben. Wenn lazy geladene Beziehungen nicht in Session.refresh.attribute_names angegeben sind, bleiben sie als "lazy loaded" Attribute erhalten und werden nicht implizit neu geladen.

Geändert in Version 2.0.4: Die Methode Session.refresh() lädt nun lazy geladene relationship()-orientierte Attribute für diejenigen neu, die explizit in der Session.refresh.attribute_names-Sammlung angegeben sind.

Tipp

Während die Methode Session.refresh() sowohl spalten- als auch beziehungsorientierte Attribute neu laden kann, liegt ihr Hauptaugenmerk auf dem Neuladen lokaler spaltenorientierter Attribute einer einzelnen Instanz. Für flexiblere "Refresh"-Funktionalität, einschließlich der Möglichkeit, Attribute mehrerer Objekte gleichzeitig neu zu laden und explizite Kontrolle über Beziehungs-Loader-Strategien zu haben, verwenden Sie stattdessen die Funktion populate existing.

Beachten Sie, dass eine stark isolierte Transaktion dieselben Werte zurückgibt, wie sie zuvor in derselben Transaktion gelesen wurden, unabhängig von Änderungen im Datenbankstatus außerhalb dieser Transaktion. Das Auffrischen von Attributen ist normalerweise nur zu Beginn einer Transaktion sinnvoll, in der die Datenbankzeilen noch nicht zugegriffen wurden.

Parameter:

attribute_names¶ – optional. Eine iterierbare Sammlung von Zeichenketten-Attributnamen, die eine Teilmenge der zu aktualisierenden Attribute angeben.
with_for_update¶ – optionaler boolescher Wert True, der angibt, dass FOR UPDATE verwendet werden soll, oder ein Wörterbuch mit Flags, das eine spezifischere Menge von FOR UPDATE-Flags für das SELECT angibt; die Flags sollten den Parametern von Query.with_for_update() entsprechen. Überschreibt den Parameter Session.refresh.lockmode.

Siehe auch

Aktualisieren / Ablaufen lassen - einführendes Material

Session.expire()

Session.expire_all()

Populate Existing - ermöglicht es jeder ORM-Abfrage, Objekte neu zu laden, wie sie normalerweise geladen würden.

method sqlalchemy.orm.Session.reset() → None¶

Schließen Sie die Transaktionsressourcen und ORM-Objekte, die von dieser Session verwendet werden, und setzen Sie die Sitzung in ihren ursprünglichen Zustand zurück.

Diese Methode bietet dasselbe "nur zurücksetzen"-Verhalten wie die Methode Session.close() in der Vergangenheit, bei der der Zustand der Session so zurückgesetzt wird, als wäre das Objekt brandneu und wieder einsatzbereit. Diese Methode kann daher für Session-Objekte nützlich sein, die Session.close_resets_only auf False setzen, sodass das "nur zurücksetzen"-Verhalten weiterhin verfügbar ist.

Neu in Version 2.0.22.

Siehe auch

Schließen - Details zu den Semantiken von Session.close() und Session.reset().

Session.close() - eine ähnliche Methode verhindert zusätzlich die Wiederverwendung der Sitzung, wenn der Parameter Session.close_resets_only auf False gesetzt ist.

method sqlalchemy.orm.Session.rollback() → None¶

Die aktuelle laufende Transaktion zurückrollen.

Wenn keine Transaktion läuft, ist diese Methode ein Pass-Through.

Die Methode rollt immer die oberste Datenbanktransaktion zurück und verwirft alle laufenden geschachtelten Transaktionen.

Siehe auch

Rollback

Transaktionen verwalten

method sqlalchemy.orm.Session.scalar(statement: Executable, params: _CoreSingleExecuteParams | None = None, *, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: _BindArguments | None = None, **kw: Any) → Any¶

Führt eine Anweisung aus und gibt ein Skalaren-Ergebnis zurück.

Verwendung und Parameter sind identisch mit Session.execute(); das Ergebnis ist ein skalarer Python-Wert.

method sqlalchemy.orm.Session.scalars(statement: Executable, params: _CoreAnyExecuteParams | None = None, *, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: _BindArguments | None = None, **kw: Any) → ScalarResult[Any]¶

Führen Sie eine Anweisung aus und geben Sie die Ergebnisse als Skalare zurück.

Verwendung und Parameter sind identisch mit Session.execute(); das Ergebnis ist ein ScalarResult-Filterobjekt, das einzelne Elemente anstelle von Row-Objekten zurückgibt.

Gibt zurück:: ein ScalarResult-Objekt

Neu in Version 1.4.24: Session.scalars() hinzugefügt

Neu in Version 1.4.26: scoped_session.scalars() hinzugefügt

Siehe auch

Selecting ORM Entities - kontrastiert das Verhalten von Session.execute() mit Session.scalars()

class sqlalchemy.orm.SessionTransaction¶

Eine Transaktion auf Session-Ebene.

SessionTransaction wird von den Methoden Session.begin() und Session.begin_nested() erzeugt. Es ist weitgehend ein internes Objekt, das im modernen Gebrauch einen Kontextmanager für Sitzungstransaktionen bereitstellt.

Dokumentation zur Interaktion mit SessionTransaction finden Sie unter: Managing Transactions.

Geändert in Version 1.4: Die Scoping- und API-Methoden zur direkten Arbeit mit dem Objekt SessionTransaction wurden vereinfacht.

Siehe auch

Transaktionen verwalten

Session.begin()

Session.begin_nested()

Session.rollback()

Session.commit()

Session.in_transaction()

Session.in_nested_transaction()

Session.get_transaction()

Session.get_nested_transaction()

Mitglieder

nested, origin, parent

Klassensignatur

class sqlalchemy.orm.SessionTransaction (sqlalchemy.orm.state_changes._StateChange, sqlalchemy.engine.util.TransactionalContext)

attribute sqlalchemy.orm.SessionTransaction.nested: bool = False¶

Gibt an, ob dies eine geschachtelte Transaktion oder eine SAVEPOINT-Transaktion ist.

Wenn SessionTransaction.nested True ist, wird erwartet, dass auch SessionTransaction.parent vorhanden ist und auf die einschließende SessionTransaction verweist.

Siehe auch

SessionTransaction.origin

attribute sqlalchemy.orm.SessionTransaction.origin: SessionTransactionOrigin¶

Ursprung dieser SessionTransaction.

Verweist auf eine SessionTransactionOrigin-Instanz, die eine Enumeration darstellt, die das Quellereignis angibt, das zur Erstellung dieser SessionTransaction geführt hat.

Neu in Version 2.0.

attribute sqlalchemy.orm.SessionTransaction.parent¶

Das Elternteil SessionTransaction dieser SessionTransaction.

Wenn dieses Attribut None ist, zeigt dies an, dass sich diese SessionTransaction am oberen Ende des Stapels befindet und einem echten "COMMIT"/"ROLLBACK"-Block entspricht. Wenn nicht None, dann ist dies entweder eine "Subtransaktion" (ein internes Markerobjekt, das vom Flush-Prozess verwendet wird) oder eine "verschachtelte" / SAVEPOINT-Transaktion. Wenn das Attribut SessionTransaction.nested True ist, dann ist dies ein SAVEPOINT, und wenn False, zeigt dies eine Subtransaktion an.

class sqlalchemy.orm.SessionTransactionOrigin¶

Zeigt den Ursprung einer SessionTransaction an.

Diese Enumeration ist auf dem Attribut SessionTransaction.origin jedes SessionTransaction-Objekts vorhanden.

Neu in Version 2.0.

Mitglieder

AUTOBEGIN, BEGIN, BEGIN_NESTED, SUBTRANSACTION

Klassensignatur

class sqlalchemy.orm.SessionTransactionOrigin (enum.Enum)

attribute sqlalchemy.orm.SessionTransactionOrigin.AUTOBEGIN = 0¶: Transaktion wurde durch Autobegin gestartet

attribute sqlalchemy.orm.SessionTransactionOrigin.BEGIN = 1¶: Transaktion wurde durch Aufruf von Session.begin() gestartet

attribute sqlalchemy.orm.SessionTransactionOrigin.BEGIN_NESTED = 2¶: Transaktion wurde durch Session.begin_nested() gestartet

attribute sqlalchemy.orm.SessionTransactionOrigin.SUBTRANSACTION = 3¶: Transaktion ist eine interne "Subtransaktion"

Session-Hilfsfunktionen¶

Objektname	Beschreibung
close_all_sessions()	Schließt alle Sessions im Speicher.
make_transient(instance)	Ändert den Zustand der gegebenen Instanz so, dass sie transient ist.
make_transient_to_detached(instance)	Macht die gegebene transiente Instanz detached.
object_session(instance)	Gibt die `Session` zurück, zu der die gegebene Instanz gehört.
was_deleted(object_)	Gibt True zurück, wenn das gegebene Objekt während eines Session-Flushes gelöscht wurde.

function sqlalchemy.orm.close_all_sessions() → None¶

Schließt alle Sessions im Speicher.

Diese Funktion konsultiert ein globales Register aller Session-Objekte und ruft Session.close() für sie auf, was sie in einen sauberen Zustand zurücksetzt.

Diese Funktion ist nicht für den allgemeinen Gebrauch bestimmt, kann aber für Testsuiten im Rahmen des Abbauverfahrens nützlich sein.

Neu in Version 1.3.

function sqlalchemy.orm.make_transient(instance: object) → None¶

Ändert den Zustand der gegebenen Instanz so, dass sie transient ist.

Hinweis

make_transient() ist eine Funktion für Spezialfälle, nur für fortgeschrittene Anwendungsfälle.

Von der gegebenen abgebildeten Instanz wird angenommen, dass sie sich im Zustand persistent oder detached befindet. Die Funktion entfernt ihre Verbindung zu jeder Session sowie ihre InstanceState.identity. Die Auswirkung ist, dass sich das Objekt so verhält, als wäre es neu konstruiert worden, behält aber alle Attribut-/Sammlungswerte, die zum Zeitpunkt des Aufrufs geladen wurden. Das Flag InstanceState.deleted wird ebenfalls zurückgesetzt, wenn dieses Objekt durch die Verwendung von Session.delete() gelöscht wurde.

Warnung

make_transient() "entwertet" nicht und lädt auch keine ORM-abgebildeten Attribute, die zum Zeitpunkt des Aufrufs der Funktion nicht geladen sind, vorab. Dies schließt Attribute ein, die

wurden über Session.expire() verfallen sind
sind als natürliche Folge des Committens einer Session-Transaktion verfallen, z. B. Session.commit()
werden normalerweise lazy loaded, aber derzeit nicht geladen sind
sind "deferred" (siehe Begrenzung, welche Spalten mit Column Deferral geladen werden) und noch nicht geladen sind
waren nicht in der Abfrage enthalten, die dieses Objekt geladen hat, z. B. was in Joined Table Inheritance und anderen Szenarien üblich ist.

Nachdem make_transient() aufgerufen wurde, werden nicht geladene Attribute wie die oben genannten beim Zugriff normalerweise zu None ausgewertet oder eine leere Sammlung für ein sammlungsbezogenes Attribut. Da das Objekt transient und mit keiner Datenbankidentität verbunden ist, werden diese Werte nicht mehr abrufen.

Siehe auch

make_transient_to_detached()

function sqlalchemy.orm.make_transient_to_detached(instance: object) → None¶

Macht die gegebene transiente Instanz detached.

Hinweis

make_transient_to_detached() ist eine Funktion für Spezialfälle, nur für fortgeschrittene Anwendungsfälle.

Der gesamte Attributverlauf der gegebenen Instanz wird zurückgesetzt, als wäre die Instanz frisch aus einer Abfrage geladen worden. Fehlende Attribute werden als abgelaufen markiert. Die Primärschlüsselattribute des Objekts, die erforderlich sind, werden zum "Schlüssel" der Instanz.

Das Objekt kann dann einer Session hinzugefügt oder mit dem Flag load=False gemerged werden, woraufhin es so aussieht, als wäre es so geladen worden, ohne SQL auszugeben.

Dies ist eine spezielle Anwendungsfunktion, die sich von einem normalen Aufruf von Session.merge() unterscheidet, da ein gegebener persistenter Zustand ohne SQL-Aufrufe hergestellt werden kann.

Siehe auch

make_transient()

Session.enable_relationship_loading()

function sqlalchemy.orm.object_session(instance: object) → Session | None¶

Gibt die Session zurück, zu der die gegebene Instanz gehört.

Dies ist im Wesentlichen dasselbe wie der InstanceState.session-Accessor. Siehe dieses Attribut für Details.

function sqlalchemy.orm.util.was_deleted(object_: object) → bool¶

Gibt True zurück, wenn das gegebene Objekt während eines Session-Flushes gelöscht wurde.

Dies gilt unabhängig davon, ob das Objekt persistent oder detached ist.

Siehe auch

InstanceState.was_deleted

Hilfsfunktionen für Attribute und Zustände¶

Diese Funktionen werden von der SQLAlchemy-Attributinstrumentierungs-API bereitgestellt, um eine detaillierte Schnittstelle für den Umgang mit Instanzen, Attributwerten und dem Verlauf zu bieten. Einige davon sind nützlich beim Erstellen von Ereignis-Listener-Funktionen, wie z. B. in ORM-Ereignisse beschrieben.

Objektname	Beschreibung
del_attribute(instance, key)	Löscht den Wert eines Attributs und löst Verlaufsereignisse aus.
flag_dirty(instance)	Markiert eine Instanz als "dirty" ohne ein bestimmtes Attribut zu erwähnen.
flag_modified(instance, key)	Markiert ein Attribut einer Instanz als "modifiziert".
get_attribute(instance, key)	Ruft den Wert eines Attributs ab und löst alle erforderlichen Aufrufbarkeiten aus.
get_history(obj, key[, passive])	Gibt einen `History`-Datensatz für das gegebene Objekt und Attributschlüssel zurück.
History	Ein Tupel aus 3 Elementen (hinzugefügt, unverändert und gelöscht), das die Änderungen darstellt, die an einem instrumentierten Attribut aufgetreten sind.
init_collection(obj, key)	Initialisiert ein Sammlungattribut und gibt den Sammlungsadapter zurück.
instance_state	Gibt den `InstanceState` für ein gegebenes abgebildetes Objekt zurück.
is_instrumented(instance, key)	Gibt True zurück, wenn das gegebene Attribut der gegebenen Instanz vom Attributspaket instrumentiert ist.
object_state(instance)	Gibt den `InstanceState` zurück, der dem gegebenen Objekt zugeordnet ist.
set_attribute(instance, key, value[, initiator])	Setzt den Wert eines Attributs und löst Verlaufsereignisse aus.
set_committed_value(instance, key, value)	Setzt den Wert eines Attributs ohne Verlaufsereignisse.

function sqlalchemy.orm.util.object_state(instance: _T) → InstanceState[_T]¶

Gibt den InstanceState zurück, der dem gegebenen Objekt zugeordnet ist.

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

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

inspect(instance)

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

function sqlalchemy.orm.attributes.del_attribute(instance: object, key: str) → None¶

Löscht den Wert eines Attributs und löst Verlaufsereignisse aus.

Diese Funktion kann unabhängig von der direkt auf die Klasse angewendeten Instrumentierung verwendet werden, d. h. es sind keine Deskriptoren erforderlich. Benutzerdefinierte Attributverwaltungsschemata müssen diese Methode verwenden, um den Attributstatus festzulegen, wie er von SQLAlchemy verstanden wird.

function sqlalchemy.orm.attributes.get_attribute(instance: object, key: str) → Any¶

Ruft den Wert eines Attributs ab und löst alle erforderlichen Aufrufbarkeiten aus.

Diese Funktion kann unabhängig von der direkt auf die Klasse angewendeten Instrumentierung verwendet werden, d. h. es sind keine Deskriptoren erforderlich. Benutzerdefinierte Attributverwaltungsschemata müssen diese Methode verwenden, um die Nutzung des Attributstatus, wie von SQLAlchemy verstanden, zu ermöglichen.

function sqlalchemy.orm.attributes.get_history(obj: object, key: str, passive: PassiveFlag = symbol('PASSIVE_OFF')) → History¶

Gibt einen History-Datensatz für das gegebene Objekt und Attributschlüssel zurück.

Dies ist der **Pre-Flush**-Verlauf für ein bestimmtes Attribut, der jedes Mal zurückgesetzt wird, wenn die Session Änderungen an der aktuellen Datenbanktransaktion ausspült.

Hinweis

Bevorzugen Sie die Verwendung der Accessoren AttributeState.history und AttributeState.load_history(), um den History für Instanzattribute abzurufen.

Parameter:

obj¶ – ein Objekt, dessen Klasse vom Attributspaket instrumentiert ist.
key¶ – Zeichenkettenattributname.
passive¶ – gibt das Ladeverhalten für das Attribut an, wenn der Wert nicht bereits vorhanden ist. Dies ist ein Bitflag-Attribut, das standardmäßig auf das Symbol PASSIVE_OFF gesetzt ist und angibt, dass alle erforderlichen SQL-Anweisungen ausgegeben werden sollten.

Siehe auch

AttributeState.history

AttributeState.load_history() - Ruft den Verlauf mithilfe von Loader-Aufrufables ab, wenn der Wert nicht lokal vorhanden ist.

function sqlalchemy.orm.attributes.init_collection(obj: object, key: str) → CollectionAdapter¶

Initialisiert ein Sammlungattribut und gibt den Sammlungsadapter zurück.

Diese Funktion wird verwendet, um direkten Zugriff auf interne Sammlungen für ein zuvor nicht geladenes Attribut zu erhalten. Z.B.

collection_adapter = init_collection(someobject, "elements")
for elem in values:
    collection_adapter.append_without_event(elem)

Für eine einfachere Möglichkeit, das oben Genannte zu tun, siehe set_committed_value().

Parameter:

obj¶ – ein abgebildetes Objekt
key¶ – Zeichenkettenattributname, an dem sich die Sammlung befindet.

function sqlalchemy.orm.attributes.flag_modified(instance: object, key: str) → None¶

Markiert ein Attribut einer Instanz als "modifiziert".

Dies setzt das Flag "modified" auf der Instanz und etabliert ein bedingungsloses Änderungsereignis für das gegebene Attribut. Das Attribut muss einen vorhandenen Wert haben, sonst wird eine InvalidRequestError ausgelöst.

Um ein Objekt "dirty" zu markieren, ohne sich auf ein bestimmtes Attribut zu beziehen, damit es in einem Flush berücksichtigt wird, verwenden Sie den Aufruf flag_dirty().

Siehe auch

flag_dirty()

function sqlalchemy.orm.attributes.flag_dirty(instance: object) → None¶

Markiert eine Instanz als "dirty" ohne ein bestimmtes Attribut zu erwähnen.

Dies ist ein spezieller Vorgang, der es dem Objekt ermöglicht, den Flush-Prozess zu durchlaufen, um von Ereignissen wie SessionEvents.before_flush() abgefangen zu werden. Beachten Sie, dass für ein Objekt ohne Änderungen, auch wenn es über diese Methode als dirty markiert ist, keine SQL-Anweisungen im Flush-Prozess ausgegeben werden. Ein Handler für SessionEvents.before_flush() kann das Objekt jedoch in der Sammlung Session.dirty sehen und Änderungen daran festlegen, die dann in die ausgegebenen SQL-Anweisungen aufgenommen werden.

Neu seit Version 1.2.

Siehe auch

flag_modified()

function sqlalchemy.orm.attributes.instance_state()¶

Gibt den InstanceState für ein gegebenes abgebildetes Objekt zurück.

Diese Funktion ist die interne Version von object_state(). Die Funktion object_state() und/oder die Funktion inspect() werden hier bevorzugt, da sie jeweils eine aussagekräftige Ausnahme auslösen, wenn das gegebene Objekt nicht abgebildet ist.

function sqlalchemy.orm.instrumentation.is_instrumented(instance, key)¶

Gibt True zurück, wenn das gegebene Attribut der gegebenen Instanz vom Attributspaket instrumentiert ist.

Diese Funktion kann unabhängig von der direkt auf die Klasse angewendeten Instrumentierung verwendet werden, d. h. es sind keine Deskriptoren erforderlich.

function sqlalchemy.orm.attributes.set_attribute(instance: object, key: str, value: Any, initiator: AttributeEventToken | None = None) → None¶

Setzt den Wert eines Attributs und löst Verlaufsereignisse aus.

Diese Funktion kann unabhängig von der direkt auf die Klasse angewendeten Instrumentierung verwendet werden, d. h. es sind keine Deskriptoren erforderlich. Benutzerdefinierte Attributverwaltungsschemata müssen diese Methode verwenden, um den Attributstatus festzulegen, wie er von SQLAlchemy verstanden wird.

Parameter:

instance¶ – das zu modifizierende Objekt
key¶ – Zeichenkettenname des Attributs
value¶ – zuzuweisender Wert
initiator¶ –
eine Instanz von Event, die von einem vorherigen Event-Listener propagiert worden wäre. Dieses Argument wird verwendet, wenn die Funktion set_attribute() innerhalb einer bestehenden Event-Listener-Funktion verwendet wird, bei der ein Event-Objekt bereitgestellt wird; das Objekt kann verwendet werden, um den Ursprung der Event-Kette zu verfolgen.

Neu in Version 1.2.3.

Funktion sqlalchemy.orm.attributes.set_committed_value(instance, key, value)¶

Setzt den Wert eines Attributs ohne Verlaufsereignisse.

Hebt alle vorherigen vorhandenen Verläufe auf. Der Wert sollte ein Skalarwert für Attribute sein, die Skalare enthalten, oder ein Iterable für jedes Attribut, das Sammlungen enthält.

Dies ist dieselbe zugrunde liegende Methode, die verwendet wird, wenn ein Lazy Loader ausgelöst wird und zusätzliche Daten aus der Datenbank lädt. Insbesondere kann diese Methode von Anwendungscode verwendet werden, der zusätzliche Attribute oder Sammlungen über separate Abfragen geladen hat, die dann einer Instanz so angehängt werden können, als ob sie Teil ihres ursprünglichen geladenen Zustands wären.

Klasse sqlalchemy.orm.attributes.History¶

Ein Tupel aus 3 Elementen (hinzugefügt, unverändert und gelöscht), das die Änderungen darstellt, die an einem instrumentierten Attribut aufgetreten sind.

Der einfachste Weg, ein History-Objekt für ein bestimmtes Attribut eines Objekts zu erhalten, ist die Verwendung der Funktion inspect().

from sqlalchemy import inspect

hist = inspect(myobject).attrs.myattribute.history

Jedes Tupelmitglied ist eine Iterable-Sequenz.

added - die Sammlung von Elementen, die dem Attribut hinzugefügt wurden (erstes Tupel-Element).
unchanged - die Sammlung von Elementen, die an dem Attribut nicht geändert wurden (zweites Tupel-Element).
deleted - die Sammlung von Elementen, die aus dem Attribut entfernt wurden (drittes Tupel-Element).

Mitglieder

added, deleted, empty(), has_changes(), non_added(), non_deleted(), sum(), unchanged

Klassensignatur

Klasse sqlalchemy.orm.History (builtins.tuple)

Attribut sqlalchemy.orm.attributes.History.added: Tuple[()] | List[Any]¶: Alias für Feldnummer 0

Attribut sqlalchemy.orm.attributes.History.deleted: Tuple[()] | List[Any]¶: Alias für Feldnummer 2

Methode sqlalchemy.orm.attributes.History.empty() → bool¶: Gibt True zurück, wenn dieser History keine Änderungen und keinen bestehenden, unveränderten Zustand hat.

Methode sqlalchemy.orm.attributes.History.has_changes() → bool¶: Gibt True zurück, wenn dieser History Änderungen aufweist.

Methode sqlalchemy.orm.attributes.History.non_added() → Sequence[Any]¶: Gibt eine Sammlung von unveränderten + gelöschten Elementen zurück.

Methode sqlalchemy.orm.attributes.History.non_deleted() → Sequence[Any]¶: Gibt eine Sammlung von hinzugefügten + unveränderten Elementen zurück.

Methode sqlalchemy.orm.attributes.History.sum() → Sequence[Any]¶: Gibt eine Sammlung von hinzugefügten + unveränderten + gelöschten Elementen zurück.

Attribut sqlalchemy.orm.attributes.History.unchanged: Tuple[()] | List[Any]¶: Alias für Feldnummer 1

SQLAlchemy 2.0 Dokumentation

SQLAlchemy 2.0 Dokumentation

SQLAlchemy ORM

Projektversionen

Session API¶

Session und sessionmaker()¶

Session-Hilfsfunktionen¶

Hilfsfunktionen für Attribute und Zustände¶