From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Thu, 25 Aug 2011 12:53:32 +0000 (-0400)
Subject: add more discouragment from using before_/after_ mapper events for anything ORM-heavy
X-Git-Tag: rel_0_7_3~63
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=439f2813e00de00aefb0905bbf52337f7ddcc7d3;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

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 a8162fa723..913d764dac 100644
--- 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