strongly discourage noload

Change-Id: I54a1c1d29b33091838b7f3fcd46eeec48bbd498b

diff --git a/doc/build/orm/queryguide/relationships.rst b/doc/build/orm/queryguide/relationships.rst
index 30c8b1906fc9c2230d5b57877fac1166ba3d99fc..bf6f692b98ada8b43ef28ecbc1cfd4bf501c8c0b 100644 (file)
--- a/doc/build/orm/queryguide/relationships.rst
+++ b/doc/build/orm/queryguide/relationships.rst
@@ -1001,8 +1001,7 @@ Wildcard Loading Strategies
 ---------------------------
 
 Each of :func:`_orm.joinedload`, :func:`.subqueryload`, :func:`.lazyload`,
-:func:`.selectinload`,
-:func:`.noload`, and :func:`.raiseload` can be used to set the default
+:func:`.selectinload`, and :func:`.raiseload` can be used to set the default
 style of :func:`_orm.relationship` loading
 for a particular query, affecting all :func:`_orm.relationship` -mapped
 attributes not otherwise

diff --git a/lib/sqlalchemy/orm/strategy_options.py b/lib/sqlalchemy/orm/strategy_options.py
index 31c3a54e3238c267bedbb2d7fb7112b9ecabfde9..974a1ff45f6b7913fc7997f3d6e80cd85792807b 100644 (file)
--- a/lib/sqlalchemy/orm/strategy_options.py
+++ b/lib/sqlalchemy/orm/strategy_options.py
@@ -507,10 +507,10 @@ class _AbstractLoad(traversals.GenerativeOnTraversal, LoaderOption):
         :func:`_orm.noload` applies to :func:`_orm.relationship` attributes
         only.
 
-        .. note:: Setting this loading strategy as the default strategy
-            for a relationship using the :paramref:`.orm.relationship.lazy`
-            parameter may cause issues with flushes, such if a delete operation
-            needs to load related objects and instead ``None`` was returned.
+        .. legacy:: The :func:`_orm.noload` option is **legacy**.  As it
+           forces collections to be empty, which invariably leads to
+           non-intuitive and difficult to predict results.  There are no
+           legitimate uses for this option in modern SQLAlchemy.
 
         .. seealso::