SQLAlchemy 2.0 Documentation

SessionEvents.before_commit()

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

Execute after a transaction is begun on a connection

Example argument forms:

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) ...

Parameters:

session – The target Session.
transaction – The SessionTransaction.
connection – The Connection object which will be used for SQL statements.

See also

SessionEvents.after_commit()

QueryEvents.before_compile_delete()

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

Event for after the legacy Query.delete() method has been called.

Example argument forms:

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) ...

Changed in version 0.9: The SessionEvents.after_bulk_delete() event now accepts the arguments SessionEvents.after_bulk_delete.delete_context. Support for listener functions which accept the previous argument signature(s) listed above as “deprecated” will be removed in a future release.

Legacy Feature

The SessionEvents.after_bulk_delete() method is a legacy event hook as of SQLAlchemy 2.0. The event does not participate in 2.0 style invocations using delete() documented at ORM UPDATE and DELETE with Custom WHERE Criteria. For 2.0 style use, the SessionEvents.do_orm_execute() hook will intercept these calls.

Parameters:

delete_context –

a “delete context” object which contains details about the update, including these attributes:

session - the Session involved

query -the Query object that this update operation was called upon.

result the CursorResult returned as a result of the bulk DELETE operation.

Changed in version 1.4: the update_context no longer has a QueryContext object associated with it.

See also

SessionEvents.after_bulk_update()

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

Event for after the legacy Query.update() method has been called.

Example argument forms:

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) ...

Changed in version 0.9: The SessionEvents.after_bulk_update() event now accepts the arguments SessionEvents.after_bulk_update.update_context. Support for listener functions which accept the previous argument signature(s) listed above as “deprecated” will be removed in a future release.

Legacy Feature

The SessionEvents.after_bulk_update() method is a legacy event hook as of SQLAlchemy 2.0. The event does not participate in 2.0 style invocations using update() documented at ORM UPDATE and DELETE with Custom WHERE Criteria. For 2.0 style use, the SessionEvents.do_orm_execute() hook will intercept these calls.

Parameters:

update_context –

an “update context” object which contains details about the update, including these attributes:

session - the Session involved

query -the Query object that this update operation was called upon.

values The “values” dictionary that was passed to Query.update().

result the CursorResult returned as a result of the bulk UPDATE operation.

Changed in version 1.4: the update_context no longer has a QueryContext object associated with it.

See also

QueryEvents.before_compile_update()

SessionEvents.after_bulk_delete()

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

Execute after a commit has occurred.

Example argument forms:

from sqlalchemy import event


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

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

Note

The SessionEvents.after_commit() hook is not per-flush, that is, the Session can emit SQL to the database many times within the scope of a transaction. For interception of these events, use the SessionEvents.before_flush(), SessionEvents.after_flush(), or SessionEvents.after_flush_postexec() events.

Note

The Session is not in an active transaction when the SessionEvents.after_commit() event is invoked, and therefore can not emit SQL. To emit SQL corresponding to every transaction, use the SessionEvents.before_commit() event.

Parameters:: session – The target Session.

See also

SessionEvents.before_commit()

SessionEvents.after_begin()

SessionEvents.before_flush()

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

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

Example argument forms:

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) ...

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.

Warning

This event runs after the Session has emitted SQL to modify the database, but before it has altered its internal state to reflect those changes, including that newly inserted objects are placed into the identity map. ORM operations emitted within this event such as loads of related items may produce new identity map entries that will immediately be replaced, sometimes causing confusing results. SQLAlchemy will emit a warning for this condition as of version 1.3.9.

Parameters:

session – The target Session.
flush_context – Internal UOWTransaction object which handles the details of the flush.

See also

SessionEvents.after_flush_postexec()

SessionEvents.before_flush()

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

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

Example argument forms:

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) ...

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.

Parameters:

session – The target Session.
flush_context – Internal UOWTransaction object which handles the details of the flush.

See also

SessionEvents.after_flush()

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

Execute after a real DBAPI rollback has occurred.

Example argument forms:

from sqlalchemy import event


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

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

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.

Parameters:: session – The target Session.

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

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

Example argument forms:

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) ...

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")

Parameters:

session – The target Session.
previous_transaction – The SessionTransaction transactional marker object which was just closed. The current SessionTransaction for the given Session is available via the Session.transaction attribute.

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

Execute when a new SessionTransaction is created.

Example argument forms:

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) ...

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).

Parameters:

session – the target Session.

transaction –

the target SessionTransaction.

To detect if this is the outermost SessionTransaction, as opposed to a “subtransaction” or a SAVEPOINT, test that the SessionTransaction.parent attribute is None:

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

To detect if the SessionTransaction is a SAVEPOINT, use the SessionTransaction.nested attribute:

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

See also

SessionTransaction

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

Execute when the span of a SessionTransaction ends.

Example argument forms:

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) ...

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.

Parameters:

session – the target Session.

transaction –

the target SessionTransaction.

To detect if this is the outermost SessionTransaction, as opposed to a “subtransaction” or a SAVEPOINT, test that the SessionTransaction.parent attribute is None:

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

To detect if the SessionTransaction is a SAVEPOINT, use the SessionTransaction.nested attribute:

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

See also

SessionTransaction

SessionEvents.after_attach()

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

Execute before an instance is attached to a session.

Example argument forms:

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) ...

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

See also

SessionEvents.after_commit()

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

Execute before commit is called.

Example argument forms:

from sqlalchemy import event


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

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

Note

The SessionEvents.before_commit() hook is not per-flush, that is, the Session can emit SQL to the database many times within the scope of a transaction. For interception of these events, use the SessionEvents.before_flush(), SessionEvents.after_flush(), or SessionEvents.after_flush_postexec() events.

Parameters:: session – The target Session.

See also

SessionEvents.after_begin()

SessionEvents.after_flush()

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

Execute before flush process has started.

Example argument forms:

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) ...

Parameters:

session – The target Session.
flush_context – Internal UOWTransaction object which handles the details of the flush.
instances – Usually None, this is the collection of objects which can be passed to the Session.flush() method (note this usage is deprecated).

See also

SessionEvents.after_flush_postexec()

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

Intercept the “deleted to detached” transition for a specific object.

Example argument forms:

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) ...

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().

See also

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

Intercept the “deleted to persistent” transition for a specific object.

Example argument forms:

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) ...

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.

See also

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

Intercept the “detached to persistent” transition for a specific object.

Example argument forms:

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) ...

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).

Note

If the object becomes persistent as part of a call to Session.delete(), the object is not yet marked as deleted when this event is called. To detect deleted objects, check the deleted flag sent to the SessionEvents.persistent_to_detached() to event after the flush proceeds, or check the Session.deleted collection within the SessionEvents.before_flush() event if deleted objects need to be intercepted before the flush.

Parameters:

session – target Session
instance – the ORM-mapped instance being operated upon.

See also

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

reference back to the _Dispatch class.

Bidirectional against _Dispatch._events

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

Intercept statement executions that occur on behalf of an ORM Session object.

Example argument forms:

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) ...

This event is invoked for all top-level SQL statements invoked from the Session.execute() method, as well as related methods such as Session.scalars() and Session.scalar(). As of SQLAlchemy 1.4, all ORM queries that run through the Session.execute() method as well as related methods Session.scalars(), Session.scalar() etc. will participate in this event. This event hook does not apply to the queries that are emitted internally within the ORM flush process, i.e. the process described at Flushing.

Note

The SessionEvents.do_orm_execute() event hook is triggered for ORM statement executions only, meaning those invoked via the Session.execute() and similar methods on the Session object. It does not trigger for statements that are invoked by SQLAlchemy Core only, i.e. statements invoked directly using Connection.execute() or otherwise originating from an Engine object without any Session involved. To intercept all SQL executions regardless of whether the Core or ORM APIs are in use, see the event hooks at ConnectionEvents, such as ConnectionEvents.before_execute() and ConnectionEvents.before_cursor_execute().

Also, this event hook does not apply to queries that are emitted internally within the ORM flush process, i.e. the process described at Flushing; to intercept steps within the flush process, see the event hooks described at Persistence Events as well as Mapper-level Flush Events.

This event is a do_ event, meaning it has the capability to replace the operation that the 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.

Parameters:: orm_execute_state – an instance of ORMExecuteState which contains all information about the current execution, as well as helper functions used to derive other commonly required information. See that object for details.

See also

Execute Events - top level documentation on how to use SessionEvents.do_orm_execute()

ORMExecuteState - the object passed to the SessionEvents.do_orm_execute() event which contains all information about the statement to be invoked. It also provides an interface to extend the current statement, options, and parameters as well as an option that allows programmatic invocation of the statement at any point.

ORM Query Events - includes examples of using SessionEvents.do_orm_execute()

Dogpile Caching - an example of how to integrate Dogpile caching with the ORM Session making use of the SessionEvents.do_orm_execute() event hook.

Horizontal Sharding - the Horizontal Sharding example / extension relies upon the SessionEvents.do_orm_execute() event hook to invoke a SQL statement on multiple backends and return a merged result.

New in version 1.4.

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

Intercept the “loaded as persistent” transition for a specific object.

Example argument forms:

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) ...

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.

Note

This event is invoked within the loader process before eager loaders may have been completed, and the object’s state may not be complete. Additionally, invoking row-level refresh operations on the object will place the object into a new loader context, interfering with the existing load context. See the note on InstanceEvents.load() for background on making use of the SessionEvents.restore_load_context parameter, which works in the same manner as that of InstanceEvents.restore_load_context, in order to resolve this scenario.

Parameters:

session – target Session
instance – the ORM-mapped instance being operated upon.

See also

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

Intercept the “pending to persistent”” transition for a specific object.

Example argument forms:

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) ...

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.

Parameters:

session – target Session
instance – the ORM-mapped instance being operated upon.

See also

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

Intercept the “pending to transient” transition for a specific object.

Example argument forms:

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) ...

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.

Parameters:

session – target Session
instance – the ORM-mapped instance being operated upon.

See also

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

Intercept the “persistent to deleted” transition for a specific object.

Example argument forms:

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) ...

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.

See also

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

Intercept the “persistent to detached” transition for a specific object.

Example argument forms:

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) ...

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

Parameters:

session – target Session
instance – the ORM-mapped instance being operated upon.
deleted – boolean. If True, indicates this object moved to the detached state because it was marked as deleted and flushed.

See also

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

Intercept the “persistent to transient” transition for a specific object.

Example argument forms:

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) ...

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.

Parameters:

session – target Session
instance – the ORM-mapped instance being operated upon.

See also

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

Intercept the “transient to pending” transition for a specific object.

Example argument forms:

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) ...

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.

Parameters:

session – target Session
instance – the ORM-mapped instance being operated upon.

See also

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 event hooks encompass things that happen as related to individual or multiple Mapper objects, which are the central configurational object that maps a user-defined class to a Table object. Types of things which occur at the Mapper level include:

Per-object persistence operations - the most popular mapper hooks are the unit-of-work hooks such as MapperEvents.before_insert(), MapperEvents.after_update(), etc. These events are contrasted to the more coarse grained session-level events such as SessionEvents.before_flush() in that they occur within the flush process on a per-object basis; while finer grained activity on an object is more straightforward, availability of Session features is limited.
Mapper configuration events - the other major class of mapper hooks are those which occur as a class is mapped, as a mapper is finalized, and when sets of mappers are configured to refer to each other. These events include MapperEvents.instrument_class(), MapperEvents.before_mapper_configured() and MapperEvents.mapper_configured() at the individual Mapper level, and MapperEvents.before_configured() and MapperEvents.after_configured() at the level of collections of Mapper objects.

Object Name	Description
MapperEvents	Define events specific to mappings.

class sqlalchemy.orm.MapperEvents¶

Define events specific to mappings.

e.g.:

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)

Available targets include:

mapped classes
unmapped superclasses of mapped or to-be-mapped classes (using the propagate=True flag)
Mapper objects
the Mapper class itself indicates listening for all mappers.

Mapper events provide hooks into critical sections of the mapper, including those related to object instrumentation, object loading, and object persistence. In particular, the persistence methods MapperEvents.before_insert(), and MapperEvents.before_update() are popular places to augment the state being persisted - however, these methods operate with several significant restrictions. The user is encouraged to evaluate the SessionEvents.before_flush() and SessionEvents.after_flush() methods as more flexible and user-friendly hooks in which to apply additional database state during a flush.

When using MapperEvents, several modifiers are available to the listen() function.

Parameters:

propagate=False – When True, the event listener should be applied to all inheriting mappers and/or the mappers of inheriting classes, as well as any mapper which is the target of this listener.
raw=False – When True, the “target” argument passed to applicable event listener functions will be the instance’s InstanceState management object, rather than the mapped instance itself.
retval=False –
when True, the user-defined event function must have a return value, the purpose of which is either to control subsequent event propagation, or to otherwise alter the operation in progress by the mapper. Possible return values are:
- sqlalchemy.orm.interfaces.EXT_CONTINUE - continue event processing normally.
- sqlalchemy.orm.interfaces.EXT_STOP - cancel all subsequent event handlers in the chain.
- other values - the return value specified by specific listeners.

Members

Class signature

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

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

Called after a series of mappers have been configured.

Example argument forms:

from sqlalchemy import event


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

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

The MapperEvents.after_configured() event is invoked each time the configure_mappers() function is invoked, after the function has completed its work. configure_mappers() is typically invoked automatically as mappings are first used, as well as each time new mappers have been made available and new mapper use is detected.

Contrast this event to the MapperEvents.mapper_configured() event, which is called on a per-mapper basis while the configuration operation proceeds; unlike that event, when this event is invoked, all cross-configurations (e.g. backrefs) will also have been made available for any mappers that were pending. Also contrast to MapperEvents.before_configured(), which is invoked before the series of mappers has been configured.

This event can only be applied to the Mapper class, and not to individual mappings or mapped classes. It is only invoked for all mappings as a whole:

from sqlalchemy.orm import Mapper

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

Theoretically this event is called once per application, but is actually called any time new mappers have been affected by a configure_mappers() call. If new mappings are constructed after existing ones have already been used, this event will likely be called again. To ensure that a particular event is only called once and no further, the once=True argument (new in 0.9.4) can be applied:

from sqlalchemy.orm import mapper

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

MapperEvents.mapper_configured()

MapperEvents.before_configured()

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

Receive an object instance after a DELETE statement has been emitted corresponding to that instance.

Example argument forms:

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) ...

Note

this event only applies to the session flush operation and does not apply to the ORM DML operations described at ORM-Enabled INSERT, UPDATE, and DELETE statements. To intercept ORM DML events, use SessionEvents.do_orm_execute().

This event is used to emit additional SQL statements on the given connection as well as to perform application specific bookkeeping related to a deletion event.

The event is often called for a batch of objects of the same class after their DELETE statements have been emitted at once in a previous step.

Warning

Mapper-level flush events only allow very limited operations, on attributes local to the row being operated upon only, as well as allowing any SQL to be emitted on the given Connection. Please read fully the notes at Mapper-level Flush Events for guidelines on using these methods; generally, the SessionEvents.before_flush() method should be preferred for general on-flush changes.

Parameters:

mapper – the Mapper which is the target of this event.
connection – the Connection being used to emit DELETE statements for this instance. This provides a handle into the current transaction on the target database specific to this instance.
target – the mapped instance being deleted. If the event is configured with raw=True, this will instead be the InstanceState state-management object associated with the instance.

Returns:

No return value is supported by this event.

See also

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

Receive an object instance after an INSERT statement is emitted corresponding to that instance.

Example argument forms:

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) ...

Note

this event only applies to the session flush operation and does not apply to the ORM DML operations described at ORM-Enabled INSERT, UPDATE, and DELETE statements. To intercept ORM DML events, use SessionEvents.do_orm_execute().

This event is used to modify in-Python-only state on the instance after an INSERT occurs, as well as to emit additional SQL statements on the given connection.

The event is often called for a batch of objects of the same class after their INSERT statements have been emitted at once in a previous step. In the extremely rare case that this is not desirable, the Mapper object can be configured with batch=False, which will cause batches of instances to be broken up into individual (and more poorly performing) event->persist->event steps.

Warning

Mapper-level flush events only allow very limited operations, on attributes local to the row being operated upon only, as well as allowing any SQL to be emitted on the given Connection. Please read fully the notes at Mapper-level Flush Events for guidelines on using these methods; generally, the SessionEvents.before_flush() method should be preferred for general on-flush changes.

Parameters:

mapper – the Mapper which is the target of this event.
connection – the Connection being used to emit INSERT statements for this instance. This provides a handle into the current transaction on the target database specific to this instance.
target – the mapped instance being persisted. If the event is configured with raw=True, this will instead be the InstanceState state-management object associated with the instance.

Returns:

No return value is supported by this event.

See also

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

Receive a class and mapper when the Mapper has been fully constructed.

Example argument forms:

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) ...

This event is called after the initial constructor for Mapper completes. This occurs after the MapperEvents.instrument_class() event and after the Mapper has done an initial pass of its arguments to generate its collection of MapperProperty objects, which are accessible via the Mapper.get_property() method and the Mapper.iterate_properties attribute.

This event differs from the MapperEvents.before_mapper_configured() event in that it is invoked within the constructor for Mapper, rather than within the registry.configure() process. Currently, this event is the only one which is appropriate for handlers that wish to create additional mapped classes in response to the construction of this Mapper, which will be part of the same configure step when registry.configure() next runs.

New in version 2.0.2.

See also

Versioning Objects - an example which illustrates the use of the MapperEvents.before_mapper_configured() event to create new mappers to record change-audit histories on objects.

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

Receive an object instance after an UPDATE statement is emitted corresponding to that instance.

Example argument forms:

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) ...

Note

this event only applies to the session flush operation and does not apply to the ORM DML operations described at ORM-Enabled INSERT, UPDATE, and DELETE statements. To intercept ORM DML events, use SessionEvents.do_orm_execute().

This event is used to modify in-Python-only state on the instance after an UPDATE occurs, as well as to emit additional SQL statements on the given connection.

This method is called for all instances that are marked as “dirty”, even those which have no net changes to their column-based attributes, and for which no UPDATE statement has proceeded. An object is marked as dirty when any of its column-based attributes have a “set attribute” operation called or when any of its collections are modified. If, at update time, no column-based attributes have any net changes, no UPDATE statement will be issued. This means that an instance being sent to MapperEvents.after_update() is not a guarantee that an UPDATE statement has been issued.

To detect if the column-based attributes on the object have net changes, and therefore resulted in an UPDATE statement, use object_session(instance).is_modified(instance, include_collections=False).

The event is often called for a batch of objects of the same class after their UPDATE statements have been emitted at once in a previous step. In the extremely rare case that this is not desirable, the Mapper can be configured with batch=False, which will cause batches of instances to be broken up into individual (and more poorly performing) event->persist->event steps.

Warning

Mapper-level flush events only allow very limited operations, on attributes local to the row being operated upon only, as well as allowing any SQL to be emitted on the given Connection. Please read fully the notes at Mapper-level Flush Events for guidelines on using these methods; generally, the SessionEvents.before_flush() method should be preferred for general on-flush changes.

Parameters:

mapper – the Mapper which is the target of this event.
connection – the Connection being used to emit UPDATE statements for this instance. This provides a handle into the current transaction on the target database specific to this instance.
target – the mapped instance being persisted. If the event is configured with raw=True, this will instead be the InstanceState state-management object associated with the instance.

Returns:

No return value is supported by this event.

See also

MapperEvents.mapper_configured()

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

Called before a series of mappers have been configured.

Example argument forms:

from sqlalchemy import event


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

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

The MapperEvents.before_configured() event is invoked each time the configure_mappers() function is invoked, before the function has done any of its work. configure_mappers() is typically invoked automatically as mappings are first used, as well as each time new mappers have been made available and new mapper use is detected.

This event can only be applied to the Mapper class, and not to individual mappings or mapped classes. It is only invoked for all mappings as a whole:

from sqlalchemy.orm import Mapper

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

Contrast this event to MapperEvents.after_configured(), which is invoked after the series of mappers has been configured, as well as MapperEvents.before_mapper_configured() and MapperEvents.mapper_configured(), which are both invoked on a per-mapper basis.

Theoretically this event is called once per application, but is actually called any time new mappers are to be affected by a configure_mappers() call. If new mappings are constructed after existing ones have already been used, this event will likely be called again. To ensure that a particular event is only called once and no further, the once=True argument (new in 0.9.4) can be applied:

from sqlalchemy.orm import mapper

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

MapperEvents.after_configured()

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

Receive an object instance before a DELETE statement is emitted corresponding to that instance.

Example argument forms:

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) ...

Note

this event only applies to the session flush operation and does not apply to the ORM DML operations described at ORM-Enabled INSERT, UPDATE, and DELETE statements. To intercept ORM DML events, use SessionEvents.do_orm_execute().

This event is used to emit additional SQL statements on the given connection as well as to perform application specific bookkeeping related to a deletion event.

The event is often called for a batch of objects of the same class before their DELETE statements are emitted at once in a later step.

Warning

Mapper-level flush events only allow very limited operations, on attributes local to the row being operated upon only, as well as allowing any SQL to be emitted on the given Connection. Please read fully the notes at Mapper-level Flush Events for guidelines on using these methods; generally, the SessionEvents.before_flush() method should be preferred for general on-flush changes.

Parameters:

mapper – the Mapper which is the target of this event.
connection – the Connection being used to emit DELETE statements for this instance. This provides a handle into the current transaction on the target database specific to this instance.
target – the mapped instance being deleted. If the event is configured with raw=True, this will instead be the InstanceState state-management object associated with the instance.

Returns:

No return value is supported by this event.

See also

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

Receive an object instance before an INSERT statement is emitted corresponding to that instance.

Example argument forms:

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) ...

Note

this event only applies to the session flush operation and does not apply to the ORM DML operations described at ORM-Enabled INSERT, UPDATE, and DELETE statements. To intercept ORM DML events, use SessionEvents.do_orm_execute().

This event is used to modify local, non-object related attributes on the instance before an INSERT occurs, as well as to emit additional SQL statements on the given connection.

The event is often called for a batch of objects of the same class before their INSERT statements are emitted at once in a later step. In the extremely rare case that this is not desirable, the Mapper object can be configured with batch=False, which will cause batches of instances to be broken up into individual (and more poorly performing) event->persist->event steps.

Warning

Mapper-level flush events only allow very limited operations, on attributes local to the row being operated upon only, as well as allowing any SQL to be emitted on the given Connection. Please read fully the notes at Mapper-level Flush Events for guidelines on using these methods; generally, the SessionEvents.before_flush() method should be preferred for general on-flush changes.

Parameters:

mapper – the Mapper which is the target of this event.
connection – the Connection being used to emit INSERT statements for this instance. This provides a handle into the current transaction on the target database specific to this instance.
target – the mapped instance being persisted. If the event is configured with raw=True, this will instead be the InstanceState state-management object associated with the instance.

Returns:

No return value is supported by this event.

See also

MapperEvents.before_configured()

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

Called right before a specific mapper is to be configured.

Example argument forms:

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) ...

This event is intended to allow a specific mapper to be skipped during the configure step, by returning the interfaces.EXT_SKIP symbol which indicates to the configure_mappers() call that this particular mapper (or hierarchy of mappers, if propagate=True is used) should be skipped in the current configuration run. When one or more mappers are skipped, the he “new mappers” flag will remain set, meaning the configure_mappers() function will continue to be called when mappers are used, to continue to try to configure all available mappers.

In comparison to the other configure-level events, MapperEvents.before_configured(), MapperEvents.after_configured(), and MapperEvents.mapper_configured(), the :meth;`.MapperEvents.before_mapper_configured` event provides for a meaningful return value when it is registered with the retval=True parameter.

New in version 1.3.

e.g.:

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

See also

MapperEvents.after_configured()

MapperEvents.mapper_configured()

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

Receive an object instance before an UPDATE statement is emitted corresponding to that instance.

Example argument forms:

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) ...

Note

this event only applies to the session flush operation and does not apply to the ORM DML operations described at ORM-Enabled INSERT, UPDATE, and DELETE statements. To intercept ORM DML events, use SessionEvents.do_orm_execute().

This event is used to modify local, non-object related attributes on the instance before an UPDATE occurs, as well as to emit additional SQL statements on the given connection.

This method is called for all instances that are marked as “dirty”, even those which have no net changes to their column-based attributes. An object is marked as dirty when any of its column-based attributes have a “set attribute” operation called or when any of its collections are modified. If, at update time, no column-based attributes have any net changes, no UPDATE statement will be issued. This means that an instance being sent to MapperEvents.before_update() is not a guarantee that an UPDATE statement will be issued, although you can affect the outcome here by modifying attributes so that a net change in value does exist.

To detect if the column-based attributes on the object have net changes, and will therefore generate an UPDATE statement, use object_session(instance).is_modified(instance, include_collections=False).

The event is often called for a batch of objects of the same class before their UPDATE statements are emitted at once in a later step. In the extremely rare case that this is not desirable, the Mapper can be configured with batch=False, which will cause batches of instances to be broken up into individual (and more poorly performing) event->persist->event steps.

Warning

Mapper-level flush events only allow very limited operations, on attributes local to the row being operated upon only, as well as allowing any SQL to be emitted on the given Connection. Please read fully the notes at Mapper-level Flush Events for guidelines on using these methods; generally, the SessionEvents.before_flush() method should be preferred for general on-flush changes.

Parameters:

mapper – the Mapper which is the target of this event.
connection – the Connection being used to emit UPDATE statements for this instance. This provides a handle into the current transaction on the target database specific to this instance.
target – the mapped instance being persisted. If the event is configured with raw=True, this will instead be the InstanceState state-management object associated with the instance.

Returns:

No return value is supported by this event.

See also