From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Sat, 9 Feb 2019 17:22:39 +0000 (-0500)
Subject: Note for history methods that history is reset per-flush.
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=83983593b353642d8013757085d9df3214922530;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

Note for history methods that history is reset per-flush.

Change-Id: I9bc4d0ddfa93f13e6717b89fa9934f1b8052147f
(cherry picked from commit 833583458c69e24e797c300c934da0ff04348db5)
---

diff --git a/lib/sqlalchemy/orm/attributes.py b/lib/sqlalchemy/orm/attributes.py
index 61647a7b79..07b0674012 100644
--- a/lib/sqlalchemy/orm/attributes.py
+++ b/lib/sqlalchemy/orm/attributes.py
@@ -1414,6 +1414,17 @@ def get_history(obj, key, passive=PASSIVE_OFF):
     """Return a :class:`.History` record for the given object
     and attribute key.
 
+    This is the **pre-flush** history for a given attribute, which is
+    reset each time the :class:`.Session` flushes changes to the
+    current database transaction.
+
+    .. note::
+
+        Prefer to use the :attr:`.AttributeState.history` and
+        :meth:`.AttributeState.load_history` accessors to retrieve the
+        :class:`.History` for instance attributes.
+
+
     :param obj: an object whose class is instrumented by the
       attributes package.
 
@@ -1425,6 +1436,13 @@ def get_history(obj, key, passive=PASSIVE_OFF):
        :attr:`.PASSIVE_OFF` indicating all necessary SQL
        should be emitted.
 
+    .. seealso::
+
+        :attr:`.AttributeState.history`
+
+        :meth:`.AttributeState.load_history` - retrieve history
+        using loader callables if the value is not locally present.
+
     """
     if passive is True:
         util.warn_deprecated("Passing True for 'passive' is deprecated. "
diff --git a/lib/sqlalchemy/orm/state.py b/lib/sqlalchemy/orm/state.py
index fb6d25a7f4..9929532af2 100644
--- a/lib/sqlalchemy/orm/state.py
+++ b/lib/sqlalchemy/orm/state.py
@@ -784,12 +784,21 @@ class AttributeState(object):
 
     @property
     def history(self):
-        """Return the current pre-flush change history for
+        """Return the current **pre-flush** change history for
         this attribute, via the :class:`.History` interface.
 
         This method will **not** emit loader callables if the value of the
         attribute is unloaded.
 
+        .. note::
+
+            The attribute history system tracks changes on a **per flush
+            basis**. Each time the :class:`.Session` is flushed, the history
+            of each attribute is reset to empty.   The :class:`.Session` by
+            default autoflushes each time a :class:`.Query` is invoked.  For
+            options on how to control this, see :ref:`session_flushing`.
+
+
         .. seealso::
 
             :meth:`.AttributeState.load_history` - retrieve history
@@ -802,12 +811,20 @@ class AttributeState(object):
                                       PASSIVE_NO_INITIALIZE)
 
     def load_history(self):
-        """Return the current pre-flush change history for
+        """Return the current **pre-flush** change history for
         this attribute, via the :class:`.History` interface.
 
         This method **will** emit loader callables if the value of the
         attribute is unloaded.
 
+        .. note::
+
+            The attribute history system tracks changes on a **per flush
+            basis**. Each time the :class:`.Session` is flushed, the history
+            of each attribute is reset to empty.   The :class:`.Session` by
+            default autoflushes each time a :class:`.Query` is invoked.  For
+            options on how to control this, see :ref:`session_flushing`.
+
         .. seealso::
 
             :attr:`.AttributeState.history`