diff options
author | Andrew Svetlov <andrew.svetlov@gmail.com> | 2019-05-09 19:14:58 (GMT) |
---|---|---|
committer | GitHub <noreply@github.com> | 2019-05-09 19:14:58 (GMT) |
commit | a076e4f5e42b85664693191d04cfb33e2f9acfa5 (patch) | |
tree | 3b70de541e9e742bde047631a2db60078ad18e35 /Doc/library/asyncio-stream.rst | |
parent | 3b2f9ab31db81405650325920465378532ab2d78 (diff) | |
download | cpython-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.rst | 90 |
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 |