Improve noload documentation

Also add a link to the loading strategies doc from the
async orm docs

Fixes: #5832
Change-Id: I41170369273df7d323f7140cd05759567484dc4d

diff --git a/doc/build/orm/extensions/asyncio.rst b/doc/build/orm/extensions/asyncio.rst
index 2fa274fcdd40cd0f6abd710e2c988ddd64e53d19..43068288d27710a1aba33cd6bdae4a654c220c14 100644 (file)
--- a/doc/build/orm/extensions/asyncio.rst
+++ b/doc/build/orm/extensions/asyncio.rst
@@ -142,6 +142,8 @@ This also includes that methods such as :meth:`_orm.Session.expire` should be
 avoided in favor of :meth:`_asyncio.AsyncSession.refresh`, and that
 appropriate loader options should be employed for :func:`_orm.deferred`
 columns as well as for :func:`_orm.relationship` constructs.
+The full list of available loaders is documented in the section
+:doc:`/orm/loading_relationships`.
 
 In the example above the :class:`_asyncio.AsyncSession` is instantiated with an
 :class:`_asyncio.AsyncEngine` associated with a particular database URL.
@@ -270,7 +272,7 @@ along the lines of
 
 If the same engine must be shared between different loop, it should be configured
 to disable pooling using :class:`~sqlalchemy.pool.NullPool`, preventing the Engine
-from using any connection more than once:
+from using any connection more than once::
 
     from sqlalchemy.pool import NullPool
     engine = create_async_engine(

diff --git a/doc/build/orm/loading_relationships.rst b/doc/build/orm/loading_relationships.rst
index e1ae5e0b188306553d125f39851ba2fd92b846c8..8cc0308634139d655c95e592a15118ab49c2000b 100644 (file)
--- a/doc/build/orm/loading_relationships.rst
+++ b/doc/build/orm/loading_relationships.rst
@@ -61,7 +61,7 @@ The primary forms of relationship loading are:
   An introduction to raise loading is at :ref:`prevent_lazy_with_raiseload`.
 
 * **no loading** - available via ``lazy='noload'``, or the :func:`.noload`
-  option; this loading style turns the attribute into an empty attribute that
+  option; this loading style turns the attribute into an empty attribute (``None``) that
   will never load or have any loading effect.  "noload" is a fairly
   uncommon loader option.
 

diff --git a/lib/sqlalchemy/orm/strategy_options.py b/lib/sqlalchemy/orm/strategy_options.py
index fbecfedebe1fbddc48464c2326009b2e255fd989..f24f42a6b37c37ee4ea9b6ee1226e2f7b9d56575 100644 (file)
--- 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`