bpo-33649: A copy-editing pass on asyncio documentation (GH-9376)
diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst
index 0489201..60aae16 100644
--- a/Doc/library/asyncio-stream.rst
+++ b/Doc/library/asyncio-stream.rst
@@ -54,7 +54,7 @@
:class:`StreamReader` and :class:`StreamWriter` classes.
The *loop* argument is optional and can always be determined
- automatically when this method is awaited from a coroutine.
+ automatically when this function is awaited from a coroutine.
*limit* determines the buffer size limit used by the
returned :class:`StreamReader` instance. By default the *limit*
@@ -84,7 +84,7 @@
*client_connected_cb* can be a plain callable or a
:ref:`coroutine function <coroutine>`; if it is a coroutine function,
- it will be automatically wrapped into a :class:`Task`.
+ it will be automatically scheduled as a :class:`Task`.
The *loop* argument is optional and can always be determined
automatically when this method is awaited from a coroutine.
@@ -107,14 +107,14 @@
limit=None, ssl=None, sock=None, \
server_hostname=None, ssl_handshake_timeout=None)
- Establish a UNIX socket connection and return a pair of
+ Establish a Unix socket connection and return a pair of
``(reader, writer)``.
- Similar to :func:`open_connection` but operates on UNIX sockets.
+ Similar to :func:`open_connection` but operates on Unix sockets.
See also the documentation of :meth:`loop.create_unix_connection`.
- Availability: UNIX.
+ Availability: Unix.
.. versionadded:: 3.7
@@ -130,13 +130,13 @@
backlog=100, ssl=None, ssl_handshake_timeout=None, \
start_serving=True)
- Start a UNIX socket server.
+ Start a Unix socket server.
- Similar to :func:`start_server` but works with UNIX sockets.
+ Similar to :func:`start_server` but works with Unix sockets.
See also the documentation of :meth:`loop.create_unix_server`.
- Availability: UNIX.
+ Availability: Unix.
.. versionadded:: 3.7
@@ -167,7 +167,7 @@
Read up to *n* bytes. If *n* is not provided, or set to ``-1``,
read until EOF and return all read bytes.
- If an EOF was received and the internal buffer is empty,
+ If EOF was received and the internal buffer is empty,
return an empty ``bytes`` object.
.. coroutinemethod:: readline()
@@ -175,41 +175,36 @@
Read one line, where "line" is a sequence of bytes
ending with ``\n``.
- If an EOF is received and ``\n`` was not found, the method
+ If EOF is received and ``\n`` was not found, the method
returns partially read data.
- If an EOF is received and the internal buffer is empty,
+ If EOF is received and the internal buffer is empty,
return an empty ``bytes`` object.
.. coroutinemethod:: readexactly(n)
Read exactly *n* bytes.
- Raise an :exc:`IncompleteReadError` if an EOF reached before *n*
+ Raise an :exc:`IncompleteReadError` if EOF is reached before *n*
can be read. Use the :attr:`IncompleteReadError.partial`
attribute to get the partially read data.
.. coroutinemethod:: readuntil(separator=b'\\n')
- Read data from the stream until ``separator`` is found.
+ Read data from the stream until *separator* is found.
On success, the data and separator will be removed from the
internal buffer (consumed). Returned data will include the
separator at the end.
- Configured stream limit is used to check result. Limit sets the
- maximal length of data that can be returned, not counting the
- separator.
+ If the amount of data read exceeds the configured stream limit, a
+ :exc:`LimitOverrunError` exception is raised, and the data
+ is left in the internal buffer and can be read again.
- If an EOF occurs and the complete separator is still not found,
- an :exc:`IncompleteReadError` exception will be
- raised, and the internal buffer will be reset. The
- :attr:`IncompleteReadError.partial` attribute may contain the
- separator partially.
-
- If the data cannot be read because of over limit, a
- :exc:`LimitOverrunError` exception will be raised, and the data
- will be left in the internal buffer, so it can be read again.
+ If EOF is reached before the complete separator is found,
+ an :exc:`IncompleteReadError` exception is raised, and the internal
+ buffer is reset. The :attr:`IncompleteReadError.partial` attribute
+ may contain a portion of the separator.
.. versionadded:: 3.5.2
@@ -235,8 +230,8 @@
Write *data* to the stream.
- The method respects control-flow, execution is paused if write
- buffer reaches high-water limit.
+ The method respects flow control, execution is paused if the write
+ buffer reaches the high watermark.
.. versionadded:: 3.8
@@ -244,7 +239,7 @@
Close the stream.
- Wait for finishing all closing actions, e.g. SSL shutdown for
+ Wait until all closing actions are complete, e.g. SSL shutdown for
secure sockets.
.. versionadded:: 3.8
@@ -272,28 +267,29 @@
Write *data* to the stream.
- This method doesn't apply control-flow. The call should be
- followed by :meth:`drain`.
+ 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 doesn't apply control-flow. The call should be
- followed by :meth:`drain`.
+ 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.
- E.g.::
+ Example::
writer.write(data)
await writer.drain()
- This is a flow-control method that interacts with the underlying
+ This is a flow control method that interacts with the underlying
IO write buffer. When the size of the buffer reaches
- the high-water limit, *drain()* blocks until the size of the
- buffer is drained down to the low-water limit and writing can
+ the high watermark, *drain()* blocks until the size of the
+ buffer is drained down to the low watermark and writing can
be resumed. When there is nothing to wait for, the :meth:`drain`
returns immediately.