SQLAlchemy 2.0 Dokumentation

SessionEvents.before_commit()

method sqlalchemy.orm.SessionEvents.after_begin(session: Session, transaction: SessionTransaction, connection: Connection) → None¶

Wird ausgeführt, nachdem eine Transaktion für eine Verbindung begonnen wurde.

Beispielhafte Argumentformen

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'after_begin')
def receive_after_begin(session, transaction, connection):
    "listen for the 'after_begin' event"

    # ... (event handling logic) ...

Hinweis

Dieses Ereignis wird während des Prozesses aufgerufen, bei dem die Session ihren internen Zustand ändert. Um SQL-Operationen innerhalb dieses Hooks aufzurufen, verwenden Sie die der Ereignisübergabe bereitgestellte Connection; führen Sie keine SQL-Operationen direkt über die Session aus.

Parameter:

session¶ – Die Ziel-Session.
transaction¶ – Die SessionTransaction.
connection¶ – Das Connection-Objekt, das für SQL-Anweisungen verwendet wird.

Siehe auch

SessionEvents.after_commit()

QueryEvents.before_compile_delete()

method sqlalchemy.orm.SessionEvents.after_bulk_delete(delete_context: _O) → None¶

Ereignis nach Aufruf der Legacy-Methode Query.delete().

Beispielhafte Argumentformen

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'after_bulk_delete')
def receive_after_bulk_delete(delete_context):
    "listen for the 'after_bulk_delete' event"

    # ... (event handling logic) ...

# DEPRECATED calling style (pre-0.9, will be removed in a future release)
@event.listens_for(SomeSessionClassOrObject, 'after_bulk_delete')
def receive_after_bulk_delete(session, query, query_context, result):
    "listen for the 'after_bulk_delete' event"

    # ... (event handling logic) ...

Geändert in Version 0.9: Das Ereignis SessionEvents.after_bulk_delete() akzeptiert nun die Argumente SessionEvents.after_bulk_delete.delete_context. Die Unterstützung für Listener-Funktionen, die die vorherigen Argument-Signaturen (wie oben aufgeführt) als „veraltet“ akzeptieren, wird in einer zukünftigen Version entfernt.

Legacy-Funktion

Die Methode SessionEvents.after_bulk_delete() ist ab SQLAlchemy 2.0 ein Legacy-Ereignishook. Das Ereignis nimmt nicht teil an 2.0-Stil-Aufrufen unter Verwendung von delete(), wie unter ORM UPDATE und DELETE mit benutzerdefinierten WHERE-Kriterien dokumentiert. Für die Verwendung im 2.0-Stil fängt der Hook SessionEvents.do_orm_execute() diese Aufrufe ab.

Parameter:

delete_context¶ –

ein „delete context“-Objekt, das Details zur Löschung enthält, einschließlich dieser Attribute

session - die beteiligte Session

query - das Query-Objekt, auf dem dieser Löschvorgang aufgerufen wurde.

result das CursorResult, das als Ergebnis des Bulk-DELETE-Vorgangs zurückgegeben wird.

Geändert in Version 1.4: Der update_context hat kein QueryContext-Objekt mehr, das ihm zugeordnet ist.

Siehe auch

SessionEvents.after_bulk_update()

method sqlalchemy.orm.SessionEvents.after_bulk_update(update_context: _O) → None¶

Ereignis nach Aufruf der Legacy-Methode Query.update().

Beispielhafte Argumentformen

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'after_bulk_update')
def receive_after_bulk_update(update_context):
    "listen for the 'after_bulk_update' event"

    # ... (event handling logic) ...

# DEPRECATED calling style (pre-0.9, will be removed in a future release)
@event.listens_for(SomeSessionClassOrObject, 'after_bulk_update')
def receive_after_bulk_update(session, query, query_context, result):
    "listen for the 'after_bulk_update' event"

    # ... (event handling logic) ...

Geändert in Version 0.9: Das Ereignis SessionEvents.after_bulk_update() akzeptiert nun die Argumente SessionEvents.after_bulk_update.update_context. Die Unterstützung für Listener-Funktionen, die die vorherigen Argument-Signaturen (wie oben aufgeführt) als „veraltet“ akzeptieren, wird in einer zukünftigen Version entfernt.

Legacy-Funktion

Die Methode SessionEvents.after_bulk_update() ist ab SQLAlchemy 2.0 ein Legacy-Ereignishook. Das Ereignis nimmt nicht teil an 2.0-Stil-Aufrufen unter Verwendung von update(), wie unter ORM UPDATE und DELETE mit benutzerdefinierten WHERE-Kriterien dokumentiert. Für die Verwendung im 2.0-Stil fängt der Hook SessionEvents.do_orm_execute() diese Aufrufe ab.

Parameter:

update_context¶ –

ein „update context“-Objekt, das Details zur Aktualisierung enthält, einschließlich dieser Attribute

session - die beteiligte Session

query - das Query-Objekt, auf dem dieser Löschvorgang aufgerufen wurde.

values Das „values“-Dictionary, das an Query.update() übergeben wurde.

result das CursorResult, das als Ergebnis des Bulk-UPDATE-Vorgangs zurückgegeben wird.

Geändert in Version 1.4: Der update_context hat kein QueryContext-Objekt mehr, das ihm zugeordnet ist.

Siehe auch

QueryEvents.before_compile_update()

SessionEvents.after_bulk_delete()

method sqlalchemy.orm.SessionEvents.after_commit(session: Session) → None¶

Wird ausgeführt, nachdem ein Commit erfolgt ist.

Beispielhafte Argumentformen

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'after_commit')
def receive_after_commit(session):
    "listen for the 'after_commit' event"

    # ... (event handling logic) ...

Hinweis

Der Hook SessionEvents.after_commit() ist *nicht* pro Flush, d.h. die Session kann innerhalb des Gültigkeitsbereichs einer Transaktion viele Male SQL an die Datenbank emittieren. Für die Abfangung dieser Ereignisse verwenden Sie die Ereignisse SessionEvents.before_flush(), SessionEvents.after_flush() oder SessionEvents.after_flush_postexec().

Hinweis

Die Session befindet sich nicht in einer aktiven Transaktion, wenn das Ereignis SessionEvents.after_commit() aufgerufen wird, und kann daher kein SQL emittieren. Um SQL für jede Transaktion zu emittieren, verwenden Sie das Ereignis SessionEvents.before_commit().

Parameter:: session¶ – Die Ziel-Session.

Siehe auch

SessionEvents.before_commit()

SessionEvents.after_begin()

SessionEvents.before_flush()

method sqlalchemy.orm.SessionEvents.after_flush(session: Session, flush_context: UOWTransaction) → None¶

Wird ausgeführt, nachdem der Flush abgeschlossen ist, aber bevor der Commit aufgerufen wurde.

Beispielhafte Argumentformen

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'after_flush')
def receive_after_flush(session, flush_context):
    "listen for the 'after_flush' event"

    # ... (event handling logic) ...

Beachten Sie, dass sich der Zustand der Session noch im Vor-Flush-Zustand befindet, d.h. die Listen „new“, „dirty“ und „deleted“ zeigen immer noch den Vor-Flush-Zustand sowie die Verlaufs-Einstellungen für Instanzattribute an.

Warnung

Dieses Ereignis wird ausgeführt, nachdem die Session SQL zur Änderung der Datenbank emittiert hat, aber bevor sie ihren internen Zustand geändert hat, um diese Änderungen widerzuspiegeln, einschließlich der Tatsache, dass neu eingefügte Objekte in die Identitätszuordnung aufgenommen werden. ORM-Operationen, die innerhalb dieses Ereignisses emittiert werden, wie z.B. das Laden von zugehörigen Elementen, können neue Identitätszuordnungseinträge erstellen, die sofort ersetzt werden, was manchmal zu verwirrenden Ergebnissen führt. SQLAlchemy gibt ab Version 1.3.9 eine Warnung für diesen Zustand aus.

Parameter:

session¶ – Die Ziel-Session.
flush_context¶ – Internes UOWTransaction-Objekt, das die Details des Flushes handhabt.

Siehe auch

SessionEvents.after_flush_postexec()

SessionEvents.before_flush()

method sqlalchemy.orm.SessionEvents.after_flush_postexec(session: Session, flush_context: UOWTransaction) → None¶

Wird ausgeführt, nachdem der Flush abgeschlossen ist und nach dem Post-Exec-Zustand.

Beispielhafte Argumentformen

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'after_flush_postexec')
def receive_after_flush_postexec(session, flush_context):
    "listen for the 'after_flush_postexec' event"

    # ... (event handling logic) ...

Dies ist der Zeitpunkt, an dem die Listen „new“, „dirty“ und „deleted“ ihren endgültigen Zustand erreicht haben. Ein tatsächlicher commit() kann stattgefunden haben oder auch nicht, abhängig davon, ob der Flush seine eigene Transaktion gestartet hat oder an einer größeren Transaktion beteiligt war.

Parameter:

session¶ – Die Ziel-Session.
flush_context¶ – Internes UOWTransaction-Objekt, das die Details des Flushes handhabt.

Siehe auch

SessionEvents.after_flush()

method sqlalchemy.orm.SessionEvents.after_rollback(session: Session) → None¶

Wird ausgeführt, nachdem ein echtes DBAPI-Rollback stattgefunden hat.

Beispielhafte Argumentformen

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'after_rollback')
def receive_after_rollback(session):
    "listen for the 'after_rollback' event"

    # ... (event handling logic) ...

Beachten Sie, dass dieses Ereignis nur ausgelöst wird, wenn das *tatsächliche* Rollback gegen die Datenbank erfolgt – es wird *nicht* jedes Mal ausgelöst, wenn die Methode Session.rollback() aufgerufen wird, falls die zugrunde liegende DBAPI-Transaktion bereits zurückgerollt wurde. In vielen Fällen befindet sich die Session während dieses Ereignisses nicht in einem „aktiven“ Zustand, da die aktuelle Transaktion ungültig ist. Um eine Session zu erhalten, die nach dem Abschluss des äußersten Rollbacks aktiv ist, verwenden Sie das Ereignis SessionEvents.after_soft_rollback() und überprüfen Sie das Flag Session.is_active.

Parameter:: session¶ – Die Ziel-Session.

Methode sqlalchemy.orm.SessionEvents.after_soft_rollback(session: Session, previous_transaction: SessionTransaction) → None¶

Wird nach jedem Rollback ausgeführt, einschließlich „weicher“ Rollbacks, die auf DBAPI-Ebene keine tatsächliche Aktion auslösen.

Beispielhafte Argumentformen

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'after_soft_rollback')
def receive_after_soft_rollback(session, previous_transaction):
    "listen for the 'after_soft_rollback' event"

    # ... (event handling logic) ...

Dies betrifft sowohl verschachtelte als auch äußere Rollbacks, d. h. den innersten Rollback, der die rollback()-Methode des DBAPI aufruft, sowie die umschließenden Rollback-Aufrufe, die sich nur selbst aus dem Transaktionsstapel entfernen.

Die angegebene Session kann verwendet werden, um SQL und Session.query()-Operationen nach einem äußersten Rollback aufzurufen, indem zuerst das Session.is_active-Flag geprüft wird.

@event.listens_for(Session, "after_soft_rollback")
def do_something(session, previous_transaction):
    if session.is_active:
        session.execute(text("select * from some_table"))

Parameter:

session¶ – Die Ziel-Session.
previous_transaction¶ – Das gerade geschlossene Transaktionsmarkierungsobjekt SessionTransaction. Die aktuelle SessionTransaction für die angegebene Session ist über das Attribut Session.transaction verfügbar.

Methode sqlalchemy.orm.SessionEvents.after_transaction_create(session: Session, transaction: SessionTransaction) → None¶

Wird ausgeführt, wenn eine neue SessionTransaction erstellt wird.

Beispielhafte Argumentformen

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'after_transaction_create')
def receive_after_transaction_create(session, transaction):
    "listen for the 'after_transaction_create' event"

    # ... (event handling logic) ...

Dieses Ereignis unterscheidet sich von SessionEvents.after_begin() dadurch, dass es für jede SessionTransaction insgesamt auftritt, im Gegensatz zum Beginn von Transaktionen auf einzelnen Datenbankverbindungen. Es wird auch für verschachtelte Transaktionen und Subtransaktionen aufgerufen und immer von einem entsprechenden SessionEvents.after_transaction_end()-Ereignis begleitet (vorausgesetzt, die normale Funktionsweise der Session).

Parameter:

session¶ – die Ziel-Session.

transaction¶ –

die Ziel-SessionTransaction.

Um zu erkennen, ob es sich um die äußerste SessionTransaction handelt, im Gegensatz zu einer „Subtransaktion“ oder einem SAVEPOINT, prüfen Sie, ob das Attribut SessionTransaction.parent None ist.

@event.listens_for(session, "after_transaction_create")
def after_transaction_create(session, transaction):
    if transaction.parent is None:
        ...  # work with top-level transaction

Um zu erkennen, ob die SessionTransaction ein SAVEPOINT ist, verwenden Sie das Attribut SessionTransaction.nested.

@event.listens_for(session, "after_transaction_create")
def after_transaction_create(session, transaction):
    if transaction.nested:
        ...  # work with SAVEPOINT transaction

Siehe auch

SessionTransaction

Methode sqlalchemy.orm.SessionEvents.after_transaction_end(session: Session, transaction: SessionTransaction) → None¶

Wird ausgeführt, wenn der Gültigkeitsbereich einer SessionTransaction endet.

Beispielhafte Argumentformen

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'after_transaction_end')
def receive_after_transaction_end(session, transaction):
    "listen for the 'after_transaction_end' event"

    # ... (event handling logic) ...

Dieses Ereignis unterscheidet sich von SessionEvents.after_commit() dadurch, dass es allen verwendeten SessionTransaction-Objekten entspricht, einschließlich derjenigen für verschachtelte Transaktionen und Subtransaktionen. Es wird immer von einem entsprechenden SessionEvents.after_transaction_create()-Ereignis begleitet.

Parameter:

session¶ – die Ziel-Session.

transaction¶ –

die Ziel-SessionTransaction.

Um zu erkennen, ob es sich um die äußerste SessionTransaction handelt, im Gegensatz zu einer „Subtransaktion“ oder einem SAVEPOINT, prüfen Sie, ob das Attribut SessionTransaction.parent None ist.

@event.listens_for(session, "after_transaction_create")
def after_transaction_end(session, transaction):
    if transaction.parent is None:
        ...  # work with top-level transaction

Um zu erkennen, ob die SessionTransaction ein SAVEPOINT ist, verwenden Sie das Attribut SessionTransaction.nested.

@event.listens_for(session, "after_transaction_create")
def after_transaction_end(session, transaction):
    if transaction.nested:
        ...  # work with SAVEPOINT transaction

Siehe auch

SessionTransaction

SessionEvents.after_attach()

Methode sqlalchemy.orm.SessionEvents.before_attach(session: Session, instance: _O) → None¶

Wird ausgeführt, bevor eine Instanz an eine Session angehängt wird.

Beispielhafte Argumentformen

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'before_attach')
def receive_before_attach(session, instance):
    "listen for the 'before_attach' event"

    # ... (event handling logic) ...

Dies wird aufgerufen, bevor ein add, delete oder merge das Objekt zu einem Teil der Session macht.

Siehe auch

SessionEvents.after_commit()

Methode sqlalchemy.orm.SessionEvents.before_commit(session: Session) → None¶

Wird ausgeführt, bevor commit aufgerufen wird.

Beispielhafte Argumentformen

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'before_commit')
def receive_before_commit(session):
    "listen for the 'before_commit' event"

    # ... (event handling logic) ...

Hinweis

Der Hook SessionEvents.before_commit() ist nicht pro Flush; das heißt, die Session kann innerhalb des Gültigkeitsbereichs einer Transaktion viele Male SQL an die Datenbank senden. Für die Abfangen dieser Ereignisse verwenden Sie die Ereignisse SessionEvents.before_flush(), SessionEvents.after_flush() oder SessionEvents.after_flush_postexec().

Parameter:: session¶ – Die Ziel-Session.

Siehe auch

SessionEvents.after_begin()

SessionEvents.after_flush()

Methode sqlalchemy.orm.SessionEvents.before_flush(session: Session, flush_context: UOWTransaction, instances: Sequence[_O] | None) → None¶

Wird ausgeführt, bevor der Flush-Prozess begonnen hat.

Beispielhafte Argumentformen

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'before_flush')
def receive_before_flush(session, flush_context, instances):
    "listen for the 'before_flush' event"

    # ... (event handling logic) ...

Parameter:

session¶ – Die Ziel-Session.
flush_context¶ – Internes UOWTransaction-Objekt, das die Details des Flush-Vorgangs verwaltet.
instances¶ – Normalerweise None, dies ist die Sammlung von Objekten, die an die Methode Session.flush() übergeben werden können (beachten Sie, dass diese Verwendung veraltet ist).

Siehe auch

SessionEvents.after_flush_postexec()

Methode sqlalchemy.orm.SessionEvents.deleted_to_detached(session: Session, instance: _O) → None¶

Abfangen des Übergangs von „gelöscht zu getrennt“ für ein bestimmtes Objekt.

Beispielhafte Argumentformen

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'deleted_to_detached')
def receive_deleted_to_detached(session, instance):
    "listen for the 'deleted_to_detached' event"

    # ... (event handling logic) ...

Dieses Ereignis wird aufgerufen, wenn ein gelöschtes Objekt aus der Session entfernt wird. Der typische Fall dafür ist, wenn die Transaktion einer Session, in der das Objekt gelöscht wurde, committet wird; das Objekt wechselt vom Status „gelöscht“ zum Status „getrennt“.

Es wird auch für Objekte aufgerufen, die in einem Flush gelöscht wurden, wenn die Ereignisse Session.expunge_all() oder Session.close() aufgerufen werden, sowie wenn das Objekt individuell aus seinem gelöschten Zustand mittels Session.expunge() entfernt wird.

Siehe auch

Methode sqlalchemy.orm.SessionEvents.deleted_to_persistent(session: Session, instance: _O) → None¶

Abfangen des Übergangs von „gelöscht zu persistent“ für ein bestimmtes Objekt.

Beispielhafte Argumentformen

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'deleted_to_persistent')
def receive_deleted_to_persistent(session, instance):
    "listen for the 'deleted_to_persistent' event"

    # ... (event handling logic) ...

Dieser Übergang tritt nur auf, wenn ein Objekt, das in einem Flush erfolgreich gelöscht wurde, aufgrund eines Aufrufs von Session.rollback() wiederhergestellt wird. Das Ereignis wird unter keinen anderen Umständen aufgerufen.

Siehe auch

Methode sqlalchemy.orm.SessionEvents.detached_to_persistent(session: Session, instance: _O) → None¶

Abfangen des Übergangs von „getrennt zu persistent“ für ein bestimmtes Objekt.

Beispielhafte Argumentformen

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'detached_to_persistent')
def receive_detached_to_persistent(session, instance):
    "listen for the 'detached_to_persistent' event"

    # ... (event handling logic) ...

Dieses Ereignis ist eine Spezialisierung des Ereignisses SessionEvents.after_attach(), das nur für diesen spezifischen Übergang aufgerufen wird. Es wird typischerweise während des Aufrufs von Session.add() aufgerufen, sowie während des Aufrufs von Session.delete(), wenn das Objekt nicht zuvor mit der Session verbunden war (beachten Sie, dass ein als „gelöscht“ markiertes Objekt bis zum Fortfahren des Flush im Status „persistent“ bleibt).

Hinweis

Wenn das Objekt als Teil eines Aufrufs von Session.delete() persistent wird, ist das Objekt zum Zeitpunkt des Aufrufs dieses Ereignisses noch nicht als gelöscht markiert. Um gelöschte Objekte zu erkennen, prüfen Sie das Flag deleted, das an das Ereignis SessionEvents.persistent_to_detached() gesendet wird, nachdem der Flush fortgefahren ist, oder prüfen Sie die Sammlung Session.deleted innerhalb des Ereignisses SessionEvents.before_flush(), wenn gelöschte Objekte vor dem Flush abgefangen werden müssen.

Parameter:

session¶ – Ziel-Session
instance¶ – die ORM-geprägte Instanz, auf die die Operation angewendet wird.

Siehe auch

Attribut sqlalchemy.orm.SessionEvents.dispatch: _Dispatch[_ET] = <sqlalchemy.event.base.SessionEventsDispatch object>¶

Referenz zurück zur _Dispatch-Klasse.

Bidirektional zu _Dispatch._events

Methode sqlalchemy.orm.SessionEvents.do_orm_execute(orm_execute_state: ORMExecuteState) → None¶

Abfangen von Anweisungs-Ausführungen, die im Auftrag eines ORM Session-Objekts erfolgen.

Beispielhafte Argumentformen

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'do_orm_execute')
def receive_do_orm_execute(orm_execute_state):
    "listen for the 'do_orm_execute' event"

    # ... (event handling logic) ...

Dieses Ereignis wird für alle Top-Level-SQL-Anweisungen aufgerufen, die über die Methode Session.execute() aufgerufen werden, sowie für verwandte Methoden wie Session.scalars() und Session.scalar(). Ab SQLAlchemy 1.4 nehmen alle ORM-Abfragen, die über die Methode Session.execute() sowie verwandte Methoden Session.scalars(), Session.scalar() usw. teil. Dieser Hook gilt nicht für Abfragen, die intern während des ORM-Flush-Prozesses ausgeführt werden, d. h. für den Prozess, der unter Flushing beschrieben wird.

Hinweis

Der Ereignishook SessionEvents.do_orm_execute() wird nur für ORM-Anweisungsausführungen ausgelöst, d. h. für diejenigen, die über die Methode Session.execute() und ähnliche Methoden des Session-Objekts aufgerufen werden. Er wird nicht für Anweisungen ausgelöst, die ausschließlich von SQLAlchemy Core aufgerufen werden, d. h. für Anweisungen, die direkt mit Connection.execute() aufgerufen werden oder anderweitig von einem Engine-Objekt stammen, ohne dass eine Session beteiligt ist. Um alle SQL-Ausführungen abzufangen, unabhängig davon, ob die Core- oder ORM-APIs verwendet werden, siehe die Ereignishooks in ConnectionEvents, wie z. B. ConnectionEvents.before_execute() und ConnectionEvents.before_cursor_execute().

Außerdem gilt dieser Hook nicht für Abfragen, die intern während des ORM-Flush-Prozesses ausgeführt werden, d. h. für den Prozess, der unter Flushing beschrieben wird; um Schritte innerhalb des Flush-Prozesses abzufangen, siehe die Ereignishooks, die unter Persistence Events sowie Mapper-level Flush Events beschrieben sind.

Dieses Ereignis ist ein do_-Ereignis, was bedeutet, dass es die Möglichkeit hat, die Operation zu ersetzen, die die Methode Session.execute() normalerweise ausführt. Der beabsichtigte Verwendungszweck umfasst Sharding- und Result-Caching-Schemata, die möglicherweise dieselbe Anweisung über mehrere Datenbankverbindungen ausführen, ein Ergebnis zurückgeben, das von jeder einzelnen zusammengeführt wird, oder die Anweisung gar nicht ausführen und stattdessen Daten aus einem Cache zurückgeben.

Der Hook soll die Verwendung der Methode Query._execute_and_instances ersetzen, die vor SQLAlchemy 1.4 unterklassifiziert werden konnte.

Parameter:: orm_execute_state¶ – eine Instanz von ORMExecuteState, die alle Informationen über die aktuelle Ausführung enthält, sowie Hilfsfunktionen, die zur Ableitung anderer häufig benötigter Informationen verwendet werden. Siehe dieses Objekt für Details.

Siehe auch

Execute Events - Top-Level-Dokumentation zur Verwendung von SessionEvents.do_orm_execute()

ORMExecuteState - Das Objekt, das an das Ereignis SessionEvents.do_orm_execute() übergeben wird, das alle Informationen über die auszuführende Anweisung enthält. Es stellt auch eine Schnittstelle zur Erweiterung der aktuellen Anweisung, Optionen und Parameter sowie eine Option zur programmatischen Ausführung der Anweisung zu jedem Zeitpunkt bereit.

ORM Query Events - Enthält Beispiele für die Verwendung von SessionEvents.do_orm_execute()

Dogpile Caching - Ein Beispiel für die Integration von Dogpile-Caching mit dem ORM Session unter Verwendung des Ereignishooks SessionEvents.do_orm_execute().

Horizontal Sharding - Das Beispiel / die Erweiterung für horizontales Sharding basiert auf dem Ereignishook SessionEvents.do_orm_execute(), um eine SQL-Anweisung auf mehreren Backends auszuführen und ein zusammengeführtes Ergebnis zurückzugeben.

Neu in Version 1.4.

method sqlalchemy.orm.SessionEvents.loaded_as_persistent(session: Session, instance: _O) → None¶

Fängt den Übergang „geladen als persistent“ für ein bestimmtes Objekt ab.

Beispielhafte Argumentformen

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'loaded_as_persistent')
def receive_loaded_as_persistent(session, instance):
    "listen for the 'loaded_as_persistent' event"

    # ... (event handling logic) ...

Dieses Ereignis wird während des ORM-Ladevorgangs aufgerufen und ähnelt stark dem Ereignis InstanceEvents.load(). Das Ereignis ist jedoch mit einer Session-Klasse oder -Instanz verknüpfbar, anstatt mit einer Mapper- oder Klassenhierarchie, und integriert sich nahtlos in die anderen Sitzungslebenszyklusereignisse. Das Objekt ist garantiert in der Identitätszuordnung der Sitzung vorhanden, wenn dieses Ereignis aufgerufen wird.

Hinweis

Dieses Ereignis wird während des Ladevorgangs aufgerufen, bevor Eager-Loader möglicherweise abgeschlossen sind, und der Zustand des Objekts ist möglicherweise noch nicht vollständig. Darüber hinaus führen Aufrufe von Zeilenaktualisierungsoperationen für das Objekt zu einem neuen Ladekontext, was den bestehenden Ladekontext stört. Siehe die Notiz zu InstanceEvents.load() für Hintergrundinformationen zur Verwendung des Parameters SessionEvents.restore_load_context, der auf die gleiche Weise wie bei InstanceEvents.restore_load_context funktioniert, um dieses Szenario zu lösen.

Parameter:

session¶ – Ziel-Session
instance¶ – die ORM-gemappte Instanz, die gerade bearbeitet wird.

Siehe auch

method sqlalchemy.orm.SessionEvents.pending_to_persistent(session: Session, instance: _O) → None¶

Fängt den Übergang „pending zu persistent“ für ein bestimmtes Objekt ab.

Beispielhafte Argumentformen

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'pending_to_persistent')
def receive_pending_to_persistent(session, instance):
    "listen for the 'pending_to_persistent' event"

    # ... (event handling logic) ...

Dieses Ereignis wird während des Flush-Prozesses aufgerufen und ähnelt dem Durchsuchen der Sammlung Session.new im Ereignis SessionEvents.after_flush(). In diesem Fall wurde das Objekt jedoch bereits in den persistenten Zustand verschoben, wenn das Ereignis aufgerufen wird.

Parameter:

session¶ – Ziel-Session
instance¶ – die ORM-gemappte Instanz, die gerade bearbeitet wird.

Siehe auch

method sqlalchemy.orm.SessionEvents.pending_to_transient(session: Session, instance: _O) → None¶

Fängt den Übergang „pending zu transient“ für ein bestimmtes Objekt ab.

Beispielhafte Argumentformen

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'pending_to_transient')
def receive_pending_to_transient(session, instance):
    "listen for the 'pending_to_transient' event"

    # ... (event handling logic) ...

Dieser weniger häufige Übergang tritt auf, wenn ein ausstehendes Objekt, das noch nicht geflusht wurde, aus der Sitzung entfernt wird; dies kann passieren, wenn die Methode Session.rollback() die Transaktion zurückrollt oder wenn die Methode Session.expunge() verwendet wird.

Parameter:

session¶ – Ziel-Session
instance¶ – die ORM-gemappte Instanz, die gerade bearbeitet wird.

Siehe auch

method sqlalchemy.orm.SessionEvents.persistent_to_deleted(session: Session, instance: _O) → None¶

Fängt den Übergang „persistent zu gelöscht“ für ein bestimmtes Objekt ab.

Beispielhafte Argumentformen

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'persistent_to_deleted')
def receive_persistent_to_deleted(session, instance):
    "listen for the 'persistent_to_deleted' event"

    # ... (event handling logic) ...

Dieses Ereignis wird aufgerufen, wenn die Identität eines persistenten Objekts während eines Flushs aus der Datenbank gelöscht wird. Das Objekt bleibt jedoch bis zum Abschluss der Transaktion mit der Session assoziiert.

Wenn die Transaktion zurückgerollt wird, wechselt das Objekt erneut in den persistenten Zustand, und das Ereignis SessionEvents.deleted_to_persistent() wird aufgerufen. Wenn die Transaktion committet wird, wird das Objekt getrennt, was das Ereignis SessionEvents.deleted_to_detached() auslöst.

Beachten Sie, dass die Methode Session.delete() zwar die primäre öffentliche Schnittstelle ist, um ein Objekt als gelöscht zu markieren, viele Objekte jedoch aufgrund von Kaskadierungsregeln gelöscht werden, die erst zur Flush-Zeit bestimmt werden. Daher gibt es keine Möglichkeit, jedes gelöschte Objekt zu erfassen, bis der Flush fortgeschritten ist. Das Ereignis SessionEvents.persistent_to_deleted() wird daher am Ende eines Flush aufgerufen.

Siehe auch

method sqlalchemy.orm.SessionEvents.persistent_to_detached(session: Session, instance: _O) → None¶

Fängt den Übergang „persistent zu detached“ für ein bestimmtes Objekt ab.

Beispielhafte Argumentformen

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'persistent_to_detached')
def receive_persistent_to_detached(session, instance):
    "listen for the 'persistent_to_detached' event"

    # ... (event handling logic) ...

Dieses Ereignis wird aufgerufen, wenn ein persistentes Objekt aus der Sitzung entfernt wird. Es gibt viele Bedingungen, die dazu führen, darunter:

Verwendung einer Methode wie Session.expunge() oder Session.close()
Aufruf der Methode Session.rollback(), wenn das Objekt Teil einer INSERT-Anweisung für die Transaktion dieser Sitzung war

Parameter:

session¶ – Ziel-Session
instance¶ – die ORM-gemappte Instanz, die gerade bearbeitet wird.
deleted¶ – boolesch. Wenn True, zeigt dies an, dass das Objekt in den detached-Zustand übergegangen ist, weil es als gelöscht markiert und geflusht wurde.

Siehe auch

method sqlalchemy.orm.SessionEvents.persistent_to_transient(session: Session, instance: _O) → None¶

Fängt den Übergang „persistent zu transient“ für ein bestimmtes Objekt ab.

Beispielhafte Argumentformen

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'persistent_to_transient')
def receive_persistent_to_transient(session, instance):
    "listen for the 'persistent_to_transient' event"

    # ... (event handling logic) ...

Dieser weniger häufige Übergang tritt auf, wenn ein ausstehendes Objekt, das geflusht wurde, aus der Sitzung entfernt wird. Dies kann passieren, wenn die Methode Session.rollback() die Transaktion zurückrollt.

Parameter:

session¶ – Ziel-Session
instance¶ – die ORM-gemappte Instanz, die gerade bearbeitet wird.

Siehe auch

method sqlalchemy.orm.SessionEvents.transient_to_pending(session: Session, instance: _O) → None¶

Fängt den Übergang „transient zu pending“ für ein bestimmtes Objekt ab.

Beispielhafte Argumentformen

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'transient_to_pending')
def receive_transient_to_pending(session, instance):
    "listen for the 'transient_to_pending' event"

    # ... (event handling logic) ...

Dieses Ereignis ist eine Spezialisierung des Ereignisses SessionEvents.after_attach(), das nur für diesen spezifischen Übergang aufgerufen wird. Es wird typischerweise während des Aufrufs von Session.add() aufgerufen.

Parameter:

session¶ – Ziel-Session
instance¶ – die ORM-gemappte Instanz, die gerade bearbeitet wird.

Siehe auch

after_configured(), after_delete(), after_insert(), after_mapper_constructed(), after_update(), before_configured(), before_delete(), before_insert(), before_mapper_configured(), before_update(), dispatch, instrument_class(), mapper_configured()

Mapper Events¶

Mapper-Ereignishooks umfassen Dinge, die im Zusammenhang mit einzelnen oder mehreren Mapper-Objekten geschehen, die das zentrale Konfigurationsobjekt sind, das eine benutzerdefinierte Klasse einer Table-Objekt zuordnet. Zu den Arten von Dingen, die auf Mapper-Ebene auftreten, gehören:

Persistenzoperationen pro Objekt – die beliebtesten Mapper-Hooks sind die Unit-of-Work-Hooks wie MapperEvents.before_insert(), MapperEvents.after_update() usw. Diese Ereignisse stehen im Gegensatz zu den allgemeineren Sitzungsebene-Ereignissen wie SessionEvents.before_flush(), da sie während des Flush-Prozesses pro Objekt auftreten. Während feinere Aktivität an einem Objekt unkomplizierter ist, ist die Verfügbarkeit von Session-Funktionen begrenzt.
Mapper-Konfigurationsereignisse – die andere Hauptklasse von Mapper-Hooks sind diejenigen, die auftreten, wenn eine Klasse zugeordnet wird, ein Mapper finalisiert wird und wenn Sätze von Mappern so konfiguriert werden, dass sie aufeinander verweisen. Diese Ereignisse umfassen MapperEvents.instrument_class(), MapperEvents.before_mapper_configured() und MapperEvents.mapper_configured() auf der Ebene einzelner Mapper-Objekte und MapperEvents.before_configured() und MapperEvents.after_configured() auf der Ebene von Sammlungen von Mapper-Objekten.

Objektname	Beschreibung
MapperEvents	Definiert ereignisspezifische Zuordnungen.

class sqlalchemy.orm.MapperEvents¶

Definiert ereignisspezifische Zuordnungen.

z. B.

from sqlalchemy import event


def my_before_insert_listener(mapper, connection, target):
    # execute a stored procedure upon INSERT,
    # apply the value to the row to be inserted
    target.calculated_value = connection.execute(
        text("select my_special_function(%d)" % target.special_number)
    ).scalar()


# associate the listener function with SomeClass,
# to execute during the "before_insert" hook
event.listen(SomeClass, "before_insert", my_before_insert_listener)

Verfügbare Ziele umfassen

zugeordnete Klassen
nicht zugeordnete Oberklassen von zugeordneten oder noch zuzuordnenden Klassen (mit dem Flag propagate=True)
Mapper-Objekte
die Mapper-Klasse selbst gibt an, dass für alle Mapper zugehört wird.

Mapper-Ereignisse bieten Hooks in kritischen Abschnitten des Mappers, einschließlich solcher, die sich auf die Objektinstrumentierung, das Laden von Objekten und die Objektpersistenz beziehen. Insbesondere sind die Persistenzmethoden MapperEvents.before_insert() und MapperEvents.before_update() beliebte Orte, um den zu persistenten Zustand zu erweitern. Diese Methoden haben jedoch mehrere signifikante Einschränkungen. Der Benutzer wird ermutigt, die Methoden SessionEvents.before_flush() und SessionEvents.after_flush() als flexiblere und benutzerfreundlichere Hooks zu bewerten, um zusätzliche Datenbankzustände während eines Flushs anzuwenden.

Bei der Verwendung von MapperEvents sind mehrere Modifikatoren für die Funktion listen() verfügbar.

Parameter:

propagate=False¶ – Wenn True, sollte der Ereignis-Listener auf alle erbenden Mapper und/oder die Mapper von erbenden Klassen sowie auf jeden Mapper angewendet werden, der das Ziel dieses Listeners ist.
raw=False¶ – Wenn True, ist das an die entsprechenden Ereignis-Listener-Funktionen übergebene „target“-Argument das InstanceState-Verwaltungsobjekt der Instanz und nicht die zugeordnete Instanz selbst.
retval=False¶ –
wenn True, muss die benutzerdefinierte Ereignisfunktion einen Rückgabewert haben, dessen Zweck entweder die Steuerung der nachfolgenden Ereignisweitergabe ist oder die laufende Operation des Mappers anderweitig zu ändern. Mögliche Rückgabewerte sind:
- sqlalchemy.orm.interfaces.EXT_CONTINUE - Die Ereignisverarbeitung normal fortsetzen.
- sqlalchemy.orm.interfaces.EXT_STOP - Alle nachfolgenden Ereignis-Handler in der Kette abbrechen.
- andere Werte – der von spezifischen Listenern angegebene Rückgabewert.

Mitglieder

Klassensignatur

class sqlalchemy.orm.MapperEvents (sqlalchemy.event.Events)

method sqlalchemy.orm.MapperEvents.after_configured() → None¶

Aufgerufen nach der Konfiguration einer Reihe von Mappern.

Beispielhafte Argumentformen

from sqlalchemy import event


@event.listens_for(SomeClass, 'after_configured')
def receive_after_configured():
    "listen for the 'after_configured' event"

    # ... (event handling logic) ...

Das Ereignis MapperEvents.after_configured() wird jedes Mal aufgerufen, wenn die Funktion configure_mappers() aufgerufen wird, nachdem die Funktion ihre Arbeit abgeschlossen hat. configure_mappers() wird typischerweise automatisch aufgerufen, wenn Zuordnungen erstmals verwendet werden, sowie jedes Mal, wenn neue Mapper verfügbar gemacht wurden und eine neue Mapper-Nutzung erkannt wird.

Vergleichen Sie dieses Ereignis mit dem Ereignis MapperEvents.mapper_configured(), das pro Mapper aufgerufen wird, während der Konfigurationsvorgang fortschreitet; im Gegensatz zu diesem Ereignis sind, wenn dieses Ereignis aufgerufen wird, alle Querkonfigurationen (z. B. Backrefs) auch für alle wartenden Mapper verfügbar. Vergleichen Sie auch mit MapperEvents.before_configured(), das aufgerufen wird, bevor die Reihe von Mappern konfiguriert wurde.

Dieses Ereignis kann **nur** auf die Mapper-Klasse und nicht auf einzelne Zuordnungen oder zugeordnete Klassen angewendet werden. Es wird nur für alle Zuordnungen als Ganzes aufgerufen.

from sqlalchemy.orm import Mapper


@event.listens_for(Mapper, "after_configured")
def go(): ...

Theoretisch wird dieses Ereignis einmal pro Anwendung aufgerufen, aber tatsächlich wird es jedes Mal aufgerufen, wenn neue Mapper von einem Aufruf von configure_mappers() betroffen sind. Wenn neue Zuordnungen nach der Verwendung bestehender Zuordnungen erstellt werden, wird dieses Ereignis wahrscheinlich erneut aufgerufen. Um sicherzustellen, dass ein bestimmtes Ereignis nur einmal und nicht weiter aufgerufen wird, kann das Argument once=True (neu ab 0.9.4) angewendet werden.

from sqlalchemy.orm import mapper


@event.listens_for(mapper, "after_configured", once=True)
def go(): ...

Siehe auch

MapperEvents.before_mapper_configured()

MapperEvents.mapper_configured()

MapperEvents.before_configured()

method sqlalchemy.orm.MapperEvents.after_delete(mapper: Mapper[_O], connection: Connection, target: _O) → None¶

Erhält eine Objektinstanz, nachdem eine DELETE-Anweisung, die dieser Instanz entspricht, ausgegeben wurde.

Beispielhafte Argumentformen

from sqlalchemy import event


@event.listens_for(SomeClass, 'after_delete')
def receive_after_delete(mapper, connection, target):
    "listen for the 'after_delete' event"

    # ... (event handling logic) ...

Hinweis

Dieses Ereignis gilt **nur** für die Sitzungs-Flush-Operation und gilt **nicht** für die ORM DML-Operationen, die unter ORM-aktivierte INSERT-, UPDATE- und DELETE-Anweisungen beschrieben sind. Um ORM DML-Ereignisse abzufangen, verwenden Sie SessionEvents.do_orm_execute().

Dieses Ereignis wird verwendet, um zusätzliche SQL-Anweisungen auf der angegebenen Verbindung auszugeben sowie anwendungsspezifische Buchhaltung für ein Löschereignis durchzuführen.

Das Ereignis wird oft für eine Gruppe von Objekten derselben Klasse aufgerufen, nachdem deren DELETE-Anweisungen in einem früheren Schritt auf einmal ausgegeben wurden.

Warnung

Mapper-Flush-Ereignisse erlauben **nur sehr begrenzte Operationen** auf Attributen, die lokal zur gerade bearbeiteten Zeile sind, sowie das Ausgeben von SQL auf der gegebenen Connection. **Bitte lesen Sie vollständig** die Hinweise unter Mapper-Level Flush Events für Richtlinien zur Verwendung dieser Methoden; im Allgemeinen sollte die Methode SessionEvents.before_flush() für allgemeine Änderungen während des Flush bevorzugt werden.

Parameter:

mapper¶ – der Mapper, der das Ziel dieses Ereignisses ist.
connection¶ – die Connection, die zum Ausgeben von DELETE-Anweisungen für diese Instanz verwendet wird. Dies bietet einen Zugriff auf die aktuelle Transaktion auf der Zieldatenbank, die spezifisch für diese Instanz ist.
target¶ – die zugeordnete Instanz, die gelöscht wird. Wenn das Ereignis mit raw=True konfiguriert wurde, ist dies stattdessen das InstanceState-Zustandsverwaltungsobjekt, das mit der Instanz assoziiert ist.

Gibt zurück:

Kein Rückgabewert wird von diesem Ereignis unterstützt.

Siehe auch

methode sqlalchemy.orm.MapperEvents.after_insert(mapper: Mapper[_O], connection: Connection, target: _O) → None¶

Empfängt eine Objektinstanz, nachdem eine INSERT-Anweisung für diese Instanz ausgegeben wurde.

Beispielhafte Argumentformen

from sqlalchemy import event


@event.listens_for(SomeClass, 'after_insert')
def receive_after_insert(mapper, connection, target):
    "listen for the 'after_insert' event"

    # ... (event handling logic) ...

Hinweis

Dieses Ereignis gilt **nur** für die Sitzungs-Flush-Operation und gilt **nicht** für die ORM DML-Operationen, die unter ORM-aktivierte INSERT-, UPDATE- und DELETE-Anweisungen beschrieben sind. Um ORM DML-Ereignisse abzufangen, verwenden Sie SessionEvents.do_orm_execute().

Dieses Ereignis wird verwendet, um den reinen Python-Zustand der Instanz nach einem INSERT zu ändern und zusätzliche SQL-Anweisungen über die gegebene Verbindung auszugeben.

Das Ereignis wird oft für eine Gruppe von Objekten derselben Klasse aufgerufen, nachdem deren INSERT-Anweisungen in einem vorherigen Schritt auf einmal ausgegeben wurden. In dem extrem seltenen Fall, dass dies nicht erwünscht ist, kann das Mapper-Objekt mit batch=False konfiguriert werden, wodurch Instanzgruppen in einzelne (und schlechter performende) Ereignis->persist->Ereignisschritte aufgeteilt werden.

Warnung

Mapper-Flush-Ereignisse erlauben **nur sehr begrenzte Operationen** auf Attributen, die lokal zur gerade bearbeiteten Zeile sind, sowie das Ausgeben von SQL auf der gegebenen Connection. **Bitte lesen Sie vollständig** die Hinweise unter Mapper-Level Flush Events für Richtlinien zur Verwendung dieser Methoden; im Allgemeinen sollte die Methode SessionEvents.before_flush() für allgemeine Änderungen während des Flush bevorzugt werden.

Parameter:

mapper¶ – Der Mapper, der das Ziel dieses Ereignisses ist.
connection¶ – Die Connection, die zum Ausgeben von INSERT-Anweisungen für diese Instanz verwendet wird. Dies bietet einen Zugriff auf die aktuelle Transaktion in der Zieldatenbank, die spezifisch für diese Instanz ist.
target¶ – Die zu persistierende gemappte Instanz. Wenn das Ereignis mit raw=True konfiguriert ist, ist dies stattdessen das InstanceState-Objekt zur Zustandsverwaltung, das mit der Instanz verbunden ist.

Gibt zurück:

Kein Rückgabewert wird von diesem Ereignis unterstützt.

Siehe auch

methode sqlalchemy.orm.MapperEvents.after_mapper_constructed(mapper: Mapper[_O], class_: Type[_O]) → None¶

Empfängt eine Klasse und einen Mapper, wenn der Mapper vollständig konstruiert wurde.

Beispielhafte Argumentformen

from sqlalchemy import event


@event.listens_for(SomeClass, 'after_mapper_constructed')
def receive_after_mapper_constructed(mapper, class_):
    "listen for the 'after_mapper_constructed' event"

    # ... (event handling logic) ...

Dieses Ereignis wird nach Abschluss des anfänglichen Konstruktors für Mapper aufgerufen. Dies geschieht nach dem MapperEvents.instrument_class()-Ereignis und nachdem der Mapper einen ersten Durchlauf seiner Argumente durchgeführt hat, um seine Sammlung von MapperProperty-Objekten zu generieren, die über die Methode Mapper.get_property() und das Attribut Mapper.iterate_properties zugänglich sind.

Dieses Ereignis unterscheidet sich vom MapperEvents.before_mapper_configured()-Ereignis dadurch, dass es innerhalb des Konstruktors für Mapper aufgerufen wird, anstatt innerhalb des registry.configure()-Prozesses. Derzeit ist dieses Ereignis das einzige, das für Handler geeignet ist, die als Reaktion auf die Konstruktion dieses Mapper zusätzliche gemappte Klassen erstellen möchten, die Teil desselben Konfigurationsschritts sein werden, wenn registry.configure() erneut ausgeführt wird.

Neu in Version 2.0.2.

Siehe auch

Versioning von Objekten - Ein Beispiel, das die Verwendung des MapperEvents.before_mapper_configured()-Ereignisses veranschaulicht, um neue Mapper zu erstellen, die Änderungsprotokolle für Objekte aufzeichnen.

methode sqlalchemy.orm.MapperEvents.after_update(mapper: Mapper[_O], connection: Connection, target: _O) → None¶

Empfängt eine Objektinstanz, nachdem eine UPDATE-Anweisung für diese Instanz ausgegeben wurde.

Beispielhafte Argumentformen

from sqlalchemy import event


@event.listens_for(SomeClass, 'after_update')
def receive_after_update(mapper, connection, target):
    "listen for the 'after_update' event"

    # ... (event handling logic) ...

Hinweis

Dieses Ereignis gilt **nur** für die Sitzungs-Flush-Operation und gilt **nicht** für die ORM DML-Operationen, die unter ORM-aktivierte INSERT-, UPDATE- und DELETE-Anweisungen beschrieben sind. Um ORM DML-Ereignisse abzufangen, verwenden Sie SessionEvents.do_orm_execute().

Dieses Ereignis wird verwendet, um den reinen Python-Zustand der Instanz nach einem UPDATE zu ändern und zusätzliche SQL-Anweisungen über die gegebene Verbindung auszugeben.

Diese Methode wird für alle Instanzen aufgerufen, die als "dirty" markiert sind, *auch solche, die keine Nettoänderungen an ihren spaltenbasierten Attributen aufweisen*, und für die keine UPDATE-Anweisung durchgeführt wurde. Ein Objekt wird als "dirty" markiert, wenn eine "set attribute"-Operation für eines seiner spaltenbasierten Attribute aufgerufen wird oder wenn eine seiner Sammlungen geändert wird. Wenn zum Zeitpunkt des Updates keine spaltenbasierten Attribute Nettoänderungen aufweisen, wird keine UPDATE-Anweisung ausgegeben. Das bedeutet, dass eine Instanz, die an MapperEvents.after_update() übergeben wird, *keine* Garantie dafür ist, dass eine UPDATE-Anweisung ausgegeben wurde.

Um zu erkennen, ob die spaltenbasierten Attribute des Objekts Nettoänderungen aufweisen und somit eine UPDATE-Anweisung generiert haben, verwenden Sie object_session(instance).is_modified(instance, include_collections=False).

Das Ereignis wird oft für eine Gruppe von Objekten derselben Klasse aufgerufen, nachdem deren UPDATE-Anweisungen in einem vorherigen Schritt auf einmal ausgegeben wurden. In dem extrem seltenen Fall, dass dies nicht erwünscht ist, kann der Mapper mit batch=False konfiguriert werden, wodurch Instanzgruppen in einzelne (und schlechter performende) Ereignis->persist->Ereignisschritte aufgeteilt werden.

Warnung

Mapper-Flush-Ereignisse erlauben **nur sehr begrenzte Operationen** auf Attributen, die lokal zur gerade bearbeiteten Zeile sind, sowie das Ausgeben von SQL auf der gegebenen Connection. **Bitte lesen Sie vollständig** die Hinweise unter Mapper-Level Flush Events für Richtlinien zur Verwendung dieser Methoden; im Allgemeinen sollte die Methode SessionEvents.before_flush() für allgemeine Änderungen während des Flush bevorzugt werden.

Parameter:

mapper¶ – Der Mapper, der das Ziel dieses Ereignisses ist.
connection¶ – Die Connection, die zum Ausgeben von UPDATE-Anweisungen für diese Instanz verwendet wird. Dies bietet einen Zugriff auf die aktuelle Transaktion in der Zieldatenbank, die spezifisch für diese Instanz ist.
target¶ – Die zu persistierende gemappte Instanz. Wenn das Ereignis mit raw=True konfiguriert ist, ist dies stattdessen das InstanceState-Objekt zur Zustandsverwaltung, das mit der Instanz verbunden ist.

Gibt zurück:

Kein Rückgabewert wird von diesem Ereignis unterstützt.

Siehe auch

MapperEvents.before_mapper_configured()

methode sqlalchemy.orm.MapperEvents.before_configured() → None¶

Wird aufgerufen, bevor eine Reihe von Mappern konfiguriert wird.

Beispielhafte Argumentformen

from sqlalchemy import event


@event.listens_for(SomeClass, 'before_configured')
def receive_before_configured():
    "listen for the 'before_configured' event"

    # ... (event handling logic) ...

Das MapperEvents.before_configured()-Ereignis wird jedes Mal aufgerufen, wenn die Funktion configure_mappers() aufgerufen wird, bevor die Funktion ihre Arbeit aufgenommen hat. configure_mappers() wird typischerweise automatisch aufgerufen, wenn Mappings zum ersten Mal verwendet werden, sowie jedes Mal, wenn neue Mapper verfügbar gemacht wurden und neue Mapper-Verwendung erkannt wird.

Dieses Ereignis kann **nur** auf die Mapper-Klasse und nicht auf einzelne Zuordnungen oder zugeordnete Klassen angewendet werden. Es wird nur für alle Zuordnungen als Ganzes aufgerufen.

from sqlalchemy.orm import Mapper


@event.listens_for(Mapper, "before_configured")
def go(): ...

Vergleichen Sie dieses Ereignis mit MapperEvents.after_configured(), das nach der Konfiguration der Mapper-Reihe aufgerufen wird, sowie mit MapperEvents.before_mapper_configured() und MapperEvents.mapper_configured(), die beide auf Mapper-Basis aufgerufen werden.

Theoretisch wird dieses Ereignis einmal pro Anwendung aufgerufen, aber tatsächlich wird es jedes Mal aufgerufen, wenn neue Mapper von einem configure_mappers()-Aufruf betroffen sein sollen. Wenn neue Mappings nach bereits verwendeten konstruiert werden, wird dieses Ereignis wahrscheinlich erneut aufgerufen. Um sicherzustellen, dass ein bestimmtes Ereignis nur einmal und nicht weiter aufgerufen wird, kann das Argument once=True (neu ab 0.9.4) verwendet werden.

from sqlalchemy.orm import mapper


@event.listens_for(mapper, "before_configured", once=True)
def go(): ...

Siehe auch

MapperEvents.mapper_configured()

MapperEvents.after_configured()

methode sqlalchemy.orm.MapperEvents.before_delete(mapper: Mapper[_O], connection: Connection, target: _O) → None¶

Empfängt eine Objektinstanz, bevor eine DELETE-Anweisung für diese Instanz ausgegeben wird.

Beispielhafte Argumentformen

from sqlalchemy import event


@event.listens_for(SomeClass, 'before_delete')
def receive_before_delete(mapper, connection, target):
    "listen for the 'before_delete' event"

    # ... (event handling logic) ...

Hinweis

Dieses Ereignis gilt **nur** für die Sitzungs-Flush-Operation und gilt **nicht** für die ORM DML-Operationen, die unter ORM-aktivierte INSERT-, UPDATE- und DELETE-Anweisungen beschrieben sind. Um ORM DML-Ereignisse abzufangen, verwenden Sie SessionEvents.do_orm_execute().

Dieses Ereignis wird verwendet, um zusätzliche SQL-Anweisungen auf der angegebenen Verbindung auszugeben sowie anwendungsspezifische Buchhaltung für ein Löschereignis durchzuführen.

Das Ereignis wird oft für eine Gruppe von Objekten derselben Klasse aufgerufen, bevor deren DELETE-Anweisungen in einem späteren Schritt auf einmal ausgegeben werden.

Warnung

Mapper-Flush-Ereignisse erlauben **nur sehr begrenzte Operationen** auf Attributen, die lokal zur gerade bearbeiteten Zeile sind, sowie das Ausgeben von SQL auf der gegebenen Connection. **Bitte lesen Sie vollständig** die Hinweise unter Mapper-Level Flush Events für Richtlinien zur Verwendung dieser Methoden; im Allgemeinen sollte die Methode SessionEvents.before_flush() für allgemeine Änderungen während des Flush bevorzugt werden.

Parameter:

mapper¶ – Der Mapper, der das Ziel dieses Ereignisses ist.
connection¶ – Die Connection, die zum Ausgeben von DELETE-Anweisungen für diese Instanz verwendet wird. Dies bietet einen Zugriff auf die aktuelle Transaktion in der Zieldatenbank, die spezifisch für diese Instanz ist.
target¶ – Die zu löschende gemappte Instanz. Wenn das Ereignis mit raw=True konfiguriert ist, ist dies stattdessen das InstanceState-Objekt zur Zustandsverwaltung, das mit der Instanz verbunden ist.

Gibt zurück:

Kein Rückgabewert wird von diesem Ereignis unterstützt.

Siehe auch

methode sqlalchemy.orm.MapperEvents.before_insert(mapper: Mapper[_O], connection: Connection, target: _O) → None¶

Empfängt eine Objektinstanz, bevor eine INSERT-Anweisung für diese Instanz ausgegeben wird.

Beispielhafte Argumentformen

from sqlalchemy import event


@event.listens_for(SomeClass, 'before_insert')
def receive_before_insert(mapper, connection, target):
    "listen for the 'before_insert' event"

    # ... (event handling logic) ...

Hinweis

Dieses Ereignis gilt **nur** für die Sitzungs-Flush-Operation und gilt **nicht** für die ORM DML-Operationen, die unter ORM-aktivierte INSERT-, UPDATE- und DELETE-Anweisungen beschrieben sind. Um ORM DML-Ereignisse abzufangen, verwenden Sie SessionEvents.do_orm_execute().

Dieses Ereignis wird verwendet, um lokale, nicht objektbezogene Attribute der Instanz vor einem INSERT zu ändern und zusätzliche SQL-Anweisungen über die gegebene Verbindung auszugeben.

Das Ereignis wird oft für eine Gruppe von Objekten derselben Klasse aufgerufen, bevor deren INSERT-Anweisungen in einem späteren Schritt auf einmal ausgegeben werden. In dem extrem seltenen Fall, dass dies nicht erwünscht ist, kann das Mapper-Objekt mit batch=False konfiguriert werden, wodurch Instanzgruppen in einzelne (und schlechter performende) Ereignis->persist->Ereignisschritte aufgeteilt werden.

Warnung

Mapper-Flush-Ereignisse erlauben **nur sehr begrenzte Operationen** auf Attributen, die lokal zur gerade bearbeiteten Zeile sind, sowie das Ausgeben von SQL auf der gegebenen Connection. **Bitte lesen Sie vollständig** die Hinweise unter Mapper-Level Flush Events für Richtlinien zur Verwendung dieser Methoden; im Allgemeinen sollte die Methode SessionEvents.before_flush() für allgemeine Änderungen während des Flush bevorzugt werden.

Parameter:

mapper¶ – Der Mapper, der das Ziel dieses Ereignisses ist.
connection¶ – Die Connection, die zum Ausgeben von INSERT-Anweisungen für diese Instanz verwendet wird. Dies bietet einen Zugriff auf die aktuelle Transaktion in der Zieldatenbank, die spezifisch für diese Instanz ist.
target¶ – Die zu persistierende gemappte Instanz. Wenn das Ereignis mit raw=True konfiguriert ist, ist dies stattdessen das InstanceState-Objekt zur Zustandsverwaltung, das mit der Instanz verbunden ist.

Gibt zurück:

Kein Rückgabewert wird von diesem Ereignis unterstützt.

Siehe auch

MapperEvents.before_configured()

methode sqlalchemy.orm.MapperEvents.before_mapper_configured(mapper: Mapper[_O], class_: Type[_O]) → None¶

Wird kurz vor der Konfiguration eines bestimmten Mappers aufgerufen.

Beispielhafte Argumentformen

from sqlalchemy import event


@event.listens_for(SomeClass, 'before_mapper_configured')
def receive_before_mapper_configured(mapper, class_):
    "listen for the 'before_mapper_configured' event"

    # ... (event handling logic) ...

Dieses Ereignis ist dazu bestimmt, die Überspringung eines bestimmten Mappers während des Konfigurationsschritts zu ermöglichen, indem das Symbol interfaces.EXT_SKIP zurückgegeben wird, das dem configure_mappers()-Aufruf anzeigt, dass dieser bestimmte Mapper (oder eine Hierarchie von Mappern, wenn propagate=True verwendet wird) im aktuellen Konfigurationslauf übersprungen werden soll. Wenn ein oder mehrere Mapper übersprungen werden, bleibt das Flag "neue Mapper" gesetzt, was bedeutet, dass die Funktion configure_mappers() weiterhin aufgerufen wird, wenn Mapper verwendet werden, um zu versuchen, alle verfügbaren Mapper zu konfigurieren.

Im Vergleich zu den anderen Konfigurationsereignissen, MapperEvents.before_configured(), MapperEvents.after_configured() und MapperEvents.mapper_configured(), bietet das MapperEvents.before_mapper_configured()-Ereignis einen aussagekräftigen Rückgabewert, wenn es mit dem Parameter retval=True registriert wird.

Neu in Version 1.3.

z. B.

from sqlalchemy.orm import EXT_SKIP

Base = declarative_base()

DontConfigureBase = declarative_base()


@event.listens_for(
    DontConfigureBase,
    "before_mapper_configured",
    retval=True,
    propagate=True,
)
def dont_configure(mapper, cls):
    return EXT_SKIP

Siehe auch

MapperEvents.after_configured()

MapperEvents.mapper_configured()

methode sqlalchemy.orm.MapperEvents.before_update(mapper: Mapper[_O], connection: Connection, target: _O) → None¶

Empfängt eine Objektinstanz, bevor eine UPDATE-Anweisung für diese Instanz ausgegeben wird.

Beispielhafte Argumentformen

from sqlalchemy import event


@event.listens_for(SomeClass, 'before_update')
def receive_before_update(mapper, connection, target):
    "listen for the 'before_update' event"

    # ... (event handling logic) ...

Hinweis

Dieses Ereignis gilt **nur** für die Sitzungs-Flush-Operation und gilt **nicht** für die ORM DML-Operationen, die unter ORM-aktivierte INSERT-, UPDATE- und DELETE-Anweisungen beschrieben sind. Um ORM DML-Ereignisse abzufangen, verwenden Sie SessionEvents.do_orm_execute().

Dieses Ereignis wird verwendet, um lokale, nicht objektbezogene Attribute der Instanz vor einem UPDATE zu ändern und zusätzliche SQL-Anweisungen über die gegebene Verbindung auszugeben.

Diese Methode wird für alle Instanzen aufgerufen, die als "dirty" markiert sind, *auch solche, die keine Nettoänderungen an ihren spaltenbasierten Attributen aufweisen*. Ein Objekt wird als "dirty" markiert, wenn eine "set attribute"-Operation für eines seiner spaltenbasierten Attribute aufgerufen wird oder wenn eine seiner Sammlungen geändert wird. Wenn zum Zeitpunkt des Updates keine spaltenbasierten Attribute Nettoänderungen aufweisen, wird keine UPDATE-Anweisung ausgegeben. Das bedeutet, dass eine Instanz, die an MapperEvents.before_update() übergeben wird, *keine* Garantie dafür ist, dass eine UPDATE-Anweisung ausgegeben wird, obwohl Sie hier den Ausgang beeinflussen können, indem Sie Attribute ändern, sodass eine Nettoänderung des Werts vorhanden ist.

Um zu erkennen, ob die spaltenbasierten Attribute des Objekts Nettoänderungen aufweisen und somit eine UPDATE-Anweisung generieren werden, verwenden Sie object_session(instance).is_modified(instance, include_collections=False).

Das Ereignis wird oft für eine Gruppe von Objekten derselben Klasse aufgerufen, bevor deren UPDATE-Anweisungen in einem späteren Schritt auf einmal ausgegeben werden. In dem extrem seltenen Fall, dass dies nicht erwünscht ist, kann der Mapper mit batch=False konfiguriert werden, wodurch Instanzgruppen in einzelne (und schlechter performende) Ereignis->persist->Ereignisschritte aufgeteilt werden.

Warnung

Mapper-Flush-Ereignisse erlauben **nur sehr begrenzte Operationen** auf Attributen, die lokal zur gerade bearbeiteten Zeile sind, sowie das Ausgeben von SQL auf der gegebenen Connection. **Bitte lesen Sie vollständig** die Hinweise unter Mapper-Level Flush Events für Richtlinien zur Verwendung dieser Methoden; im Allgemeinen sollte die Methode SessionEvents.before_flush() für allgemeine Änderungen während des Flush bevorzugt werden.

Parameter:

mapper¶ – Der Mapper, der das Ziel dieses Ereignisses ist.
connection¶ – Die Connection, die zum Ausgeben von UPDATE-Anweisungen für diese Instanz verwendet wird. Dies bietet einen Zugriff auf die aktuelle Transaktion in der Zieldatenbank, die spezifisch für diese Instanz ist.
target¶ – Die zu persistierende gemappte Instanz. Wenn das Ereignis mit raw=True konfiguriert ist, ist dies stattdessen das InstanceState-Objekt zur Zustandsverwaltung, das mit der Instanz verbunden ist.

Gibt zurück:

Kein Rückgabewert wird von diesem Ereignis unterstützt.

Siehe auch