Improve ``run_sync`` documentation in asyncio ext

Change-Id: I202458ab6d81e29053118c9fb9c205b865c8d2ba
Ref: #5817

1 files changed, 10 insertions, 0 deletions

diff --git a/lib/sqlalchemy/ext/asyncio/session.py b/lib/sqlalchemy/ext/asyncio/session.py
index 9a8284e64..faa279cf9 100644
--- a/lib/sqlalchemy/ext/asyncio/session.py
+++ b/lib/sqlalchemy/ext/asyncio/session.py
@@ -121,6 +121,16 @@ class AsyncSession:
             with AsyncSession(async_engine) as session:
                 await session.run_sync(some_business_method)
 
+        .. note::
+
+            The provided callable is invoked inline within the asyncio event
+            loop, and will block on traditional IO calls.  IO within this
+            callable should only call into SQLAlchemy's asyncio database
+            APIs which will be properly adapted to the greenlet context.
+
+        .. seealso::
+
+            :ref:`session_run_sync`
         """
 
         return await greenlet_spawn(fn, self.sync_session, *arg, **kw)