From a54ab6944e66830d99d7fd09a82766c392731920 Mon Sep 17 00:00:00 2001
From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Wed, 26 Apr 2023 15:32:56 -0400
Subject: write out a full doc for both run_sync methods

Fixes: #9705
Change-Id: I705463b9984f207f2268da6ebd80f07b68aa08f0
---
 lib/sqlalchemy/ext/asyncio/engine.py | 45 +++++++++++++++++++++++++++++++++---
 1 file changed, 42 insertions(+), 3 deletions(-)

(limited to 'lib/sqlalchemy/ext/asyncio/engine.py')

diff --git a/lib/sqlalchemy/ext/asyncio/engine.py b/lib/sqlalchemy/ext/asyncio/engine.py
index 6dfca463f..531abdde5 100644
--- a/lib/sqlalchemy/ext/asyncio/engine.py
+++ b/lib/sqlalchemy/ext/asyncio/engine.py
@@ -776,14 +776,50 @@ class AsyncConnection(
     async def run_sync(
         self, fn: Callable[..., Any], *arg: Any, **kw: Any
     ) -> Any:
-        """Invoke the given sync callable passing self as the first argument.
+        """Invoke the given synchronous (i.e. not async) callable,
+        passing a synchronous-style :class:`_engine.Connection` as the first
+        argument.
+
+        This method allows traditional synchronous SQLAlchemy functions to
+        run within the context of an asyncio application.
+
+        E.g.::
+
+            def do_something_with_core(conn: Connection, arg1: int, arg2: str) -> str:
+                '''A synchronous function that does not require awaiting
+
+                :param conn: a Core SQLAlchemy Connection, used synchronously
+
+                :return: an optional return value is supported
+
+                '''
+                conn.execute(
+                    some_table.insert().values(int_col=arg1, str_col=arg2)
+                )
+                return "success"
+
+
+            async def do_something_async(async_engine: AsyncEngine) -> None:
+                '''an async function that uses awaiting'''
+
+                async with async_engine.begin() as async_conn:
+                    # run do_something_with_core() with a sync-style
+                    # Connection, proxied into an awaitable
+                    return_code = await async_conn.run_sync(do_something_with_core, 5, "strval")
+                    print(return_code)
 
         This method maintains the asyncio event loop all the way through
         to the database connection by running the given callable in a
         specially instrumented greenlet.
 
-        E.g.::
+        The most rudimentary use of :meth:`.AsyncConnection.run_sync` is to
+        invoke methods such as :meth:`_schema.MetaData.create_all`, given
+        an :class:`.AsyncConnection` that needs to be provided to
+        :meth:`_schema.MetaData.create_all` as a :class:`_engine.Connection`
+        object::
 
+            # run metadata.create_all(conn) with a sync-style Connection,
+            # proxied into an awaitable
             with async_engine.begin() as conn:
                 await conn.run_sync(metadata.create_all)
 
@@ -796,8 +832,11 @@ class AsyncConnection(
 
         .. seealso::
 
+            :meth:`.AsyncSession.run_sync`
+
             :ref:`session_run_sync`
-        """
+
+        """  # noqa: E501
 
         return await greenlet_spawn(fn, self._proxied, *arg, **kw)
 
-- 
cgit v1.2.1