Fix asyncio.to_thread() documented return type (GH-20547)

When I wrote the documentation for `asyncio.to_thread()`, I mistakenly assumed that `return await loop.run_in_executor(...)` within an async def function would return a Future. In reality, it returns a coroutine.

This likely won't affect typical usage of `asyncio.to_thread()`, but it's important for the documentation to be correct here. In general, we also tend to avoid returning futures from high-level APIs in asyncio.

Author: aeros

Doc/library/asyncio-task.rst

@@ -614,8 +614,7 @@ Running in Threads
    allowing context variables from the event loop thread to be accessed in the
    separate thread.
 
-   Return an :class:`asyncio.Future` which represents the eventual result of
-   *func*.
+   Return a coroutine that can be awaited to get the eventual result of *func*.
 
    This coroutine function is primarily intended to be used for executing
    IO-bound functions/methods that would otherwise block the event loop if

Lib/asyncio/threads.py

@@ -17,7 +17,7 @@ async def to_thread(func, /, *args, **kwargs):
     allowing context variables from the main thread to be accessed in the
     separate thread.
 
-    Return an asyncio.Future which represents the eventual result of *func*.
+    Return a coroutine that can be awaited to get the eventual result of *func*.
     """
     loop = events.get_running_loop()
     ctx = contextvars.copy_context()