[Python-checkins] bpo-34790: [docs] Passing coroutines to asyncio.wait() can be confusing. (GH-9543)

[Miss Islington (bot)]

https://github.com/python/cpython/commit/3cc9557d9f03086fa3b0ea166f8506087e6950e3
commit: 3cc9557d9f03086fa3b0ea166f8506087e6950e3
branch: 3.7
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: GitHub <noreply at github.com>
date: 2018-09-25T11:57:49-07:00
summary:

bpo-34790: [docs] Passing coroutines to asyncio.wait() can be confusing. (GH-9543)

(cherry picked from commit 996859a90df51f84eab47351702cb59c6db4428a)

Co-authored-by: Yury Selivanov <yury at magic.io>

files:
A Misc/NEWS.d/next/Documentation/2018-09-24-12-47-08.bpo-34790.G2KXIH.rst
M Doc/library/asyncio-task.rst

diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst
index bdb475a797db..7fbfd426dba6 100644
--- a/Doc/library/asyncio-task.rst
+++ b/Doc/library/asyncio-task.rst
@@ -466,14 +466,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.
 
@@ -508,9 +514,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 000000000000..dc3de2c7d4c8
--- /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.