From 71c13990aa1ea7af8777aae4a2a26d3f6d6e8a0a Mon Sep 17 00:00:00 2001 From: Federico Caselli Date: Tue, 2 Feb 2021 20:49:41 +0100 Subject: [PATCH] Improve noload documentation Also add a link to the loading strategies doc from the async orm docs Fixes: #5832 Change-Id: I41170369273df7d323f7140cd05759567484dc4d --- doc/build/orm/extensions/asyncio.rst | 4 +++- doc/build/orm/loading_relationships.rst | 2 +- lib/sqlalchemy/orm/strategy_options.py | 8 ++++++++ 3 files changed, 12 insertions(+), 2 deletions(-) diff --git a/doc/build/orm/extensions/asyncio.rst b/doc/build/orm/extensions/asyncio.rst index 2fa274fcdd..43068288d2 100644 --- 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 e1ae5e0b18..8cc0308634 100644 --- 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 fbecfedebe..f24f42a6b3 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` -- 2.47.2