- The :class:`.SessionEvents` suite now includes events to allowticket_2677

unambiguous tracking of all object lifecycle state transitions
in terms of the :class:`.Session` itself, e.g. pending,
transient,  persistent, detached.   The state of the object
within each event is also defined.
fixes #2677
- Added a new session lifecycle state :term:`deleted`.  This new state
represents an object that has been deleted from the :term:`persistent`
state and will move to the :term:`detached` state once the transaction
is committed.  This resolves the long-standing issue that objects
which were deleted existed in a gray area between persistent and
detached.   The :attr:`.InstanceState.persistent` accessor will
**no longer** report on a deleted object as persistent; the
:attr:`.InstanceState.deleted` accessor will instead be True for
these objects, until they become detached.
- The :paramref:`.Session.weak_identity_map` parameter is deprecated.
See the new recipe at :ref:`session_referencing_behavior` for
an event-based approach to maintaining strong identity map behavior.
references #3517

6 files changed, 510 insertions, 141 deletions

diff --git a/lib/sqlalchemy/orm/events.py b/lib/sqlalchemy/orm/events.py
index 29bdbaa8c..993385e15 100644
--- a/lib/sqlalchemy/orm/events.py
+++ b/lib/sqlalchemy/orm/events.py
@@ -316,6 +316,8 @@ class InstanceEvents(event.Events):
 
             :meth:`.InstanceEvents.refresh`
 
+            :meth:`.SessionEvents.loaded_as_persistent`
+
         """
 
     def refresh(self, target, context, attrs):
@@ -1510,6 +1512,244 @@ class SessionEvents(event.Events):
 
         """
 
+    def transient_to_pending(self, session, instance):
+        """Intercept the "transient to pending" transition for a specific object.
+
+        This event is a specialization of the
+        :meth:`.SessionEvents.after_attach` event which is only invoked
+        for this specific transition.  It is invoked typically during the
+        :meth:`.Session.add` call.
+
+        :param session: target :class:`.Session`
+
+        :param instance: the ORM-mapped instance being operated upon.
+
+        .. versionadded:: 1.1
+
+        .. seealso::
+
+            :ref:`session_lifecycle_events`
+
+        """
+
+    def pending_to_transient(self, session, instance):
+        """Intercept the "pending to transient" transition for a specific object.
+
+        This less common transition occurs when an pending object that has
+        not been flushed is evicted from the session; this can occur
+        when the :meth:`.Session.rollback` method rolls back the transaction,
+        or when the :meth:`.Session.expunge` method is used.
+
+        :param session: target :class:`.Session`
+
+        :param instance: the ORM-mapped instance being operated upon.
+
+        .. versionadded:: 1.1
+
+        .. seealso::
+
+            :ref:`session_lifecycle_events`
+
+        """
+
+    def persistent_to_transient(self, session, instance):
+        """Intercept the "persistent to transient" transition for a specific object.
+
+        This less common transition occurs when an pending object that has
+        has been flushed is evicted from the session; this can occur
+        when the :meth:`.Session.rollback` method rolls back the transaction.
+
+        :param session: target :class:`.Session`
+
+        :param instance: the ORM-mapped instance being operated upon.
+
+        .. versionadded:: 1.1
+
+        .. seealso::
+
+            :ref:`session_lifecycle_events`
+
+        """
+
+    def pending_to_persistent(self, session, instance):
+        """Intercept the "pending to persistent"" transition for a specific object.
+
+        This event is invoked within the flush process, and is
+        similar to scanning the :attr:`.Session.new` collection within
+        the :meth:`.SessionEvents.after_flush` event.  However, in this
+        case the object has already been moved to the persistent state
+        when the event is called.
+
+        :param session: target :class:`.Session`
+
+        :param instance: the ORM-mapped instance being operated upon.
+
+        .. versionadded:: 1.1
+
+        .. seealso::
+
+            :ref:`session_lifecycle_events`
+
+        """
+
+    def detached_to_persistent(self, session, instance):
+        """Intercept the "detached to persistent" transition for a specific object.
+
+        This event is a specialization of the
+        :meth:`.SessionEvents.after_attach` event which is only invoked
+        for this specific transition.  It is invoked typically during the
+        :meth:`.Session.add` call, as well as during the
+        :meth:`.Session.delete` call if the object was not previously
+        associated with the
+        :class:`.Session` (note that an object marked as "deleted" remains
+        in the "persistent" state until the flush proceeds).
+
+        .. note::
+
+            If the object becomes persistent as part of a call to
+            :meth:`.Session.delete`, the object is **not** yet marked as
+            deleted when this event is called.  To detect deleted objects,
+            check the ``deleted`` flag sent to the
+            :meth:`.SessionEvents.persistent_to_detached` to event after the
+            flush proceeds, or check the :attr:`.Session.deleted` collection
+            within the :meth:`.SessionEvents.before_flush` event if deleted
+            objects need to be intercepted before the flush.
+
+        :param session: target :class:`.Session`
+
+        :param instance: the ORM-mapped instance being operated upon.
+
+        .. versionadded:: 1.1
+
+        .. seealso::
+
+            :ref:`session_lifecycle_events`
+
+        """
+
+    def loaded_as_persistent(self, session, instance):
+        """Intercept the "loaded as peristent" transition for a specific object.
+
+        This event is invoked within the ORM loading process, and is invoked
+        very similarly to the :meth:`.InstanceEvents.load` event.  However,
+        the event here is linkable to a :class:`.Session` class or instance,
+        rather than to a mapper or class hierarchy, and integrates
+        with the other session lifecycle events smoothly.  The object
+        is guaranteed to be present in the session's identity map when
+        this event is called.
+
+
+        :param session: target :class:`.Session`
+
+        :param instance: the ORM-mapped instance being operated upon.
+
+        .. versionadded:: 1.1
+
+        .. seealso::
+
+            :ref:`session_lifecycle_events`
+
+        """
+
+    def persistent_to_deleted(self, session, instance):
+        """Intercept the "persistent to deleted" transition for a specific object.
+
+        This event is invoked when a persistent object's identity
+        is deleted from the database within a flush, however the object
+        still remains associated with the :class:`.Session` until the
+        transaction completes.
+
+        If the transaction is rolled back, the object moves again
+        to the persistent state, and the
+        :meth:`.SessionEvents.deleted_to_persistent` event is called.
+        If the transaction is committed, the object becomes detached,
+        which will emit the :meth:`.SessionEvents.deleted_to_detached`
+        event.
+
+        Note that while the :meth:`.Session.delete` method is the primary
+        public interface to mark an object as deleted, many objects
+        get deleted due to cascade rules, which are not always determined
+        until flush time.  Therefore, there's no way to catch
+        every object that will be deleted until the flush has proceeded.
+        the :meth:`.SessionEvents.persistent_to_deleted` event is therefore
+        invoked at the end of a flush.
+
+        .. versionadded:: 1.1
+
+        .. seealso::
+
+            :ref:`session_lifecycle_events`
+
+        """
+
+    def deleted_to_persistent(self, session, instance):
+        """Intercept the "deleted to persistent" transition for a specific object.
+
+        This transition occurs only when an object that's been deleted
+        successfully in a flush is restored due to a call to
+        :meth:`.Session.rollback`.   The event is not called under
+        any other circumstances.
+
+        .. versionadded:: 1.1
+
+        .. seealso::
+
+            :ref:`session_lifecycle_events`
+
+        """
+
+    def deleted_to_detached(self, session, instance):
+        """Intercept the "deleted to detached" transition for a specific object.
+
+        This event is invoked when a deleted object is evicted
+        from the session.   The typical case when this occurs is when
+        the transaction for a :class:`.Session` in which the object
+        was deleted is committed; the object moves from the deleted
+        state to the detached state.
+
+        It is also invoked for objects that were deleted in a flush
+        when the :meth:`.Session.expunge_all` or :meth:`.Session.close`
+        events are called, as well as if the object is individually
+        expunged from its deleted state via :meth:`.Session.expunge`.
+
+        .. versionadded:: 1.1
+
+        .. seealso::
+
+            :ref:`session_lifecycle_events`
+
+        """
+
+    def persistent_to_detached(self, session, instance):
+        """Intercept the "persistent to detached" transition for a specific object.
+
+        This event is invoked when a persistent object is evicted
+        from the session.  There are many conditions that cause this
+        to happen, including:
+
+        * using a method such as :meth:`.Session.expunge`
+          or :meth:`.Session.close`
+
+        * Calling the :meth:`.Session.rollback` method, when the object
+          was part of an INSERT statement for that session's transaction
+
+
+        :param session: target :class:`.Session`
+
+        :param instance: the ORM-mapped instance being operated upon.
+
+        :param deleted: boolean.  If True, indicates this object moved
+         to the detached state because it was marked as deleted and flushed.
+
+
+        .. versionadded:: 1.1
+
+        .. seealso::
+
+            :ref:`session_lifecycle_events`
+
+        """
+
 
 class AttributeEvents(event.Events):
     """Define events for object attributes.
diff --git a/lib/sqlalchemy/orm/identity.py b/lib/sqlalchemy/orm/identity.py
index b42703855..2dfe3fd5c 100644
--- a/lib/sqlalchemy/orm/identity.py
+++ b/lib/sqlalchemy/orm/identity.py
@@ -8,7 +8,8 @@
 import weakref
 from . import attributes
 from .. import util
-
+from .. import exc as sa_exc
+from . import util as orm_util
 
 class IdentityMap(object):
     def __init__(self):
@@ -126,16 +127,18 @@ class WeakInstanceDict(IdentityMap):
                 if existing_state is not state:
                     o = existing_state.obj()
                     if o is not None:
-                        raise AssertionError(
-                            "A conflicting state is already "
-                            "present in the identity map for key %r"
-                            % (key, ))
+                        raise sa_exc.InvalidRequestError(
+                            "Can't attach instance "
+                            "%s; another instance with key %s is already "
+                            "present in this session." % (
+                                orm_util.state_str(state), state.key))
                 else:
-                    return
+                    return False
             except KeyError:
                 pass
         self._dict[key] = state
         self._manage_incoming_state(state)
+        return True
 
     def _add_unpresent(self, state, key):
         # inlined form of add() called by loading.py
@@ -210,13 +213,13 @@ class WeakInstanceDict(IdentityMap):
 class StrongInstanceDict(IdentityMap):
     """A 'strong-referencing' version of the identity map.
 
-    .. deprecated:: this object is present in order to fulfill
-       the ``weak_identity_map=False`` option of the Session.
-       This option is present to allow compatibility with older applications,
-       but it is recommended that strong references to objects
-       be maintained by the calling application
-       externally to the :class:`.Session` itself, to the degree
-       that is needed by the application.
+    .. deprecated 1.1::
+        The strong
+        reference identity map is legacy.  See the
+        recipe at :ref:`session_referencing_behavior` for
+        an event-based approach to maintaining strong identity
+        references.
+
 
     """
 
@@ -268,12 +271,16 @@ class StrongInstanceDict(IdentityMap):
     def add(self, state):
         if state.key in self:
             if attributes.instance_state(self._dict[state.key]) is not state:
-                raise AssertionError('A conflicting state is already '
-                                     'present in the identity map for key %r'
-                                     % (state.key, ))
+                raise sa_exc.InvalidRequestError(
+                    "Can't attach instance "
+                    "%s; another instance with key %s is already "
+                    "present in this session." % (
+                        orm_util.state_str(state), state.key))
+            return False
         else:
             self._dict[state.key] = state.obj()
             self._manage_incoming_state(state)
+            return True
 
     def _add_unpresent(self, state, key):
         # inlined form of add() called by loading.py
diff --git a/lib/sqlalchemy/orm/loading.py b/lib/sqlalchemy/orm/loading.py
index d8bf662fc..c90308a69 100644
--- a/lib/sqlalchemy/orm/loading.py
+++ b/lib/sqlalchemy/orm/loading.py
@@ -339,6 +339,9 @@ def _instance_processor(
     populate_existing = context.populate_existing or mapper.always_refresh
     load_evt = bool(mapper.class_manager.dispatch.load)
     refresh_evt = bool(mapper.class_manager.dispatch.refresh)
+    persistent_evt = bool(context.session.dispatch.loaded_as_persistent)
+    if persistent_evt:
+        loaded_as_persistent = context.session.dispatch.loaded_as_persistent
     instance_state = attributes.instance_state
     instance_dict = attributes.instance_dict
     session_id = context.session.hash_key
@@ -432,8 +435,11 @@ def _instance_processor(
                 loaded_instance, populate_existing, populators)
 
             if isnew:
-                if loaded_instance and load_evt:
-                    state.manager.dispatch.load(state, context)
+                if loaded_instance:
+                    if load_evt:
+                        state.manager.dispatch.load(state, context)
+                    if persistent_evt:
+                        loaded_as_persistent(context.session, state.obj())
                 elif refresh_evt:
                     state.manager.dispatch.refresh(
                         state, context, only_load_props)
diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py
index 6c3f392ba..96a24067e 100644
--- a/lib/sqlalchemy/orm/session.py
+++ b/lib/sqlalchemy/orm/session.py
@@ -272,10 +272,9 @@ class SessionTransaction(object):
     def _restore_snapshot(self, dirty_only=False):
         assert self._is_transaction_boundary
 
-        for s in set(self._new).union(self.session._new):
-            self.session._expunge_state(s)
-            if s.key:
-                del s.key
+        self.session._expunge_states(
+            set(self._new).union(self.session._new),
+            to_transient=True)
 
         for s, (oldkey, newkey) in self._key_switches.items():
             self.session.identity_map.safe_discard(s)
@@ -283,10 +282,7 @@ class SessionTransaction(object):
             self.session.identity_map.replace(s)
 
         for s in set(self._deleted).union(self.session._deleted):
-            if s.deleted:
-                # assert s in self._deleted
-                del s.deleted
-            self.session._update_impl(s, discard_existing=True)
+            self.session._update_impl(s, revert_deletion=True)
 
         assert not self.session._deleted
 
@@ -300,8 +296,9 @@ class SessionTransaction(object):
         if not self.nested and self.session.expire_on_commit:
             for s in self.session.identity_map.all_states():
                 s._expire(s.dict, self.session.identity_map._modified)
-            for s in list(self._deleted):
-                s._detach()
+
+            statelib.InstanceState._detach_states(
+                list(self._deleted), self.session)
             self._deleted.clear()
         elif self.nested:
             self._parent._new.update(self._new)
@@ -629,12 +626,11 @@ class Session(_SessionClassMethods):
         :param weak_identity_map:  Defaults to ``True`` - when set to
            ``False``, objects placed in the :class:`.Session` will be
            strongly referenced until explicitly removed or the
-           :class:`.Session` is closed.  **Deprecated** - this option
-           is present to allow compatibility with older applications, but
-           it is recommended that strong references to objects
-           be maintained by the calling application
-           externally to the :class:`.Session` itself,
-           to the extent that is required by the application.
+           :class:`.Session` is closed.  **Deprecated** - The strong
+           reference identity map is legacy.  See the
+           recipe at :ref:`session_referencing_behavior` for
+           an event-based approach to maintaining strong identity
+           references.
 
         """
 
@@ -643,12 +639,9 @@ class Session(_SessionClassMethods):
         else:
             util.warn_deprecated(
                 "weak_identity_map=False is deprecated.  "
-                "It is present to allow compatibility with older "
-                "applications, but "
-                "it is recommended that strong references to "
-                "objects be maintained by the calling application "
-                "externally to the :class:`.Session` itself, "
-                "to the extent that is required by the application.")
+                "See the documentation on 'Session Referencing Behavior' "
+                "for an event-based approach to maintaining strong identity "
+                "references.")
 
             self._identity_cls = identity.StrongInstanceDict
         self.identity_map = self._identity_cls()
@@ -1097,16 +1090,15 @@ class Session(_SessionClassMethods):
         ``Session``.
 
         """
-        for state in self.identity_map.all_states() + list(self._new):
-            state._detach()
 
+        all_states = self.identity_map.all_states() + list(self._new)
         self.identity_map = self._identity_cls()
         self._new = {}
         self._deleted = {}
 
-    # TODO: need much more test coverage for bind_mapper() and similar !
-    # TODO: + crystallize + document resolution order
-    #       vis. bind_mapper/bind_table
+        statelib.InstanceState._detach_states(
+            all_states, self
+        )
 
     def _add_bind(self, key, bind):
         try:
@@ -1448,7 +1440,7 @@ class Session(_SessionClassMethods):
             state._expire(state.dict, self.identity_map._modified)
         elif state in self._new:
             self._new.pop(state)
-            state._detach()
+            state._detach(self)
 
     @util.deprecated("0.7", "The non-weak-referencing identity map "
                      "feature is no longer needed.")
@@ -1483,23 +1475,26 @@ class Session(_SessionClassMethods):
 
         cascaded = list(state.manager.mapper.cascade_iterator(
             'expunge', state))
-        self._expunge_state(state)
-        for o, m, st_, dct_ in cascaded:
-            self._expunge_state(st_)
+        self._expunge_states(
+            [state] + [st_ for o, m, st_, dct_ in cascaded]
+        )
 
-    def _expunge_state(self, state):
-        if state in self._new:
-            self._new.pop(state)
-            state._detach()
-        elif self.identity_map.contains_state(state):
-            self.identity_map.safe_discard(state)
-            self._deleted.pop(state, None)
-            state._detach()
-        elif self.transaction:
-            self.transaction._deleted.pop(state, None)
-            state._detach()
+    def _expunge_states(self, states, to_transient=False):
+        for state in states:
+            if state in self._new:
+                self._new.pop(state)
+            elif self.identity_map.contains_state(state):
+                self.identity_map.safe_discard(state)
+                self._deleted.pop(state, None)
+            elif self.transaction:
+                # state is "detached" from being deleted, but still present
+                # in the transaction snapshot
+                self.transaction._deleted.pop(state, None)
+        statelib.InstanceState._detach_states(
+            states, self, to_transient=to_transient)
 
     def _register_newly_persistent(self, states):
+        pending_to_persistent = self.dispatch.pending_to_persistent or None
         for state in states:
             mapper = _state_mapper(state)
 
@@ -1546,6 +1541,11 @@ class Session(_SessionClassMethods):
         )
 
         self._register_altered(states)
+
+        if pending_to_persistent is not None:
+            for state in states:
+                pending_to_persistent(self, state.obj())
+
         # remove from new last, might be the last strong ref
         for state in set(states).intersection(self._new):
             self._new.pop(state)
@@ -1559,13 +1559,19 @@ class Session(_SessionClassMethods):
                     self.transaction._dirty[state] = True
 
     def _remove_newly_deleted(self, states):
+        persistent_to_deleted = self.dispatch.persistent_to_deleted or None
         for state in states:
             if self._enable_transaction_accounting and self.transaction:
                 self.transaction._deleted[state] = True
 
             self.identity_map.safe_discard(state)
             self._deleted.pop(state, None)
-            state.deleted = True
+            state._deleted = True
+            # can't call state._detach() here, because this state
+            # is still in the transaction snapshot and needs to be
+            # tracked as part of that
+            if persistent_to_deleted is not None:
+                persistent_to_deleted(self, state.obj())
 
     def add(self, instance, _warn=True):
         """Place an object in the ``Session``.
@@ -1620,30 +1626,39 @@ class Session(_SessionClassMethods):
         except exc.NO_STATE:
             raise exc.UnmappedInstanceError(instance)
 
+        self._delete_impl(state, head=True)
+
+    def _delete_impl(self, state, head):
+
         if state.key is None:
-            raise sa_exc.InvalidRequestError(
-                "Instance '%s' is not persisted" %
-                state_str(state))
+            if head:
+                raise sa_exc.InvalidRequestError(
+                    "Instance '%s' is not persisted" %
+                    state_str(state))
+            else:
+                return
+
+        to_attach = self._before_attach(state)
 
         if state in self._deleted:
             return
 
-        # ensure object is attached to allow the
-        # cascade operation to load deferred attributes
-        # and collections
-        self._attach(state, include_before=True)
+        if to_attach:
+            self.identity_map.add(state)
+            self._after_attach(state)
 
-        # grab the cascades before adding the item to the deleted list
-        # so that autoflush does not delete the item
-        # the strong reference to the instance itself is significant here
-        cascade_states = list(state.manager.mapper.cascade_iterator(
-            'delete', state))
+        if head:
+            # grab the cascades before adding the item to the deleted list
+            # so that autoflush does not delete the item
+            # the strong reference to the instance itself is significant here
+            cascade_states = list(state.manager.mapper.cascade_iterator(
+                'delete', state))
 
         self._deleted[state] = state.obj()
-        self.identity_map.add(state)
 
-        for o, m, st_, dct_ in cascade_states:
-            self._delete_impl(st_)
+        if head:
+            for o, m, st_, dct_ in cascade_states:
+                self._delete_impl(st_, False)
 
     def merge(self, instance, load=True):
         """Copy the state of a given instance into a corresponding instance
@@ -1820,35 +1835,46 @@ class Session(_SessionClassMethods):
                 "Object '%s' already has an identity - "
                 "it can't be registered as pending" % state_str(state))
 
-        self._before_attach(state)
+        to_attach = self._before_attach(state)
         if state not in self._new:
             self._new[state] = state.obj()
             state.insert_order = len(self._new)
-        self._attach(state)
-
-    def _update_impl(self, state, discard_existing=False):
-        if (self.identity_map.contains_state(state) and
-                state not in self._deleted):
-            return
+        if to_attach:
+            self._after_attach(state)
 
+    def _update_impl(self, state, revert_deletion=False):
         if state.key is None:
             raise sa_exc.InvalidRequestError(
                 "Instance '%s' is not persisted" %
                 state_str(state))
 
-        if state.deleted:
-            raise sa_exc.InvalidRequestError(
-                "Instance '%s' has been deleted.  Use the make_transient() "
-                "function to send this object back to the transient state." %
-                state_str(state)
-            )
-        self._before_attach(state, check_identity_map=False)
+        if state._deleted:
+            if revert_deletion:
+                if not state._attached:
+                    return
+                del state._deleted
+            else:
+                raise sa_exc.InvalidRequestError(
+                    "Instance '%s' has been deleted.  "
+                    "Use the make_transient() "
+                    "function to send this object back "
+                    "to the transient state." %
+                    state_str(state)
+                )
+
+        to_attach = self._before_attach(state)
+
+
         self._deleted.pop(state, None)
-        if discard_existing:
+        if revert_deletion:
             self.identity_map.replace(state)
         else:
             self.identity_map.add(state)
-        self._attach(state)
+
+        if to_attach:
+            self._after_attach(state)
+        elif revert_deletion and self.dispatch.deleted_to_persistent:
+            self.dispatch.deleted_to_persistent(self, state.obj())
 
     def _save_or_update_impl(self, state):
         if state.key is None:
@@ -1856,17 +1882,6 @@ class Session(_SessionClassMethods):
         else:
             self._update_impl(state)
 
-    def _delete_impl(self, state):
-        if state in self._deleted:
-            return
-
-        if state.key is None:
-            return
-
-        self._attach(state, include_before=True)
-        self._deleted[state] = state.obj()
-        self.identity_map.add(state)
-
     def enable_relationship_loading(self, obj):
         """Associate an object with this :class:`.Session` for related
         object loading.
@@ -1919,40 +1934,36 @@ class Session(_SessionClassMethods):
 
         """
         state = attributes.instance_state(obj)
-        self._attach(state, include_before=True)
+        to_attach = self._before_attach(state)
         state._load_pending = True
+        if to_attach:
+            self._after_attach(state)
 
-    def _before_attach(self, state, check_identity_map=True):
-        if state.session_id != self.hash_key and \
-                self.dispatch.before_attach:
-            self.dispatch.before_attach(self, state.obj())
-
-        if check_identity_map and state.key and \
-            state.key in self.identity_map and \
-                not self.identity_map.contains_state(state):
-            raise sa_exc.InvalidRequestError(
-                "Can't attach instance "
-                "%s; another instance with key %s is already "
-                "present in this session." % (state_str(state), state.key))
+    def _before_attach(self, state):
+        if state.session_id == self.hash_key:
+            return False
 
-        if state.session_id and \
-                state.session_id is not self.hash_key and \
-                state.session_id in _sessions:
+        if state.session_id and state.session_id in _sessions:
             raise sa_exc.InvalidRequestError(
                 "Object '%s' is already attached to session '%s' "
                 "(this is '%s')" % (state_str(state),
                                     state.session_id, self.hash_key))
 
-    def _attach(self, state, include_before=False):
+        if self.dispatch.before_attach:
+            self.dispatch.before_attach(self, state.obj())
+
+        return True
 
-        if state.session_id != self.hash_key:
-            if include_before:
-                self._before_attach(state)
-            state.session_id = self.hash_key
-            if state.modified and state._strong_obj is None:
-                state._strong_obj = state.obj()
-            if self.dispatch.after_attach:
-                self.dispatch.after_attach(self, state.obj())
+    def _after_attach(self, state):
+        state.session_id = self.hash_key
+        if state.modified and state._strong_obj is None:
+            state._strong_obj = state.obj()
+        if self.dispatch.after_attach:
+            self.dispatch.after_attach(self, state.obj())
+        if state.persistent and self.dispatch.detached_to_persistent:
+            self.dispatch.detached_to_persistent(self, state.obj())
+        elif state.pending and self.dispatch.transient_to_pending:
+            self.dispatch.transient_to_pending(self, state.obj())
 
     def __contains__(self, instance):
         """Return True if the instance is associated with this session.
@@ -2711,7 +2722,7 @@ def make_transient(instance):
     state = attributes.instance_state(instance)
     s = _state_session(state)
     if s:
-        s._expunge_state(state)
+        s._expunge_states([state])
 
     # remove expired state
     state.expired_attributes.clear()
@@ -2722,8 +2733,8 @@ def make_transient(instance):
 
     if state.key:
         del state.key
-    if state.deleted:
-        del state.deleted
+    if state._deleted:
+        del state._deleted
 
 
 def make_transient_to_detached(instance):
@@ -2755,8 +2766,8 @@ def make_transient_to_detached(instance):
         raise sa_exc.InvalidRequestError(
             "Given object must be transient")
     state.key = state.mapper._identity_key_from_state(state)
-    if state.deleted:
-        del state.deleted
+    if state._deleted:
+        del state._deleted
     state._commit_all(state.dict)
     state._expire_attributes(state.dict, state.unloaded)
 
diff --git a/lib/sqlalchemy/orm/state.py b/lib/sqlalchemy/orm/state.py
index 6c9f07bff..9f1190339 100644
--- a/lib/sqlalchemy/orm/state.py
+++ b/lib/sqlalchemy/orm/state.py
@@ -58,7 +58,7 @@ class InstanceState(interfaces.InspectionAttr):
     _strong_obj = None
     modified = False
     expired = False
-    deleted = False
+    _deleted = False
     _load_pending = False
     is_instance = True
 
@@ -89,7 +89,6 @@ class InstanceState(interfaces.InspectionAttr):
        see also the ``unmodified`` collection which is intersected
        against this set when a refresh operation occurs."""
 
-
     @util.memoized_property
     def attrs(self):
         """Return a namespace representing each attribute on
@@ -135,16 +134,80 @@ class InstanceState(interfaces.InspectionAttr):
             self._attached
 
     @property
+    def deleted(self):
+        """Return true if the object is :term:`deleted`.
+
+        An object that is in the deleted state is guaranteed to
+        not be within the :attr:`.Session.identity_map` of its parent
+        :class:`.Session`; however if the session's transaction is rolled
+        back, the object will be restored to the persistent state and
+        the identity map.
+
+        .. note::
+
+            The :attr:`.InstanceState.deleted` attribute refers to a specific
+            state of the object that occurs between the "persistent" and
+            "detached" states; once the object is :term:`detached`, the
+            :attr:`.InstanceState.deleted` attribute **no longer returns
+            True**; in order to detect that a state was deleted, regardless
+            of whether or not the object is associated with a :class:`.Session`,
+            use the :attr:`.InstanceState.was_deleted` accessor.
+
+        .. versionadded: 1.1
+
+        .. seealso::
+
+            :ref:`session_object_states`
+
+        """
+        return self.key is not None and \
+            self._attached and self._deleted
+
+    @property
+    def was_deleted(self):
+        """Return True if this object is or was previously in the
+        "deleted" state and has not been reverted to persistent.
+
+        This flag returns True once the object was deleted in flush.
+        When the object is expunged from the session either explicitly
+        or via transaction commit and enters the "detached" state,
+        this flag will continue to report True.
+
+        .. versionadded:: 1.1 - added a local method form of
+           :func:`.orm.util.was_deleted`.
+
+        .. seealso::
+
+            :attr:`.InstanceState.deleted` - refers to the "deleted" state
+
+            :func:`.orm.util.was_deleted` - standalone function
+
+            :ref:`session_object_states`
+
+        """
+        return self._deleted
+
+    @property
     def persistent(self):
         """Return true if the object is :term:`persistent`.
 
+        An object that is in the persistent state is guaranteed to
+        be within the :attr:`.Session.identity_map` of its parent
+        :class:`.Session`.
+
+        .. versionchanged:: 1.1 The :attr:`.InstanceState.persistent`
+           accessor no longer returns True for an object that was
+           "deleted" within a flush; use the :attr:`.InstanceState.deleted`
+           accessor to detect this state.   This allows the "persistent"
+           state to guarantee membership in the identity map.
+
         .. seealso::
 
             :ref:`session_object_states`
 
             """
         return self.key is not None and \
-            self._attached
+            self._attached and not self._deleted
 
     @property
     def detached(self):
@@ -155,8 +218,7 @@ class InstanceState(interfaces.InspectionAttr):
             :ref:`session_object_states`
 
         """
-        return self.key is not None and \
-            not self._attached
+        return self.key is not None and not self._attached
 
     @property
     @util.dependencies("sqlalchemy.orm.session")
@@ -243,8 +305,44 @@ class InstanceState(interfaces.InspectionAttr):
         """
         return bool(self.key)
 
-    def _detach(self):
-        self.session_id = self._strong_obj = None
+    @classmethod
+    def _detach_states(self, states, session, to_transient=False):
+        persistent_to_detached = \
+            session.dispatch.persistent_to_detached or None
+        deleted_to_detached = \
+            session.dispatch.deleted_to_detached or None
+        pending_to_transient = \
+            session.dispatch.pending_to_transient or None
+        persistent_to_transient = \
+            session.dispatch.persistent_to_transient or None
+
+        for state in states:
+            deleted = state._deleted
+            persistent = state.key is not None and not deleted
+            pending = state.key is None
+
+            state.session_id = None
+
+            if to_transient and state.key:
+                del state.key
+            if persistent:
+                if to_transient:
+                    if persistent_to_transient is not None:
+                        persistent_to_transient(session, state.obj())
+                elif persistent_to_detached is not None:
+                    persistent_to_detached(session, state.obj())
+            elif deleted and deleted_to_detached is not None:
+                deleted_to_detached(session, state.obj())
+            elif pending and pending_to_transient is not None:
+                pending_to_transient(session, state.obj())
+
+            state._strong_obj = None
+
+    def _detach(self, session=None):
+        if session:
+            InstanceState._detach_states([self], session)
+        else:
+            self.session_id = self._strong_obj = None
 
     def _dispose(self):
         self._detach()
diff --git a/lib/sqlalchemy/orm/util.py b/lib/sqlalchemy/orm/util.py
index 6d3869679..4351c8dc6 100644
--- a/lib/sqlalchemy/orm/util.py
+++ b/lib/sqlalchemy/orm/util.py
@@ -985,12 +985,19 @@ def was_deleted(object):
     """Return True if the given object was deleted
     within a session flush.
 
+    This is regardless of whether or not the object is
+    persistent or detached.
+
     .. versionadded:: 0.8.0
 
+    .. seealso::
+
+        :attr:`.InstanceState.was_deleted`
+
     """
 
     state = attributes.instance_state(object)
-    return state.deleted
+    return state.was_deleted
 
 
 def randomize_unitofwork():