Merge "Improve noload documentation"

1 files changed, 8 insertions, 0 deletions

diff --git a/lib/sqlalchemy/orm/strategy_options.py b/lib/sqlalchemy/orm/strategy_options.py
index fbecfedeb..f24f42a6b 100644
--- a/lib/sqlalchemy/orm/strategy_options.py
+++ b/lib/sqlalchemy/orm/strategy_options.py
@@ -1341,12 +1341,20 @@ def immediateload(*keys):
 def noload(loadopt, attr):
     """Indicate that the given relationship attribute should remain unloaded.
 
+    The relationship attribute will return ``None`` when accessed without
+    producing any loading effect.
+
     This function is part of the :class:`_orm.Load` interface and supports
     both method-chained and standalone operation.
 
     :func:`_orm.noload` applies to :func:`_orm.relationship` attributes; for
     column-based attributes, see :func:`_orm.defer`.
 
+    .. 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.
+
     .. seealso::
 
         :ref:`loading_toplevel`