add note re: pickling for loader criteria

Change-Id: I75992af71ba08799a03995178a6e4612c9a7428a
References: #8108

diff --git a/lib/sqlalchemy/orm/util.py b/lib/sqlalchemy/orm/util.py
index a5c571ad75d1c4a3d9cbc404ca81f21bf18b0e7a..1c9c9c796f7d64aa0fc296e2a8f8a3561b8c07cd 100644 (file)
--- a/lib/sqlalchemy/orm/util.py
+++ b/lib/sqlalchemy/orm/util.py
@@ -1092,12 +1092,19 @@ class LoaderCriteriaOption(CriteriaOption):
          accepts a target class as an argument, when the given class is
          a base with many different mapped subclasses.
 
+         .. note:: when the SQL expression is a lambda, **pickling is not
+            supported**.  Set
+            :paramref:`_orm.with_loader_criteria.propagate_to_loaders`
+            to ``False`` to prevent the object from being applied to instances.
+
         :param include_aliases: if True, apply the rule to :func:`_orm.aliased`
          constructs as well.
 
         :param propagate_to_loaders: defaults to True, apply to relationship
-         loaders such as lazy loaders.
-
+         loaders such as lazy loaders.  This indicates that the
+         option object itself including SQL expression is carried along with
+         each loaded instance.  Set to ``False`` to prevent the object from
+         being assigned to individual instances.
 
         .. seealso::