API refactor

venv/lib/python3.12/site-packages/sqlalchemy/orm/state.py

@@ -1,5 +1,5 @@
 # orm/state.py
-# Copyright (C) 2005-2023 the SQLAlchemy authors and contributors
+# Copyright (C) 2005-2025 the SQLAlchemy authors and contributors
 # <see AUTHORS file>
 #
 # This module is part of SQLAlchemy and is released under
@@ -78,8 +78,7 @@ if not TYPE_CHECKING:
 
 
 class _InstanceDictProto(Protocol):
-    def __call__(self) -> Optional[IdentityMap]:
-        ...
+    def __call__(self) -> Optional[IdentityMap]: ...
 
 
 class _InstallLoaderCallableProto(Protocol[_O]):
@@ -94,13 +93,12 @@ class _InstallLoaderCallableProto(Protocol[_O]):
 
     def __call__(
         self, state: InstanceState[_O], dict_: _InstanceDict, row: Row[Any]
-    ) -> None:
-        ...
+    ) -> None: ...
 
 
 @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;
@@ -150,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
@@ -171,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.
@@ -230,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`