document identity_map

2 files changed, 20 insertions, 0 deletions

diff --git a/doc/build/orm/session.rst b/doc/build/orm/session.rst
index 298f2ea29..4bb1738ba 100644
--- a/doc/build/orm/session.rst
+++ b/doc/build/orm/session.rst
@@ -890,6 +890,13 @@ all objects which have had changes since they were last loaded or saved (i.e.
     # persistent objects that have been marked as deleted via session.delete(obj)
     session.deleted
 
+    # dictionary of all persistent objects, keyed on their
+    # identity key
+    session.identity_map
+
+(Documentation: :attr:`.Session.new`, :attr:`.Session.dirty`, 
+:attr:`.Session.deleted`, :attr:`.Session.identity_map`).
+
 Note that objects within the session are by default *weakly referenced*. This
 means that when they are dereferenced in the outside application, they fall
 out of scope from within the :class:`~sqlalchemy.orm.session.Session` as well
diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py
index 4299290d0..ba6ceaeec 100644
--- a/lib/sqlalchemy/orm/session.py
+++ b/lib/sqlalchemy/orm/session.py
@@ -1772,6 +1772,19 @@ class Session(object):
 
         return self.transaction and self.transaction.is_active
 
+    identity_map = None
+    """A mapping of object identities to objects themselves.
+    
+    Iterating through ``Session.identity_map.values()`` provides
+    access to the full set of persistent objects (i.e., those 
+    that have row identity) currently in the session.
+    
+    See also:
+    
+    :func:`.identity_key` - operations involving identity keys.
+    
+    """
+
     @property
     def _dirty_states(self):
         """The set of all persistent states considered dirty.