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 63a2774b31e585a80c01522a04765f423489285c..8e0fd44cda08d9d3cd051d7519907936214f9556 100644 (file)
--- 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.