- rewrite the docs and add a test for the bake_queries=True

relationship flag; this flag *does* have an effect when the baked
lazy loader plugin has been invoked.  clarify the intent of this
flag as an "opt out" but only has an effect when the baked system
is loaded anyway.  fixes #3572

3 files changed, 75 insertions, 7 deletions

diff --git a/doc/build/orm/extensions/baked.rst b/doc/build/orm/extensions/baked.rst
index a282d1298..83cee51da 100644
--- a/doc/build/orm/extensions/baked.rst
+++ b/doc/build/orm/extensions/baked.rst
@@ -355,6 +355,14 @@ this feature is local to the mapper for ``MyClass``.
 For per-query use, the :func:`.baked_lazyload` strategy may be used,
 which works like any other loader option.
 
+Opting out with the bake_queries flag
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The :func:`.relationship` construct includes a flag
+:paramref:`.relationship.bake_queries` which when set to False will cause
+that relationship to opt out of the baked query system, when the
+application-wide :func:`.bake_lazy_loaders` function has been called to enable
+baked query loaders by default.
 
 API Documentation
 -----------------
diff --git a/lib/sqlalchemy/orm/relationships.py b/lib/sqlalchemy/orm/relationships.py
index 552ce8b69..929c923a6 100644
--- a/lib/sqlalchemy/orm/relationships.py
+++ b/lib/sqlalchemy/orm/relationships.py
@@ -275,15 +275,31 @@ class RelationshipProperty(StrategizedProperty):
             :paramref:`~.relationship.backref` - alternative form
             of backref specification.
 
-        :param bake_queries:
-          Use the :class:`.BakedQuery` cache to cache queries used in lazy
-          loads.  True by default, as this typically improves performance
-          significantly.  Set to False to reduce ORM memory use, or
-          if unresolved stability issues are observed with the baked query
+        :param bake_queries=True:
+          Use the :class:`.BakedQuery` cache to cache the construction of SQL
+          used in lazy loads, when the :func:`.bake_lazy_loaders` function has
+          first been called.  Defaults to True and is intended to provide an
+          "opt out" flag per-relationship when the baked query cache system is
+          in use.
+
+          .. warning::
+
+              This flag **only** has an effect when the application-wide
+              :func:`.bake_lazy_loaders` function has been called.   It
+              defaults to True so is an "opt out" flag.
+
+          Setting this flag to False when baked queries are otherwise in
+          use might be to reduce
+          ORM memory use for this :func:`.relationship`, or to work around
+          unresolved stability issues observed within the baked query
           cache system.
 
           .. versionadded:: 1.0.0
 
+          .. seealso::
+
+            :ref:`baked_toplevel`
+
         :param cascade:
           a comma-separated list of cascade rules which determines how
           Session operations should be "cascaded" from parent to child.
diff --git a/test/ext/test_baked.py b/test/ext/test_baked.py
index 8bf697fbf..dcf333184 100644
--- a/test/ext/test_baked.py
+++ b/test/ext/test_baked.py
@@ -596,14 +596,14 @@ class ResultTest(BakedTest):
 class LazyLoaderTest(BakedTest):
     run_setup_mappers = 'each'
 
-    def _o2m_fixture(self, lazy="select"):
+    def _o2m_fixture(self, lazy="select", **kw):
         User = self.classes.User
         Address = self.classes.Address
 
         mapper(User, self.tables.users, properties={
             'addresses': relationship(
                 Address, order_by=self.tables.addresses.c.id,
-                lazy=lazy)
+                lazy=lazy, **kw)
         })
         mapper(Address, self.tables.addresses)
         return User, Address
@@ -720,6 +720,50 @@ class LazyLoaderTest(BakedTest):
             # not invoked
             eq_(el.mock_calls, [])
 
+    def test_baked_lazy_loading_relationship_flag_true(self):
+        self._test_baked_lazy_loading_relationship_flag(True)
+
+    def test_baked_lazy_loading_relationship_flag_false(self):
+        self._test_baked_lazy_loading_relationship_flag(False)
+
+    def _test_baked_lazy_loading_relationship_flag(self, flag):
+        baked.bake_lazy_loaders()
+        try:
+            User, Address = self._o2m_fixture(bake_queries=flag)
+
+            sess = Session()
+            u1 = sess.query(User).first()
+
+            from sqlalchemy.orm import Query
+
+            canary = mock.Mock()
+
+            # I would think Mock can do this but apparently
+            # it cannot (wrap / autospec don't work together)
+            real_compile_context = Query._compile_context
+
+            def _my_compile_context(*arg, **kw):
+                if arg[0].column_descriptions[0]['entity'] is Address:
+                    canary()
+                return real_compile_context(*arg, **kw)
+
+            with mock.patch.object(
+                Query,
+                "_compile_context",
+                _my_compile_context
+            ):
+                u1.addresses
+
+                sess.expire(u1)
+                u1.addresses
+        finally:
+            baked.unbake_lazy_loaders()
+
+        if flag:
+            eq_(canary.call_count, 1)
+        else:
+            eq_(canary.call_count, 2)
+
     def test_baked_lazy_loading_option_o2m(self):
         User, Address = self._o2m_fixture()
         self._test_baked_lazy_loading(set_option=True)