immediateload lazy relationships named in refresh.attribute_names

The :meth:`_orm.Session.refresh` method will now immediately load a
relationship-bound attribute that is explicitly named within the
:paramref:`_orm.Session.refresh.attribute_names` collection even if it is
currently linked to the "select" loader, which normally is a "lazy" loader
that does not fire off during a refresh. The "lazy loader" strategy will
now detect that the operation is specifically a user-initiated
:meth:`_orm.Session.refresh` operation which named this attribute
explicitly, and will then call upon the "immediateload" strategy to
actually emit SQL to load the attribute. This should be helpful in
particular for some asyncio situations where the loading of an unloaded
lazy-loaded attribute must be forced, without using the actual lazy-loading
attribute pattern not supported in asyncio.

Fixes: #9298
Change-Id: I9b50f339bdf06cdb2ec98f8e5efca2b690895dd7

2 files changed, 42 insertions, 0 deletions

diff --git a/doc/build/changelog/unreleased_20/9298.rst b/doc/build/changelog/unreleased_20/9298.rst
new file mode 100644
index 000000000..f9150eb3b
--- /dev/null
+++ b/doc/build/changelog/unreleased_20/9298.rst
@@ -0,0 +1,17 @@
+.. change::
+    :tags: usecase, orm
+    :tickets: 9298
+
+    The :meth:`_orm.Session.refresh` method will now immediately load a
+    relationship-bound attribute that is explicitly named within the
+    :paramref:`_orm.Session.refresh.attribute_names` collection even if it is
+    currently linked to the "select" loader, which normally is a "lazy" loader
+    that does not fire off during a refresh. The "lazy loader" strategy will
+    now detect that the operation is specifically a user-initiated
+    :meth:`_orm.Session.refresh` operation which named this attribute
+    explicitly, and will then call upon the "immediateload" strategy to
+    actually emit SQL to load the attribute. This should be helpful in
+    particular for some asyncio situations where the loading of an unloaded
+    lazy-loaded attribute must be forced, without using the actual lazy-loading
+    attribute pattern not supported in asyncio.
+
diff --git a/doc/build/orm/extensions/asyncio.rst b/doc/build/orm/extensions/asyncio.rst
index 322c5081a..59989ad4e 100644
--- a/doc/build/orm/extensions/asyncio.rst
+++ b/doc/build/orm/extensions/asyncio.rst
@@ -337,6 +337,31 @@ Other guidelines include:
   :paramref:`_orm.Session.expire_on_commit`
   should normally be set to ``False`` when using asyncio.
 
+* A lazy-loaded relationship **can be loaded explicitly under asyncio** using
+  :meth:`_asyncio.AsyncSession.refresh`, **if** the desired attribute name
+  is passed explicitly to
+  :paramref:`_orm.Session.refresh.attribute_names`, e.g.::
+
+    # assume a_obj is an A that has lazy loaded A.bs collection
+    a_obj = await async_session.get(A, [1])
+
+    # force the collection to load by naming it in attribute_names
+    await async_session.refresh(a_obj, ["bs"])
+
+    # collection is present
+    print(f"bs collection: {a_obj.bs}")
+
+  It's of course preferable to use eager loading up front in order to have
+  collections already set up without the need to lazy-load.
+
+  .. versionadded:: 2.0.4 Added support for
+     :meth:`_asyncio.AsyncSession.refresh` and the underlying
+     :meth:`_orm.Session.refresh` method to force lazy-loaded relationships
+     to load, if they are named explicitly in the
+     :paramref:`_orm.Session.refresh.attribute_names` parameter.
+     In previous versions, the relationship would be silently skipped even
+     if named in the parameter.
+
 * Avoid using the ``all`` cascade option documented at :ref:`unitofwork_cascades`
   in favor of listing out the desired cascade features explicitly.   The
   ``all`` cascade option implies among others the :ref:`cascade_refresh_expire`