bpo-32258: Replace 'yield from' to 'await' in asyncio docs (#4779)
* Replace 'yield from' to 'await' in asyncio docs
* Fix docstrings
diff --git a/Doc/library/asyncio-dev.rst b/Doc/library/asyncio-dev.rst
index b9735de..100fff5 100644
--- a/Doc/library/asyncio-dev.rst
+++ b/Doc/library/asyncio-dev.rst
@@ -81,12 +81,11 @@
If you wait for a future, you should check early if the future was cancelled to
avoid useless operations. Example::
- @coroutine
- def slow_operation(fut):
+ async def slow_operation(fut):
if fut.cancelled():
return
# ... slow computation ...
- yield from fut
+ await fut
# ...
The :func:`shield` function can also be used to ignore cancellation.
@@ -99,7 +98,7 @@
An event loop runs in a thread and executes all callbacks and tasks in the same
thread. While a task is running in the event loop, no other task is running in
-the same thread. But when the task uses ``yield from``, the task is suspended
+the same thread. But when the task uses ``await``, the task is suspended
and the event loop executes the next task.
To schedule a callback from a different thread, the
@@ -192,8 +191,7 @@
import asyncio
- @asyncio.coroutine
- def test():
+ async def test():
print("never scheduled")
test()
@@ -270,10 +268,9 @@
There are different options to fix this issue. The first option is to chain the
coroutine in another coroutine and use classic try/except::
- @asyncio.coroutine
- def handle_exception():
+ async def handle_exception():
try:
- yield from bug()
+ await bug()
except Exception:
print("exception consumed")
@@ -300,7 +297,7 @@
--------------------------
When a coroutine function calls other coroutine functions and tasks, they
-should be chained explicitly with ``yield from``. Otherwise, the execution is
+should be chained explicitly with ``await``. Otherwise, the execution is
not guaranteed to be sequential.
Example with different bugs using :func:`asyncio.sleep` to simulate slow
@@ -308,26 +305,22 @@
import asyncio
- @asyncio.coroutine
- def create():
- yield from asyncio.sleep(3.0)
+ async def create():
+ await asyncio.sleep(3.0)
print("(1) create file")
- @asyncio.coroutine
- def write():
- yield from asyncio.sleep(1.0)
+ async def write():
+ await asyncio.sleep(1.0)
print("(2) write into file")
- @asyncio.coroutine
- def close():
+ async def close():
print("(3) close file")
- @asyncio.coroutine
- def test():
+ async def test():
asyncio.ensure_future(create())
asyncio.ensure_future(write())
asyncio.ensure_future(close())
- yield from asyncio.sleep(2.0)
+ await asyncio.sleep(2.0)
loop.stop()
loop = asyncio.get_event_loop()
@@ -359,24 +352,22 @@
before ``write()``, whereas coroutine functions were called in this order:
``create()``, ``write()``, ``close()``.
-To fix the example, tasks must be marked with ``yield from``::
+To fix the example, tasks must be marked with ``await``::
- @asyncio.coroutine
- def test():
- yield from asyncio.ensure_future(create())
- yield from asyncio.ensure_future(write())
- yield from asyncio.ensure_future(close())
- yield from asyncio.sleep(2.0)
+ async def test():
+ await asyncio.ensure_future(create())
+ await asyncio.ensure_future(write())
+ await asyncio.ensure_future(close())
+ await asyncio.sleep(2.0)
loop.stop()
Or without ``asyncio.ensure_future()``::
- @asyncio.coroutine
- def test():
- yield from create()
- yield from write()
- yield from close()
- yield from asyncio.sleep(2.0)
+ async def test():
+ await create()
+ await write()
+ await close()
+ await asyncio.sleep(2.0)
loop.stop()
diff --git a/Doc/library/asyncio-protocol.rst b/Doc/library/asyncio-protocol.rst
index af46200..a4b0d59 100644
--- a/Doc/library/asyncio-protocol.rst
+++ b/Doc/library/asyncio-protocol.rst
@@ -488,8 +488,9 @@
but there is no guarantee made about the execution order. Protocols are not
aware of coroutines created in protocol methods and so will not wait for them.
-To have a reliable execution order, use :ref:`stream objects <asyncio-streams>` in a
-coroutine with ``yield from``. For example, the :meth:`StreamWriter.drain`
+To have a reliable execution order,
+use :ref:`stream objects <asyncio-streams>` in a
+coroutine with ``await``. For example, the :meth:`StreamWriter.drain`
coroutine can be used to wait until the write buffer is flushed.
@@ -589,7 +590,7 @@
:meth:`Transport.close` can be called immediately after
:meth:`WriteTransport.write` even if data are not sent yet on the socket: both
-methods are asynchronous. ``yield from`` is not needed because these transport
+methods are asynchronous. ``await`` is not needed because these transport
methods are not coroutines.
.. seealso::
diff --git a/Doc/library/asyncio-queue.rst b/Doc/library/asyncio-queue.rst
index ea78755..65497f2 100644
--- a/Doc/library/asyncio-queue.rst
+++ b/Doc/library/asyncio-queue.rst
@@ -24,7 +24,7 @@
A queue, useful for coordinating producer and consumer coroutines.
If *maxsize* is less than or equal to zero, the queue size is infinite. If
- it is an integer greater than ``0``, then ``yield from put()`` will block
+ it is an integer greater than ``0``, then ``await put()`` will block
when the queue reaches *maxsize*, until an item is removed by :meth:`get`.
Unlike the standard library :mod:`queue`, you can reliably know this Queue's
diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst
index 78091d6..6d5cbbc 100644
--- a/Doc/library/asyncio-stream.rst
+++ b/Doc/library/asyncio-stream.rst
@@ -208,7 +208,7 @@
The intended use is to write::
w.write(data)
- yield from w.drain()
+ await w.drain()
When the size of the transport buffer reaches the high-water limit (the
protocol is paused), block until the size of the buffer is drained down
@@ -301,15 +301,14 @@
import asyncio
- @asyncio.coroutine
- def tcp_echo_client(message, loop):
- reader, writer = yield from asyncio.open_connection('127.0.0.1', 8888,
- loop=loop)
+ async def tcp_echo_client(message, loop):
+ reader, writer = await asyncio.open_connection('127.0.0.1', 8888,
+ loop=loop)
print('Send: %r' % message)
writer.write(message.encode())
- data = yield from reader.read(100)
+ data = await reader.read(100)
print('Received: %r' % data.decode())
print('Close the socket')
@@ -335,16 +334,15 @@
import asyncio
- @asyncio.coroutine
- def handle_echo(reader, writer):
- data = yield from reader.read(100)
+ async def handle_echo(reader, writer):
+ data = await reader.read(100)
message = data.decode()
addr = writer.get_extra_info('peername')
print("Received %r from %r" % (message, addr))
print("Send: %r" % message)
writer.write(data)
- yield from writer.drain()
+ await writer.drain()
print("Close the client socket")
writer.close()
@@ -387,13 +385,13 @@
connect = asyncio.open_connection(url.hostname, 443, ssl=True)
else:
connect = asyncio.open_connection(url.hostname, 80)
- reader, writer = yield from connect
+ reader, writer = await connect
query = ('HEAD {path} HTTP/1.0\r\n'
'Host: {hostname}\r\n'
'\r\n').format(path=url.path or '/', hostname=url.hostname)
writer.write(query.encode('latin-1'))
while True:
- line = yield from reader.readline()
+ line = await reader.readline()
if not line:
break
line = line.decode('latin1').rstrip()
@@ -428,19 +426,18 @@
import asyncio
from socket import socketpair
- @asyncio.coroutine
- def wait_for_data(loop):
+ async def wait_for_data(loop):
# Create a pair of connected sockets
rsock, wsock = socketpair()
# Register the open socket to wait for data
- reader, writer = yield from asyncio.open_connection(sock=rsock, loop=loop)
+ reader, writer = await asyncio.open_connection(sock=rsock, loop=loop)
# Simulate the reception of data from the network
loop.call_soon(wsock.send, 'abc'.encode())
# Wait for data
- data = yield from reader.read(100)
+ data = await reader.read(100)
# Got data, we are done: close the socket
print("Received:", data.decode())
diff --git a/Doc/library/asyncio-subprocess.rst b/Doc/library/asyncio-subprocess.rst
index 1c1d0be..280b764 100644
--- a/Doc/library/asyncio-subprocess.rst
+++ b/Doc/library/asyncio-subprocess.rst
@@ -347,21 +347,20 @@
def process_exited(self):
self.exit_future.set_result(True)
- @asyncio.coroutine
- def get_date(loop):
+ async def get_date(loop):
code = 'import datetime; print(datetime.datetime.now())'
exit_future = asyncio.Future(loop=loop)
# Create the subprocess controlled by the protocol DateProtocol,
# redirect the standard output into a pipe
- create = loop.subprocess_exec(lambda: DateProtocol(exit_future),
- sys.executable, '-c', code,
- stdin=None, stderr=None)
- transport, protocol = yield from create
+ transport, protocol = await loop.subprocess_exec(
+ lambda: DateProtocol(exit_future),
+ sys.executable, '-c', code,
+ stdin=None, stderr=None)
# Wait for the subprocess exit using the process_exited() method
# of the protocol
- yield from exit_future
+ await exit_future
# Close the stdout pipe
transport.close()
@@ -398,16 +397,16 @@
code = 'import datetime; print(datetime.datetime.now())'
# Create the subprocess, redirect the standard output into a pipe
- create = asyncio.create_subprocess_exec(sys.executable, '-c', code,
- stdout=asyncio.subprocess.PIPE)
- proc = yield from create
+ proc = await asyncio.create_subprocess_exec(
+ sys.executable, '-c', code,
+ stdout=asyncio.subprocess.PIPE)
# Read one line of output
- data = yield from proc.stdout.readline()
+ data = await proc.stdout.readline()
line = data.decode('ascii').rstrip()
# Wait for the subprocess exit
- yield from proc.wait()
+ await proc.wait()
return line
if sys.platform == "win32":
diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst
index 3656f79..a8a0a8e 100644
--- a/Doc/library/asyncio-task.rst
+++ b/Doc/library/asyncio-task.rst
@@ -515,7 +515,7 @@
Example::
for f in as_completed(fs):
- result = yield from f # The 'yield from' may raise
+ result = await f # The 'await' may raise
# Use result
.. note::
@@ -630,11 +630,11 @@
The statement::
- res = yield from shield(something())
+ res = await shield(something())
is exactly equivalent to the statement::
- res = yield from something()
+ res = await something()
*except* that if the coroutine containing it is cancelled, the task running
in ``something()`` is not cancelled. From the point of view of
@@ -647,7 +647,7 @@
combine ``shield()`` with a try/except clause, as follows::
try:
- res = yield from shield(something())
+ res = await shield(something())
except CancelledError:
res = None
@@ -690,7 +690,7 @@
Usage::
- done, pending = yield from asyncio.wait(fs)
+ done, pending = await asyncio.wait(fs)
.. note::
@@ -714,7 +714,7 @@
This function is a :ref:`coroutine <coroutine>`, usage::
- result = yield from asyncio.wait_for(fut, 60.0)
+ result = await asyncio.wait_for(fut, 60.0)
.. versionchanged:: 3.4.3
If the wait is cancelled, the future *fut* is now also cancelled.