add notes to all mapper flush events that these are only for flush

Fixes: #9339
Change-Id: I44542166417776733245e2ba39cd5de89b6d748b

diff --git a/doc/build/orm/session_events.rst b/doc/build/orm/session_events.rst
index 5c2b22fc174f6658e4fd0373b627a8a79261d0c6..6223b53f64bcf3c9e74dcbce0636b676f0b03e40 100644 (file)
--- a/doc/build/orm/session_events.rst
+++ b/doc/build/orm/session_events.rst
@@ -335,16 +335,16 @@ hook continually adds new state to be flushed each time it is called.
 
 .. _session_persistence_mapper:
 
-Mapper-level Events
-^^^^^^^^^^^^^^^^^^^
+Mapper-level Flush Events
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
-In addition to the flush-level hooks, there is also a suite of hooks
-that are more fine-grained, in that they are called on a per-object
-basis and are broken out based on INSERT, UPDATE or DELETE.   These
-are the mapper persistence hooks, and they too are very popular,
-however these events need to be approached more cautiously, as they
-proceed within the context of the flush process that is already
-ongoing; many operations are not safe to proceed here.
+In addition to the flush-level hooks, there is also a suite of hooks that are
+more fine-grained, in that they are called on a per-object basis and are broken
+out based on INSERT, UPDATE or DELETE within the flush process. These are the
+mapper persistence hooks, and they too are very popular, however these events
+need to be approached more cautiously, as they proceed within the context of
+the flush process that is already ongoing; many operations are not safe to
+proceed here.
 
 The events are:
 
@@ -355,6 +355,14 @@ The events are:
 * :meth:`.MapperEvents.before_delete`
 * :meth:`.MapperEvents.after_delete`
 
+.. note::
+
+  It is important to note that these events apply **only** to the
+  :ref:`session flush operation <session_flushing>` , and **not** to the
+  ORM-level INSERT/UPDATE/DELETE functionality described at
+  :ref:`orm_expression_update_delete`. To intercept ORM-level DML, use the
+  :meth:`_orm.SessionEvents.do_orm_execute` event.
+
 Each event is passed the :class:`_orm.Mapper`,
 the mapped object itself, and the :class:`_engine.Connection` which is being
 used to emit an INSERT, UPDATE or DELETE statement.     The appeal of these

diff --git a/lib/sqlalchemy/orm/events.py b/lib/sqlalchemy/orm/events.py
index 5e8e9c0d9efa5d8511541814d9012d05593ad1b3..bf3da5015f5bee95c7ed0ba26b71f20a8e3488c0 100644 (file)
--- a/lib/sqlalchemy/orm/events.py
+++ b/lib/sqlalchemy/orm/events.py
@@ -1189,6 +1189,12 @@ class MapperEvents(event.Events[mapperlib.Mapper[Any]]):
         """Receive an object instance before an INSERT statement
         is emitted corresponding to that instance.
 
+        .. note:: this event **only** applies to the
+           :ref:`session flush operation <session_flushing>`
+           and does **not** apply to the ORM DML operations described at
+           :ref:`orm_expression_update_delete`.  To intercept ORM
+           DML events, use :meth:`_orm.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
@@ -1237,6 +1243,12 @@ class MapperEvents(event.Events[mapperlib.Mapper[Any]]):
         """Receive an object instance after an INSERT statement
         is emitted corresponding to that instance.
 
+        .. note:: this event **only** applies to the
+           :ref:`session flush operation <session_flushing>`
+           and does **not** apply to the ORM DML operations described at
+           :ref:`orm_expression_update_delete`.  To intercept ORM
+           DML events, use :meth:`_orm.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
@@ -1285,6 +1297,12 @@ class MapperEvents(event.Events[mapperlib.Mapper[Any]]):
         """Receive an object instance before an UPDATE statement
         is emitted corresponding to that instance.
 
+        .. note:: this event **only** applies to the
+           :ref:`session flush operation <session_flushing>`
+           and does **not** apply to the ORM DML operations described at
+           :ref:`orm_expression_update_delete`.  To intercept ORM
+           DML events, use :meth:`_orm.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
@@ -1352,6 +1370,12 @@ class MapperEvents(event.Events[mapperlib.Mapper[Any]]):
         """Receive an object instance after an UPDATE statement
         is emitted corresponding to that instance.
 
+        .. note:: this event **only** applies to the
+           :ref:`session flush operation <session_flushing>`
+           and does **not** apply to the ORM DML operations described at
+           :ref:`orm_expression_update_delete`.  To intercept ORM
+           DML events, use :meth:`_orm.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
@@ -1418,6 +1442,12 @@ class MapperEvents(event.Events[mapperlib.Mapper[Any]]):
         """Receive an object instance before a DELETE statement
         is emitted corresponding to that instance.
 
+        .. note:: this event **only** applies to the
+           :ref:`session flush operation <session_flushing>`
+           and does **not** apply to the ORM DML operations described at
+           :ref:`orm_expression_update_delete`.  To intercept ORM
+           DML events, use :meth:`_orm.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.
@@ -1460,6 +1490,12 @@ class MapperEvents(event.Events[mapperlib.Mapper[Any]]):
         """Receive an object instance after a DELETE statement
         has been emitted corresponding to that instance.
 
+        .. note:: this event **only** applies to the
+           :ref:`session flush operation <session_flushing>`
+           and does **not** apply to the ORM DML operations described at
+           :ref:`orm_expression_update_delete`.  To intercept ORM
+           DML events, use :meth:`_orm.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.