From: Federico Caselli <cfederico87@gmail.com>
Date: Wed, 6 Jan 2021 09:46:29 +0000 (+0100)
Subject: Improve ``run_sync`` documentation in asyncio ext
X-Git-Tag: rel_1_4_0b2~60
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=97cb27777aff9797c16271022f104f39c38f2418;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

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 09e76f2ee4..aed01678af 100644
--- 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 5951abc1e9..829e89b716 100644
--- 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 9a8284e649..faa279cf9c 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)