bpo-34666: Implement stream.awrite() and stream.aclose() (GH-9274)

1 files changed, 45 insertions, 21 deletions

diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst
index 0cfecda..80b7625 100644
--- a/Doc/library/asyncio-stream.rst
+++ b/Doc/library/asyncio-stream.rst
@@ -20,13 +20,13 @@ streams::
             '127.0.0.1', 8888)
 
         print(f'Send: {message!r}')
-        writer.write(message.encode())
+        await writer.awrite(message.encode())
 
         data = await reader.read(100)
         print(f'Received: {data.decode()!r}')
 
         print('Close the connection')
-        writer.close()
+        await writer.aclose()
 
     asyncio.run(tcp_echo_client('Hello World!'))
 
@@ -229,14 +229,57 @@ StreamWriter
    directly; use :func:`open_connection` and :func:`start_server`
    instead.
 
+   .. coroutinemethod:: awrite(data)
+
+      Write *data* to the stream.
+
+      The method respects control-flow, execution is paused if write
+      buffer reaches high-water limit.
+
+      .. versionadded:: 3.8
+
+   .. coroutinemethod:: aclose()
+
+      Close the stream.
+
+      Wait for finishing all closing actions, e.g. SSL shutdown for
+      secure sockets.
+
+      .. versionadded:: 3.8
+
+   .. method:: can_write_eof()
+
+      Return *True* if the underlying transport supports
+      the :meth:`write_eof` method, *False* otherwise.
+
+   .. method:: write_eof()
+
+      Close the write end of the stream after the buffered write
+      data is flushed.
+
+   .. attribute:: transport
+
+      Return the underlying asyncio transport.
+
+   .. method:: get_extra_info(name, default=None)
+
+      Access optional transport information; see
+      :meth:`BaseTransport.get_extra_info` for details.
+
    .. method:: write(data)
 
       Write *data* to the stream.
 
+      This method doesn't apply control-flow. The call should be
+      followed by :meth:`drain`.
+
    .. method:: writelines(data)
 
       Write a list (or any iterable) of bytes to the stream.
 
+      This method doesn't apply control-flow. The call should be
+      followed by :meth:`drain`.
+
    .. coroutinemethod:: drain()
 
       Wait until it is appropriate to resume writing to the stream.
@@ -272,25 +315,6 @@ StreamWriter
 
       .. versionadded:: 3.7
 
-   .. method:: can_write_eof()
-
-      Return *True* if the underlying transport supports
-      the :meth:`write_eof` method, *False* otherwise.
-
-   .. method:: write_eof()
-
-      Close the write end of the stream after the buffered write
-      data is flushed.
-
-   .. attribute:: transport
-
-      Return the underlying asyncio transport.
-
-   .. method:: get_extra_info(name, default=None)
-
-      Access optional transport information; see
-      :meth:`BaseTransport.get_extra_info` for details.
-
 
 Examples
 ========