Classe « SessionEvents »

Méthode sqlalchemy.orm.SessionEvents.do_orm_execute

Signature de la méthode do_orm_execute

def do_orm_execute(self, orm_execute_state) 

Description

do_orm_execute.__doc__

Intercept statement executions that occur in terms of a :class:`.Session`.

.. container:: event_signatures

     Example argument forms::

        from sqlalchemy import event


        @event.listens_for(SomeSessionOrFactory, '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 :meth:`_orm.Session.execute` method.   As of SQLAlchemy 1.4,
all ORM queries emitted on behalf of a :class:`_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 :meth:`_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.

:param orm_execute_state: an instance of :class:`.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.

.. seealso::

    :ref:`session_execute_events` - top level documentation on how
    to use :meth:`_orm.SessionEvents.do_orm_execute`

    :class:`.ORMExecuteState` - the object passed to the
    :meth:`_orm.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.

    :ref:`examples_session_orm_events` - includes examples of using
    :meth:`_orm.SessionEvents.do_orm_execute`

    :ref:`examples_caching` - an example of how to integrate
    Dogpile caching with the ORM :class:`_orm.Session` making use
    of the :meth:`_orm.SessionEvents.do_orm_execute` event hook.

    :ref:`examples_sharding` - the Horizontal Sharding example /
    extension relies upon the
    :meth:`_orm.SessionEvents.do_orm_execute` event hook to invoke a
    SQL statement on multiple backends and return a merged result.


.. versionadded:: 1.4