From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Thu, 14 Oct 2021 22:24:26 +0000 (-0400)
Subject: clarify that with_loader_criteria does not affect contains_eager()
X-Git-Tag: rel_1_4_26~16
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=fec2b6560c14bb28ee7fc9d21028844acf700b04;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

clarify that with_loader_criteria does not affect contains_eager()

The ORM contains_eager() option does not affect the rendering
of a SQL query in any way except that it adds additional columns
to the columns clause of the SELECT. Therefore the
with_loader_criteria() function has no interaction with this
loader option.

Fixes: #7189
Change-Id: I2e5439746de92382615b652c0e0801b6e48210c8
---

diff --git a/lib/sqlalchemy/orm/util.py b/lib/sqlalchemy/orm/util.py
index 63a2774b31..8e0fd44cda 100644
--- a/lib/sqlalchemy/orm/util.py
+++ b/lib/sqlalchemy/orm/util.py
@@ -1012,6 +1012,13 @@ class LoaderCriteriaOption(CriteriaOption):
         argument.  The given class will expand to include all mapped subclass
         and need not itself be a mapped class.
 
+        .. note:: The :func:`_orm.with_loader_criteria` option only applies to
+           loader options that **render their own SQL**, which means it does
+           **not** apply to the :func:`_orm.contains_eager` option.  To apply
+           additional criteria to the JOIN used in conjunction with
+           :func:`_orm.contains_eager`, specify additional criteria within
+           the :meth:`_sql.select.join` or :meth:`_orm.Query.join` method.
+
         .. warning:: The use of a lambda inside of the call to
           :func:`_orm.with_loader_criteria` is only invoked **once per unique
           class**. Custom functions should not be invoked within this lambda.