Clarify documentation for lazy_loaded_from

This attribute was never available in conjunction with
mapper options, and additionally the use of baked queries
in the lazy loader strategy prevent this attribute from
being reliably available within the before_compile hook
unless baked queries are turned off entirely.

Fixes: #5109
Change-Id: I5fa12c68463d20475e7470647a784efe846b8af7
(cherry picked from commit 8426f97cdb77076abddabbd2a755022e85b870e8)

diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index 051a368f43afc3f7a45ac4cd40b0a778881d19a2..10ab7259613fea6cefb770288d3e7308d0a15a29 100644 (file)
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -131,9 +131,31 @@ class Query(object):
     """An :class:`.InstanceState` that is using this :class:`.Query` for a
     lazy load operation.
 
-    This can be used for extensions like the horizontal sharding extension
-    as well as event handlers and custom mapper options to determine
-    when a query is being used to lazy load a relationship on an object.
+    The primary rationale for this attribute is to support the horizontal
+    sharding extension, where it is available within specific query
+    execution time hooks created by this extension.   To that end, the
+    attribute is only intended to be meaningful at **query execution time**,
+    and importantly not any time prior to that, including query compilation
+    time.
+
+    .. note::
+
+        Within the realm of regular :class:`.Query` usage, this attribute is
+        set by the lazy loader strategy before the query is invoked.  However
+        there is no established hook that is available to reliably intercept
+        this value programmatically.  It is set by the lazy loading strategy
+        after any  mapper option objects would have been applied, and now that
+        the lazy  loading strategy in the ORM makes use of "baked" queries to
+        cache SQL  compilation, the :meth:`.QueryEvents.before_compile` hook is
+        also not reliable.
+
+        Currently, setting the :paramref:`.relationship.bake_queries` to
+        ``False`` on the target :func:`.relationship`, and then making use of
+        the :meth:`.QueryEvents.before_compile` event hook, is the only
+        available programmatic path to intercepting this attribute. In future
+        releases, there will be new hooks available that allow interception of
+        the :class:`.Query` before it is executed, rather than before it is
+        compiled.
 
     .. versionadded:: 1.2.9