Improve ``run_sync`` documentation in asyncio ext

Change-Id: I202458ab6d81e29053118c9fb9c205b865c8d2ba
Ref: #5817

diff --git a/doc/build/orm/extensions/asyncio.rst b/doc/build/orm/extensions/asyncio.rst
index 09e76f2ee449f4f372445ed920ab19dbbc19c18e..aed01678af28ccfcfd7414e28418f3f525701d00 100644 (file)
--- a/doc/build/orm/extensions/asyncio.rst
+++ b/doc/build/orm/extensions/asyncio.rst
@@ -149,6 +149,8 @@ It is then used in a Python asynchronous context manager (i.e. ``async with:`` s
 so that it is automatically closed at the end of the block; this is equivalent
 to calling the :meth:`_asyncio.AsyncSession.close` method.
 
+.. _session_run_sync:
+
 Adapting ORM Lazy loads to asyncio
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

diff --git a/lib/sqlalchemy/ext/asyncio/engine.py b/lib/sqlalchemy/ext/asyncio/engine.py
index 5951abc1e997ab9b7b290b48b6b2ef65f1c38fba..829e89b71673889142fc3b0a111a401532c44854 100644 (file)
--- a/lib/sqlalchemy/ext/asyncio/engine.py
+++ b/lib/sqlalchemy/ext/asyncio/engine.py
@@ -448,6 +448,16 @@ class AsyncConnection(ProxyComparable, StartableContext, AsyncConnectable):
             with async_engine.begin() as conn:
                 await conn.run_sync(metadata.create_all)
 
+        .. 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`
         """
 
         conn = self._sync_connection()

diff --git a/lib/sqlalchemy/ext/asyncio/session.py b/lib/sqlalchemy/ext/asyncio/session.py
index 9a8284e64928382f29339b6abf24f6ea319b59d0..faa279cf9c0929d087f9ebf184243589e4789426 100644 (file)
--- 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)