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

diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index 5f799cc68b0fe537b334f7f5c7a415a3302102e6..55b569bcd5aec6dce911a6ab930f502da5337e18 100644 (file)
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -133,9 +133,31 @@ class Query(Generative):
     """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