From fc57bafbae9d67b7ce95e26c939ca957c366b0f7 Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Tue, 21 Feb 2023 11:00:03 -0500 Subject: [PATCH] add notes to all mapper flush events that these are only for flush Fixes: #9339 Change-Id: I44542166417776733245e2ba39cd5de89b6d748b --- doc/build/orm/session_events.rst | 26 +++++++++++++++-------- lib/sqlalchemy/orm/events.py | 36 ++++++++++++++++++++++++++++++++ 2 files changed, 53 insertions(+), 9 deletions(-) diff --git a/doc/build/orm/session_events.rst b/doc/build/orm/session_events.rst index 5c2b22fc17..6223b53f64 100644 --- 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 ` , 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 5e8e9c0d9e..bf3da5015f 100644 --- 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 ` + 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 ` + 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 ` + 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 ` + 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 ` + 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 ` + 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. -- 2.47.2