From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Sun, 19 Oct 2014 20:56:18 +0000 (-0400)
Subject: - repair documenation for object_session(), returns None if no
X-Git-Tag: rel_0_9_9~84
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=de8754faf9a13b1c5dfb0c114e22ae8b49363a8c;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

- repair documenation for object_session(), returns None if no
session, and refer to InstanceState.session.  Add note about
objects that are deleted within an ongoing transaction.
---

diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py
index dd82fa02f3..f5c52a6ada 100644
--- a/lib/sqlalchemy/orm/session.py
+++ b/lib/sqlalchemy/orm/session.py
@@ -2443,16 +2443,17 @@ def make_transient_to_detached(instance):
 
 
 def object_session(instance):
-    """Return the ``Session`` to which instance belongs.
+    """Return the :class:`.Session` to which the given instance belongs.
 
-    If the instance is not a mapped instance, an error is raised.
+    This is essentially the same as the :attr:`.InstanceState.session`
+    accessor.  See that attribute for details.
 
     """
-
     try:
-        return _state_session(attributes.instance_state(instance))
+        state = attributes.instance_state(instance)
     except exc.NO_STATE:
         raise exc.UnmappedInstanceError(instance)
-
+    else:
+        return _state_session(state)
 
 _new_sessionid = util.counter()
diff --git a/lib/sqlalchemy/orm/state.py b/lib/sqlalchemy/orm/state.py
index b9aff7a853..c41a3c869a 100644
--- a/lib/sqlalchemy/orm/state.py
+++ b/lib/sqlalchemy/orm/state.py
@@ -146,7 +146,16 @@ class InstanceState(interfaces._InspectionAttr):
     @util.dependencies("sqlalchemy.orm.session")
     def session(self, sessionlib):
         """Return the owning :class:`.Session` for this instance,
-        or ``None`` if none available."""
+        or ``None`` if none available.
+
+        Note that the result here can in some cases be *different*
+        from that of ``obj in session``; an object that's been deleted
+        will report as not ``in session``, however if the transaction is
+        still in progress, this attribute will still refer to that session.
+        Only when the transaction is completed does the object become
+        fully detached under normal circumstances.
+
+        """
         return sessionlib._state_session(self)
 
     @property