summaryrefslogtreecommitdiffstats
path: root/Doc/library/asyncio-stream.rst
diff options
context:
space:
mode:
authorAndrew Svetlov <andrew.svetlov@gmail.com>2019-05-09 19:14:58 (GMT)
committerGitHub <noreply@github.com>2019-05-09 19:14:58 (GMT)
commita076e4f5e42b85664693191d04cfb33e2f9acfa5 (patch)
tree3b70de541e9e742bde047631a2db60078ad18e35 /Doc/library/asyncio-stream.rst
parent3b2f9ab31db81405650325920465378532ab2d78 (diff)
downloadcpython-a076e4f5e42b85664693191d04cfb33e2f9acfa5.zip
cpython-a076e4f5e42b85664693191d04cfb33e2f9acfa5.tar.gz
cpython-a076e4f5e42b85664693191d04cfb33e2f9acfa5.tar.bz2
bpo-36802: Drop awrite()/aclose(), support await write() and await close() instead (#13099)
Diffstat (limited to 'Doc/library/asyncio-stream.rst')
-rw-r--r--Doc/library/asyncio-stream.rst90
1 files changed, 59 insertions, 31 deletions
diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst
index e686a6a..e735b81 100644
--- a/Doc/library/asyncio-stream.rst
+++ b/Doc/library/asyncio-stream.rst
@@ -22,13 +22,13 @@ streams::
'127.0.0.1', 8888)
print(f'Send: {message!r}')
- await writer.awrite(message.encode())
+ await writer.write(message.encode())
data = await reader.read(100)
print(f'Received: {data.decode()!r}')
print('Close the connection')
- await writer.aclose()
+ await writer.close()
asyncio.run(tcp_echo_client('Hello World!'))
@@ -226,23 +226,70 @@ StreamWriter
directly; use :func:`open_connection` and :func:`start_server`
instead.
- .. coroutinemethod:: awrite(data)
+ .. method:: write(data)
+
+ The method attempts to write the *data* to the underlying socket immediately.
+ If that fails, the data is queued in an internal write buffer until it can be
+ sent.
+
+ Starting with Python 3.8, it is possible to directly await on the `write()`
+ method::
+
+ await stream.write(data)
+
+ The ``await`` pauses the current coroutine until the data is written to the
+ socket.
+
+ Below is an equivalent code that works with Python <= 3.7::
+
+ stream.write(data)
+ await stream.drain()
+
+ .. versionchanged:: 3.8
+ Support ``await stream.write(...)`` syntax.
+
+ .. method:: writelines(data)
+
+ The method writes a list (or any iterable) of bytes to the underlying socket
+ immediately.
+ If that fails, the data is queued in an internal write buffer until it can be
+ sent.
+
+ Starting with Python 3.8, it is possible to directly await on the `write()`
+ method::
+
+ await stream.writelines(lines)
+
+ The ``await`` pauses the current coroutine until the data is written to the
+ socket.
+
+ Below is an equivalent code that works with Python <= 3.7::
- Write *data* to the stream.
+ stream.writelines(lines)
+ await stream.drain()
- The method respects flow control, execution is paused if the write
- buffer reaches the high watermark.
+ .. versionchanged:: 3.8
+ Support ``await stream.writelines()`` syntax.
- .. versionadded:: 3.8
+ .. method:: close()
+
+ The method closes the stream and the underlying socket.
+
+ Starting with Python 3.8, it is possible to directly await on the `close()`
+ method::
+
+ await stream.close()
- .. coroutinemethod:: aclose()
+ The ``await`` pauses the current coroutine until the stream and the underlying
+ socket are closed (and SSL shutdown is performed for a secure connection).
- Close the stream.
+ Below is an equivalent code that works with Python <= 3.7::
- Wait until all closing actions are complete, e.g. SSL shutdown for
- secure sockets.
+ stream.close()
+ await stream.wait_closed()
- .. versionadded:: 3.8
+ .. versionchanged:: 3.8
+ Support ``await stream.close()`` syntax.
.. method:: can_write_eof()
@@ -263,21 +310,6 @@ StreamWriter
Access optional transport information; see
:meth:`BaseTransport.get_extra_info` for details.
- .. method:: write(data)
-
- Write *data* to the stream.
-
- This method is not subject to flow control. Calls to ``write()`` should
- be followed by :meth:`drain`. The :meth:`awrite` method is a
- recommended alternative the applies flow control automatically.
-
- .. method:: writelines(data)
-
- Write a list (or any iterable) of bytes to the stream.
-
- This method is not subject to flow control. Calls to ``writelines()``
- should be followed by :meth:`drain`.
-
.. coroutinemethod:: drain()
Wait until it is appropriate to resume writing to the stream.
@@ -293,10 +325,6 @@ StreamWriter
be resumed. When there is nothing to wait for, the :meth:`drain`
returns immediately.
- .. method:: close()
-
- Close the stream.
-
.. method:: is_closing()
Return ``True`` if the stream is closed or in the process of