diff options
Diffstat (limited to 'lib')
| -rw-r--r-- | lib/sqlalchemy/orm/events.py | 22 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/session.py | 4 |
2 files changed, 17 insertions, 9 deletions
diff --git a/lib/sqlalchemy/orm/events.py b/lib/sqlalchemy/orm/events.py index bf3da5015..413bfbfcb 100644 --- a/lib/sqlalchemy/orm/events.py +++ b/lib/sqlalchemy/orm/events.py @@ -1683,11 +1683,13 @@ class SessionEvents(event.Events[Session]): This event is invoked for all top-level SQL statements invoked from the :meth:`_orm.Session.execute` method, as well as related methods such as :meth:`_orm.Session.scalars` and :meth:`_orm.Session.scalar`. 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. + SQLAlchemy 1.4, all ORM queries that run through the + :meth:`_orm.Session.execute` method as well as related methods + :meth:`_orm.Session.scalars`, :meth:`_orm.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 :ref:`session_flushing`. .. note:: The :meth:`_orm.SessionEvents.do_orm_execute` event hook is triggered **for ORM statement executions only**, meaning those @@ -1698,11 +1700,17 @@ class SessionEvents(event.Events[Session]): otherwise originating from an :class:`_engine.Engine` object without any :class:`_orm.Session` involved. To intercept **all** SQL executions regardless of whether the Core or ORM APIs are in use, - see the event hooks at - :class:`.ConnectionEvents`, such as + see the event hooks at :class:`.ConnectionEvents`, such as :meth:`.ConnectionEvents.before_execute` and :meth:`.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 :ref:`session_flushing`; to + intercept steps within the flush process, see the event + hooks described at :ref:`session_persistence_events` as + well as :ref:`session_persistence_mapper`. + 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 diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py index a39dbc3ec..760c71afd 100644 --- a/lib/sqlalchemy/orm/session.py +++ b/lib/sqlalchemy/orm/session.py @@ -546,8 +546,8 @@ class ORMExecuteState(util.MemoizedSlots): def is_orm_statement(self) -> bool: """return True if the operation is an ORM statement. - This indicates that the select(), update(), or delete() being - invoked contains ORM entities as subjects. For a statement + This indicates that the select(), insert(), update(), or delete() + being invoked contains ORM entities as subjects. For a statement that does not have ORM entities and instead refers only to :class:`.Table` metadata, it is invoked as a Core SQL statement and no ORM-level automation takes place. |