Document InstanceState modified and expired.

Fixes: #11431
Change-Id: Iff762b0c14db5b8851ea8fa20f4304c0cc6657de
(cherry picked from commit c1cc8793388214351ab0ccead9616c80458c5bb9)

diff --git a/lib/sqlalchemy/orm/state.py b/lib/sqlalchemy/orm/state.py
index 03b81f90405a1618f7d49f49044de22d17aa79f5..9dfd7f64fe978d5d4e199eb1e94b2ea2fb6c33d3 100644 (file)
--- a/lib/sqlalchemy/orm/state.py
+++ b/lib/sqlalchemy/orm/state.py
@@ -98,7 +98,7 @@ class _InstallLoaderCallableProto(Protocol[_O]):
 
 @inspection._self_inspects
 class InstanceState(interfaces.InspectionAttrInfo, Generic[_O]):
-    """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;
@@ -148,7 +148,14 @@ class InstanceState(interfaces.InspectionAttrInfo, Generic[_O]):
     committed_state: Dict[str, Any]
 
     modified: bool = False
+    """When ``True`` the object was modified."""
     expired: bool = False
+    """When ``True`` the object is :term:`expired`.
+
+    .. seealso::
+
+        :ref:`session_expire`
+    """
     _deleted: bool = False
     _load_pending: bool = False
     _orphaned_outside_of_session: bool = False
@@ -169,11 +176,12 @@ class InstanceState(interfaces.InspectionAttrInfo, Generic[_O]):
 
     expired_attributes: Set[str]
     """The set of keys which are 'expired' to be loaded by
-       the manager's deferred scalar loader, assuming no pending
-       changes.
+    the manager's deferred scalar loader, assuming no pending
+    changes.
 
-       see also the ``unmodified`` collection which is intersected
-       against this set when a refresh operation occurs."""
+    See also the ``unmodified`` collection which is intersected
+    against this set when a refresh operation occurs.
+    """
 
     callables: Dict[str, Callable[[InstanceState[_O], PassiveFlag], Any]]
     """A namespace where a per-state loader callable can be associated.
@@ -228,7 +236,6 @@ class InstanceState(interfaces.InspectionAttrInfo, Generic[_O]):
     def pending(self) -> bool:
         """Return ``True`` if the object is :term:`pending`.
 
-
         .. seealso::
 
             :ref:`session_object_states`