Document dynamic for asyncio

Change-Id: Ieedc748587288c30630a2453f20eb72001cb78ab
(cherry picked from commit aeb61f4bb7d0b6d3d550d0206046208d6d4d7e91)

diff --git a/doc/build/orm/collections.rst b/doc/build/orm/collections.rst
index e803fc7843c9f35e981bdab25acf1b8db0b0ce83..bc98b4b41d810b60cfe28679c24474046451fae4 100644 (file)
--- a/doc/build/orm/collections.rst
+++ b/doc/build/orm/collections.rst
@@ -37,6 +37,9 @@ Dynamic Relationship Loaders
    method of use.  For relationships that shouldn't load, set
    :paramref:`_orm.relationship.lazy` to ``noload``.
 
+.. note:: This loader is in the general case not compatible with the :ref:`asyncio_toplevel` extension.
+   It can be used with some limitations, as indicated in :ref:`Asyncio dynamic guidelines <dynamic_asyncio>`.
+
 A :func:`_orm.relationship` which corresponds to a large collection can be
 configured so that it returns a legacy :class:`_orm.Query` object when
 accessed, which allows filtering of the relationship on criteria. The class is

diff --git a/doc/build/orm/extensions/asyncio.rst b/doc/build/orm/extensions/asyncio.rst
index 9bc72d362cf2f73b306d0af3d4a247a6ac69b9b4..fcaf104467cf3b1e9ca0ae5764012672fb26e4c5 100644 (file)
--- a/doc/build/orm/extensions/asyncio.rst
+++ b/doc/build/orm/extensions/asyncio.rst
@@ -327,11 +327,21 @@ Other guidelines include:
   constructs as noted above.  See :ref:`deferred` for background on
   deferred column loading.
 
+.. _dynamic_asyncio:
+
 * The "dynamic" relationship loader strategy described at
-  :ref:`dynamic_relationship` is not compatible with the asyncio approach and
-  cannot be used, unless invoked within the
+  :ref:`dynamic_relationship` is not compatible by default with the asyncio approach.
+  It can be used directly only if invoked within the
   :meth:`_asyncio.AsyncSession.run_sync` method described at
-  :ref:`session_run_sync`.
+  :ref:`session_run_sync`, or by using its ``.statement`` attribute
+  to obtain a normal select::
+
+      user = await session.get(User, 42)
+      addresses = (await session.scalars(user.addresses.statement)).all()
+      stmt = user.addresses.statement.where(
+          Address.email_address.startswith("patrick")
+      )
+      addresses_filter = (await session.scalars(stmt)).all()
 
 .. _session_run_sync: