From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Fri, 25 Oct 2019 14:08:18 +0000 (-0400)
Subject: Warn that before_compile for lazyload needs bake_queries=False
X-Git-Tag: rel_1_4_0b1~655
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=172d99a8a1282b534aeadafebdd2af0162758931;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

Warn that before_compile for lazyload needs bake_queries=False

The longer term future plan for ORM queries is that there
will be a new hook that receives queries before invocation
rather than "compilation", which will make use of a new
caching system.

Fixes: #4947
Change-Id: I256c16155a0cc9b7133e86e22d27040cb64eb1a9
---

diff --git a/lib/sqlalchemy/orm/events.py b/lib/sqlalchemy/orm/events.py
index 778ad33780..5bb67b68ff 100644
--- a/lib/sqlalchemy/orm/events.py
+++ b/lib/sqlalchemy/orm/events.py
@@ -2397,6 +2397,13 @@ class QueryEvents(event.Events):
         The event should normally be listened with the ``retval=True``
         parameter set, so that the modified query may be returned.
 
+        .. warning::  If the :meth:`.QueryEvents.before_compile` event is to
+           be applied to :class:`.Query` objects that are used for lazy loading
+           of :func:`.relationships` (as described at :ref:`lazy_loading`),
+           it may be necessary to set :paramref:`.relationship.bake_queries`
+           to ``False``, else the :meth:`.QueryEvents.before_compile` event
+           will not be invoked for each lazy load operation.
+
         .. seealso::
 
             :meth:`.QueryEvents.before_compile_update`