- add before_attach event, [ticket:2464]

2 files changed, 41 insertions, 5 deletions

diff --git a/lib/sqlalchemy/orm/events.py b/lib/sqlalchemy/orm/events.py
index d319a3bbb..903b7fadd 100644
--- a/lib/sqlalchemy/orm/events.py
+++ b/lib/sqlalchemy/orm/events.py
@@ -1061,10 +1061,36 @@ class SessionEvents(event.Events):
         
         """
 
+    def before_attach(self, session, instance):
+        """Execute before an instance is attached to a session.
+
+        This is called before an add, delete or merge causes
+        the object to be part of the session.
+        
+        .. versionadded:: 0.8.  Note that :meth:`.after_attach` now 
+           fires off after the item is part of the session.  
+           :meth:`.before_attach` is provided for those cases where
+           the item should not yet be part of the session state.
+           
+        """
+
     def after_attach(self, session, instance):
         """Execute after an instance is attached to a session.
 
-        This is called after an add, delete or merge. """
+        This is called after an add, delete or merge. 
+        
+        .. note::
+           
+           As of 0.8, this event fires off *after* the item
+           has been fully associated with the session, which is
+           different than previous releases.  For event
+           handlers that require the object not yet 
+           be part of session state (such as handlers which
+           may autoflush while the target object is not
+           yet complete) consider the
+           new :meth:`.before_attach` event.
+           
+        """
 
     def after_bulk_update( self, session, query, query_context, result):
         """Execute after a bulk update operation to the session.
diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py
index 40e4375ed..7f820aa05 100644
--- a/lib/sqlalchemy/orm/session.py
+++ b/lib/sqlalchemy/orm/session.py
@@ -1300,7 +1300,7 @@ class Session(object):
         # ensure object is attached to allow the 
         # cascade operation to load deferred attributes
         # and collections
-        self._attach(state)
+        self._attach(state, include_before=True)
 
         # grab the cascades before adding the item to the deleted list
         # so that autoflush does not delete the item
@@ -1472,6 +1472,7 @@ class Session(object):
                 "Object '%s' already has an identity - it can't be registered "
                 "as pending" % mapperutil.state_str(state))
 
+        self._before_attach(state)
         if state not in self._new:
             self._new[state] = state.obj()
             state.insert_order = len(self._new)
@@ -1493,6 +1494,7 @@ class Session(object):
                 "function to send this object back to the transient state." %
                 mapperutil.state_str(state)
             )
+        self._before_attach(state)
         self._deleted.pop(state, None)
         self.identity_map.add(state)
         self._attach(state)
@@ -1510,7 +1512,7 @@ class Session(object):
         if state.key is None:
             return
 
-        self._attach(state)
+        self._attach(state, include_before=True)
         self._deleted[state] = state.obj()
         self.identity_map.add(state)
 
@@ -1555,10 +1557,15 @@ class Session(object):
         
         """
         state = attributes.instance_state(obj)
-        self._attach(state)
+        self._attach(state, include_before=True)
         state._load_pending = True
 
-    def _attach(self, state):
+    def _before_attach(self, state):
+        if state.session_id != self.hash_key and \
+            self.dispatch.before_attach:
+            self.dispatch.before_attach(self, state.obj())
+
+    def _attach(self, state, include_before=False):
         if state.key and \
             state.key in self.identity_map and \
             not self.identity_map.contains_state(state):
@@ -1576,6 +1583,9 @@ class Session(object):
                                     state.session_id, self.hash_key))
 
         if state.session_id != self.hash_key:
+            if include_before and \
+                self.dispatch.before_attach:
+                self.dispatch.before_attach(self, state.obj())
             state.session_id = self.hash_key
             if self.dispatch.after_attach:
                 self.dispatch.after_attach(self, state.obj())