From 9f72da76589d14eefcad682a73a334128f4dab8b Mon Sep 17 00:00:00 2001
From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Fri, 4 Apr 2014 17:33:35 -0400
Subject: [PATCH] - add some docs for the instancestate linkage to the
 inspection system

---
 doc/build/orm/session.rst   | 22 ++++++++++++
 lib/sqlalchemy/orm/state.py | 72 ++++++++++++++++++++++++++++++++++---
 2 files changed, 89 insertions(+), 5 deletions(-)

diff --git a/doc/build/orm/session.rst b/doc/build/orm/session.rst
index 05b2535bcd..db52f1f394 100644
--- a/doc/build/orm/session.rst
+++ b/doc/build/orm/session.rst
@@ -196,6 +196,28 @@ Knowing these states is important, since the
 operations (such as trying to save the same object to two different sessions
 at the same time).
 
+Getting the Current State of an Object
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The actual state of any mapped object can be viewed at any time using
+the :func:`.inspect` system::
+
+  >>> from sqlalchemy import inspect
+  >>> insp = inspect(my_object)
+  >>> insp.persistent
+  True
+
+.. seealso::
+
+    :attr:`.InstanceState.transient`
+
+    :attr:`.InstanceState.pending`
+
+    :attr:`.InstanceState.persistent`
+
+    :attr:`.InstanceState.detached`
+
+
 .. _session_faq:
 
 Session Frequently Asked Questions
diff --git a/lib/sqlalchemy/orm/state.py b/lib/sqlalchemy/orm/state.py
index 4a00cfe9db..e8c917016d 100644
--- a/lib/sqlalchemy/orm/state.py
+++ b/lib/sqlalchemy/orm/state.py
@@ -25,7 +25,30 @@ mapperlib = util.importlater("sqlalchemy.orm", "mapperlib")
 
 
 class InstanceState(interfaces._InspectionAttr):
-    """tracks state information at the instance level."""
+    """tracks state information at the instance level.
+
+    The :class:`.InstanceState` is a key object used by the
+    SQLAlchemy ORM in order to track the state of an object;
+    it is created the moment an object is instantiated, typically
+    as a result of :term:`instrumentation` which SQLAlchemy applies
+    to the ``__init__()`` method of the class.
+
+    :class:`.InstanceState` is also a semi-public object,
+    available for runtime inspection as to the state of a
+    mapped instance, including information such as its current
+    status within a particular :class:`.Session` and details
+    about data on individual attributes.  The public API
+    in order to acquire a :class:`.InstanceState` object
+    is to use the :func:`.inspect` system::
+
+        >>> from sqlalchemy import inspect
+        >>> insp = inspect(some_mapped_object)
+
+    .. seealso::
+
+        :ref:`core_inspection_toplevel`
+
+    """
 
     session_id = None
     key = None
@@ -55,6 +78,9 @@ class InstanceState(interfaces._InspectionAttr):
         and history.
 
         The returned object is an instance of :class:`.AttributeState`.
+        This object allows inspection of the current data
+        within an attribute as well as attribute history
+        since the last flush.
 
         """
         return util.ImmutableProperties(
@@ -66,25 +92,50 @@ class InstanceState(interfaces._InspectionAttr):
 
     @property
     def transient(self):
-        """Return true if the object is transient."""
+        """Return true if the object is :term:`transient`.
+
+        .. seealso::
+
+            :ref:`session_object_states`
+
+        """
         return self.key is None and \
             not self._attached
 
     @property
     def pending(self):
-        """Return true if the object is pending."""
+        """Return true if the object is :term:`pending`.
+
+
+        .. seealso::
+
+            :ref:`session_object_states`
+
+        """
         return self.key is None and \
             self._attached
 
     @property
     def persistent(self):
-        """Return true if the object is persistent."""
+        """Return true if the object is :term:`persistent`.
+
+        .. seealso::
+
+            :ref:`session_object_states`
+
+            """
         return self.key is not None and \
             self._attached
 
     @property
     def detached(self):
-        """Return true if the object is detached."""
+        """Return true if the object is :term:`detached`.
+
+        .. seealso::
+
+            :ref:`session_object_states`
+
+        """
         return self.key is not None and \
             not self._attached
 
@@ -184,6 +235,17 @@ class InstanceState(interfaces._InspectionAttr):
 
     @property
     def dict(self):
+        """Return the instance dict used by the object.
+
+        Under normal circumstances, this is always synonymous
+        with the ``__dict__`` attribute of the mapped object,
+        unless an alternative instrumentation system has been
+        configured.
+
+        In the case that the actual object has been garbage
+        collected, this accessor returns a blank dictionary.
+
+        """
         o = self.obj()
         if o is not None:
             return attributes.instance_dict(o)
-- 
2.39.5