diff options
| -rw-r--r-- | Doc/library/asyncio-task.rst | 40 | ||||
| -rw-r--r-- | Misc/NEWS.d/next/Documentation/2018-09-24-12-47-08.bpo-34790.G2KXIH.rst | 1 |
2 files changed, 37 insertions, 4 deletions
diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst index e995fb6..bb693d7 100644 --- a/Doc/library/asyncio-task.rst +++ b/Doc/library/asyncio-task.rst @@ -472,14 +472,20 @@ Waiting Primitives return_when=ALL_COMPLETED) Run :ref:`awaitable objects <asyncio-awaitables>` in the *aws* - sequence concurrently and block until the condition specified + set concurrently and block until the condition specified by *return_when*. If any awaitable in *aws* is a coroutine, it is automatically - scheduled as a Task. + scheduled as a Task. Passing coroutines objects to + ``wait()`` directly is deprecated as it leads to + :ref:`confusing behavior <asyncio_example_wait_coroutine>`. Returns two sets of Tasks/Futures: ``(done, pending)``. + Usage:: + + done, pending = await asyncio.wait(aws) + The *loop* argument is deprecated and scheduled for removal in Python 4.0. @@ -514,9 +520,35 @@ Waiting Primitives Unlike :func:`~asyncio.wait_for`, ``wait()`` does not cancel the futures when a timeout occurs. - Usage:: + .. _asyncio_example_wait_coroutine: + .. note:: - done, pending = await asyncio.wait(aws) + ``wait()`` schedules coroutines as Tasks automatically and later + returns those implicitly created Task objects in ``(done, pending)`` + sets. Therefore the following code won't work as expected:: + + async def foo(): + return 42 + + coro = foo() + done, pending = await asyncio.wait({coro}) + + if coro in done: + # This branch will never be run! + + Here is how the above snippet can be fixed:: + + async def foo(): + return 42 + + task = asyncio.create_task(foo()) + done, pending = await asyncio.wait({task}) + + if task in done: + # Everything will work as expected now. + + Passing coroutine objects to ``wait()`` directly is + deprecated. .. function:: as_completed(aws, \*, loop=None, timeout=None) diff --git a/Misc/NEWS.d/next/Documentation/2018-09-24-12-47-08.bpo-34790.G2KXIH.rst b/Misc/NEWS.d/next/Documentation/2018-09-24-12-47-08.bpo-34790.G2KXIH.rst new file mode 100644 index 0000000..dc3de2c --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2018-09-24-12-47-08.bpo-34790.G2KXIH.rst @@ -0,0 +1 @@ +Document how passing coroutines to asyncio.wait() can be confusing. |