From 439f2813e00de00aefb0905bbf52337f7ddcc7d3 Mon Sep 17 00:00:00 2001
From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Thu, 25 Aug 2011 08:53:32 -0400
Subject: [PATCH] add more discouragment from using before_/after_ mapper
 events for anything ORM-heavy

---
 lib/sqlalchemy/orm/events.py | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

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 
-- 
2.47.3