bpo-36802: Drop awrite()/aclose(), support await write() and await close() instead (#13099)

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)
 
-      Write *data* to the stream.
+      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.
 
-      The method respects flow control, execution is paused if the write
-      buffer reaches the high watermark.
+      Starting with Python 3.8, it is possible to directly await on the `write()`
+      method::
 
-      .. versionadded:: 3.8
+         await stream.write(data)
 
-   .. coroutinemethod:: aclose()
+      The ``await`` pauses the current coroutine until the data is written to the
+      socket.
 
-      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.write(data)
+         await stream.drain()
 
-      .. versionadded:: 3.8
+      .. 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::
+
+         stream.writelines(lines)
+         await stream.drain()
+
+      .. versionchanged:: 3.8
+         Support ``await stream.writelines()`` syntax.
+
+   .. 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()
+
+      The ``await`` pauses the current coroutine until the stream and the underlying
+      socket are closed (and SSL shutdown is performed for a secure connection).
+
+      Below is an equivalent code that works with Python <= 3.7::
+
+         stream.close()
+         await stream.wait_closed()
+
+      .. 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