From d26c968a99aa7777c2a0e97e6d8fe77bc0cae9c3 Mon Sep 17 00:00:00 2001 From: Jakub Stasiak Date: Sun, 1 Nov 2020 13:17:50 +0100 Subject: [PATCH] bpo-42230: Improve asyncio documentation regarding accepting sets vs iterables People call wait() and as_completed() with various non-set iterables, a list should be the most common but there are others as well[1]. Considering typeshed also documents wait()[2] and as_completed()[3] as accepting arbitrary iterables I think it's a good idea to document the status quo better. [1] https://github.com/aio-libs/aiokafka/pull/672 [2] https://github.com/python/typeshed/blob/620989bac572f30349b95590ebe81a73ce0fe862/stdlib/3/asyncio/tasks.pyi#L161 [3] https://github.com/python/typeshed/blob/620989bac572f30349b95590ebe81a73ce0fe862/stdlib/3/asyncio/tasks.pyi#L40 --- Doc/library/asyncio-task.rst | 8 ++++---- Lib/asyncio/tasks.py | 4 ++-- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst index 99f012540d989b..eb51c704cea394 100644 --- a/Doc/library/asyncio-task.rst +++ b/Doc/library/asyncio-task.rst @@ -504,10 +504,10 @@ Waiting Primitives return_when=ALL_COMPLETED) Run :ref:`awaitable objects ` in the *aws* - set concurrently and block until the condition specified + iterable concurrently and block until the condition specified by *return_when*. - The *aws* set must not be empty. + The *aws* iterable must not be empty. Returns two sets of Tasks/Futures: ``(done, pending)``. @@ -593,9 +593,9 @@ Waiting Primitives .. function:: as_completed(aws, \*, loop=None, timeout=None) Run :ref:`awaitable objects ` in the *aws* - set concurrently. Return an iterator of coroutines. + iterable concurrently. Return an iterator of coroutines. Each coroutine returned can be awaited to get the earliest next - result from the set of the remaining awaitables. + result from the iterable of the remaining awaitables. Raises :exc:`asyncio.TimeoutError` if the timeout occurs before all Futures are done. diff --git a/Lib/asyncio/tasks.py b/Lib/asyncio/tasks.py index 8b05434f273b52..ad31f5d59796b1 100644 --- a/Lib/asyncio/tasks.py +++ b/Lib/asyncio/tasks.py @@ -373,7 +373,7 @@ def create_task(coro, *, name=None): async def wait(fs, *, loop=None, timeout=None, return_when=ALL_COMPLETED): """Wait for the Futures and coroutines given by fs to complete. - The sequence futures must not be empty. + The fs iterable must not be empty. Coroutines will be wrapped in Tasks. @@ -573,7 +573,7 @@ def as_completed(fs, *, loop=None, timeout=None): Note: The futures 'f' are not necessarily members of fs. """ if futures.isfuture(fs) or coroutines.iscoroutine(fs): - raise TypeError(f"expect a list of futures, not {type(fs).__name__}") + raise TypeError(f"expect an iterable of futures, not {type(fs).__name__}") from .queues import Queue # Import here to avoid circular import problem. done = Queue(loop=loop)