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

Change-Id: I9bc4d0ddfa93f13e6717b89fa9934f1b8052147f

1 files changed, 18 insertions, 0 deletions

diff --git a/lib/sqlalchemy/orm/attributes.py b/lib/sqlalchemy/orm/attributes.py
index 879b88a92..1b8c8c7f3 100644
--- a/lib/sqlalchemy/orm/attributes.py
+++ b/lib/sqlalchemy/orm/attributes.py
@@ -1724,6 +1724,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.
 
@@ -1735,6 +1746,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(