sqlalchemy.orm.events.SessionEvents

Undocumented

Execute after an instance is attached to a session.

This is called after an add, delete or merge.

Execute after a transaction is begun on a connection

Execute after ORM DELETE against a WHERE expression has been invoked.

This is called as a result of the _query.Query.delete method.

Execute after an ORM UPDATE against a WHERE expression has been invoked.

This is called as a result of the _query.Query.update method.

Execute after a commit has occurred.

Execute after flush has completed, but before commit has been called.

Note that the session's state is still in pre-flush, i.e. 'new', 'dirty', and 'deleted' lists still show pre-flush state as well as the history settings on instance attributes.

Execute after flush has completed, and after the post-exec state occurs.

This will be when the 'new', 'dirty', and 'deleted' lists are in their final state. An actual commit() may or may not have occurred, depending on whether or not the flush started its own transaction or participated in a larger transaction.

Execute after a real DBAPI rollback has occurred.

Note that this event only fires when the actual rollback against the database occurs - it does not fire each time the .Session.rollback method is called, if the underlying DBAPI transaction has already been rolled back. In many cases, the .Session will not be in an "active" state during this event, as the current transaction is not valid. To acquire a .Session which is active after the outermost rollback has proceeded, use the .SessionEvents.after_soft_rollback event, checking the .Session.is_active flag.

Execute after any rollback has occurred, including "soft" rollbacks that don't actually emit at the DBAPI level.

This corresponds to both nested and outer rollbacks, i.e. the innermost rollback that calls the DBAPI's rollback() method, as well as the enclosing rollback calls that only pop themselves from the transaction stack.

The given .Session can be used to invoke SQL and .Session.query operations after an outermost rollback by first checking the .Session.is_active flag:

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

Execute when a new .SessionTransaction is created.

This event differs from ~.SessionEvents.after_begin in that it occurs for each .SessionTransaction overall, as opposed to when transactions are begun on individual database connections. It is also invoked for nested transactions and subtransactions, and is always matched by a corresponding ~.SessionEvents.after_transaction_end event (assuming normal operation of the .Session).

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

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

Execute when the span of a .SessionTransaction ends.

This event differs from ~.SessionEvents.after_commit in that it corresponds to all .SessionTransaction objects in use, including those for nested transactions and subtransactions, and is always matched by a corresponding ~.SessionEvents.after_transaction_create event.

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

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

Execute before an instance is attached to a session.

This is called before an add, delete or merge causes the object to be part of the session.

Execute before commit is called.

Execute before flush process has started.

Intercept the "deleted to detached" transition for a specific object.

This event is invoked when a deleted object is evicted from the session. The typical case when this occurs is when the transaction for a .Session in which the object was deleted is committed; the object moves from the deleted state to the detached state.

It is also invoked for objects that were deleted in a flush when the .Session.expunge_all or .Session.close events are called, as well as if the object is individually expunged from its deleted state via .Session.expunge.

Intercept the "deleted to persistent" transition for a specific object.

This transition occurs only when an object that's been deleted successfully in a flush is restored due to a call to .Session.rollback. The event is not called under any other circumstances.

Intercept the "detached to persistent" transition for a specific object.

This event is a specialization of the .SessionEvents.after_attach event which is only invoked for this specific transition. It is invoked typically during the .Session.add call, as well as during the .Session.delete call if the object was not previously associated with the .Session (note that an object marked as "deleted" remains in the "persistent" state until the flush proceeds).

Intercept statement executions that occur in terms of a .Session.

This event is invoked for all top-level SQL statements invoked from the _orm.Session.execute method. As of SQLAlchemy 1.4, all ORM queries emitted on behalf of a _orm.Session will flow through this method, so this event hook provides the single point at which ORM queries of all types may be intercepted before they are invoked, and additionally to replace their execution with a different process.

This event is a do_ event, meaning it has the capability to replace the operation that the _orm.Session.execute method normally performs. The intended use for this includes sharding and result-caching schemes which may seek to invoke the same statement across multiple database connections, returning a result that is merged from each of them, or which don't invoke the statement at all, instead returning data from a cache.

The hook intends to replace the use of the Query._execute_and_instances method that could be subclassed prior to SQLAlchemy 1.4.

Intercept the "loaded as persistent" transition for a specific object.

This event is invoked within the ORM loading process, and is invoked very similarly to the .InstanceEvents.load event. However, the event here is linkable to a .Session class or instance, rather than to a mapper or class hierarchy, and integrates with the other session lifecycle events smoothly. The object is guaranteed to be present in the session's identity map when this event is called.

Intercept the "pending to persistent"" transition for a specific object.

This event is invoked within the flush process, and is similar to scanning the .Session.new collection within the .SessionEvents.after_flush event. However, in this case the object has already been moved to the persistent state when the event is called.

Intercept the "pending to transient" transition for a specific object.

This less common transition occurs when an pending object that has not been flushed is evicted from the session; this can occur when the .Session.rollback method rolls back the transaction, or when the .Session.expunge method is used.

Intercept the "persistent to deleted" transition for a specific object.

This event is invoked when a persistent object's identity is deleted from the database within a flush, however the object still remains associated with the .Session until the transaction completes.

If the transaction is rolled back, the object moves again to the persistent state, and the .SessionEvents.deleted_to_persistent event is called. If the transaction is committed, the object becomes detached, which will emit the .SessionEvents.deleted_to_detached event.

Note that while the .Session.delete method is the primary public interface to mark an object as deleted, many objects get deleted due to cascade rules, which are not always determined until flush time. Therefore, there's no way to catch every object that will be deleted until the flush has proceeded. the .SessionEvents.persistent_to_deleted event is therefore invoked at the end of a flush.

Intercept the "persistent to detached" transition for a specific object.

This event is invoked when a persistent object is evicted from the session. There are many conditions that cause this to happen, including:

• using a method such as .Session.expunge or .Session.close
• Calling the .Session.rollback method, when the object was part of an INSERT statement for that session's transaction

Intercept the "persistent to transient" transition for a specific object.

This less common transition occurs when an pending object that has has been flushed is evicted from the session; this can occur when the .Session.rollback method rolls back the transaction.

Intercept the "transient to pending" transition for a specific object.

This event is a specialization of the .SessionEvents.after_attach event which is only invoked for this specific transition. It is invoked typically during the .Session.add call.