add more discouragment from using before_/after_ mapper events for anything ORM-heavy

diff --git a/lib/sqlalchemy/orm/events.py b/lib/sqlalchemy/orm/events.py
index a8162fa723686c9739905b002e4b404bb014976c..913d764dac168f1a1bbfde5e07159bd779373da3 100644 (file)
--- a/lib/sqlalchemy/orm/events.py
+++ b/lib/sqlalchemy/orm/events.py
@@ -581,6 +581,14 @@ class MapperEvents(event.Events):
         into individual (and more poorly performing)
         event->persist->event steps.
 
+        Handlers should **not** alter mapped attributes on the objects
+        just flushed or on other objects of the same class, nor
+        should any other ORM-based operation such as :class:`.Session.add`
+        take place here.   Attribute changes on objects that were
+        already flushed will be discarded, and changes to the flush
+        plan will also not take place.  Use :meth:`.Session.before_flush`
+        to change the flush plan on flush.
+        
         :param mapper: the :class:`.Mapper` which is the target
          of this event.
         :param connection: the :class:`.Connection` being used to 
@@ -689,6 +697,14 @@ class MapperEvents(event.Events):
         (and more poorly performing) event->persist->event
         steps.
 
+        Handlers should **not** alter mapped attributes on the objects
+        just flushed or on other objects of the same class, nor
+        should any other ORM-based operation such as :class:`.Session.add`
+        take place here.   Attribute changes on objects that were
+        already flushed will be discarded, and changes to the flush
+        plan will also not take place.  Use :meth:`.Session.before_flush`
+        to change the flush plan on flush.
+
         :param mapper: the :class:`.Mapper` which is the target
          of this event.
         :param connection: the :class:`.Connection` being used to 
@@ -749,6 +765,14 @@ class MapperEvents(event.Events):
         same class after their DELETE statements have been emitted at
         once in a previous step. 
 
+        Handlers should **not** alter mapped attributes on the objects
+        just flushed or on other objects of the same class, nor
+        should any other ORM-based operation such as :class:`.Session.add`
+        take place here.   Attribute changes on objects that were
+        already flushed will be discarded, and changes to the flush
+        plan will also not take place.  Use :meth:`.Session.before_flush`
+        to change the flush plan on flush.
+
         :param mapper: the :class:`.Mapper` which is the target
          of this event.
         :param connection: the :class:`.Connection` being used to