write out a full doc for both run_sync methods

Fixes: #9705
Change-Id: I705463b9984f207f2268da6ebd80f07b68aa08f0

1 files changed, 32 insertions, 7 deletions

diff --git a/lib/sqlalchemy/ext/asyncio/session.py b/lib/sqlalchemy/ext/asyncio/session.py
index dabe1824e..d819f546c 100644
--- a/lib/sqlalchemy/ext/asyncio/session.py
+++ b/lib/sqlalchemy/ext/asyncio/session.py
@@ -233,17 +233,40 @@ class AsyncSession(ReversibleProxy[Session]):
     async def run_sync(
         self, fn: Callable[..., Any], *arg: Any, **kw: Any
     ) -> Any:
-        """Invoke the given sync callable passing sync self as the first
+        """Invoke the given synchronous (i.e. not async) callable,
+        passing a synchronous-style :class:`_orm.Session` as the first
         argument.
 
-        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.
+        This method allows traditional synchronous SQLAlchemy functions to
+        run within the context of an asyncio application.
 
         E.g.::
 
-            with AsyncSession(async_engine) as session:
-                await session.run_sync(some_business_method)
+            def some_business_method(session: Session, param: str) -> str:
+                '''A synchronous function that does not require awaiting
+
+                :param session: a SQLAlchemy Session, used synchronously
+
+                :return: an optional return value is supported
+
+                '''
+                session.add(MyObject(param=param))
+                session.flush()
+                return "success"
+
+
+            async def do_something_async(async_engine: AsyncEngine) -> None:
+                '''an async function that uses awaiting'''
+
+                with AsyncSession(async_engine) as async_session:
+                    # run some_business_method() with a sync-style
+                    # Session, proxied into an awaitable
+                    return_code = await async_session.run_sync(some_business_method, param="param1")
+                    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.
 
         .. note::
 
@@ -254,8 +277,10 @@ class AsyncSession(ReversibleProxy[Session]):
 
         .. seealso::
 
+            :meth:`.AsyncConnection.run_sync`
+
             :ref:`session_run_sync`
-        """
+        """  # noqa: E501
 
         return await greenlet_spawn(fn, self.sync_session, *arg, **kw)