bpo-33649: A copy-editing pass on asyncio documentation (GH-9376)

1 files changed, 165 insertions, 162 deletions

diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst
index 909d3ea3..0320d79 100644
--- a/Doc/library/asyncio-eventloop.rst
+++ b/Doc/library/asyncio-eventloop.rst
@@ -8,20 +8,17 @@ Event Loop
 
 .. rubric:: Preface
 
-The event loop is a central component of every asyncio application.
+The event loop is the core of every asyncio application.
 Event loops run asynchronous tasks and callbacks, perform network
 IO operations, and run subprocesses.
 
-Application developers will typically use high-level asyncio functions
-to interact with the event loop. In general, high-level asyncio applications
-should not need to work directly with event loops and, instead, should use
-the :func:`asyncio.run` function to initialize, manage the event loop, and
-run asynchronous code.
+Application developers should typically use the high-level asyncio functions,
+such as :func:`asyncio.run`, and should rarely need to reference the loop
+object or call its methods.  This section is intended mostly for authors
+of lower-level code, libraries, and frameworks, who need finer control over
+the event loop behavior.
 
-Alternatively, developers of low-level code, such as libraries and
-framework, may need access to the event loop.
-
-.. rubric:: Accessing Event Loop
+.. rubric:: Obtaining the Event Loop
 
 The following low-level functions can be used to get, set, or create
 an event loop:
@@ -68,16 +65,16 @@ and :func:`new_event_loop` functions can be altered by
 This documentation page contains the following sections:
 
 * The `Event Loop Methods`_ section is the reference documentation of
-  event loop APIs;
+  the event loop APIs;
 
 * The `Callback Handles`_ section documents the :class:`Handle` and
-  :class:`TimerHandle`, instances which are returned from functions, such
-  as :meth:`loop.call_soon` and :meth:`loop.call_later`;
+  :class:`TimerHandle` instances which are returned from scheduling
+  methods such as :meth:`loop.call_soon` and :meth:`loop.call_later`;
 
-* The `Server Objects`_ sections document types returned from
+* The `Server Objects`_ section documents types returned from
   event loop methods like :meth:`loop.create_server`;
 
-* The `Event Loops Implementations`_ section documents the
+* The `Event Loop Implementations`_ section documents the
   :class:`SelectorEventLoop` and :class:`ProactorEventLoop` classes;
 
 * The `Examples`_ section showcases how to work with some event
@@ -101,11 +98,11 @@ Running and stopping the loop
 
 .. method:: loop.run_until_complete(future)
 
-   Run until the *future* (an instance of :class:`Future`) is
+   Run until the *future* (an instance of :class:`Future`) has
    completed.
 
    If the argument is a :ref:`coroutine object <coroutine>` it
-   is implicitly wrapped into an :class:`asyncio.Task`.
+   is implicitly scheduled to run as a :class:`asyncio.Task`.
 
    Return the Future's result or raise its exception.
 
@@ -120,7 +117,7 @@ Running and stopping the loop
 
    If :meth:`stop` is called while :meth:`run_forever` is running,
    the loop will run the current batch of callbacks and then exit.
-   Note that callbacks scheduled by callbacks will not run in this
+   Note that new callbacks scheduled by callbacks will not run in this
    case; instead, they will run the next time :meth:`run_forever` or
    :meth:`run_until_complete` is called.
 
@@ -167,8 +164,6 @@ Running and stopping the loop
    .. versionadded:: 3.6
 
 
-.. _asyncio-pass-keywords:
-
 Scheduling callbacks
 ^^^^^^^^^^^^^^^^^^^^
 
@@ -201,18 +196,19 @@ Scheduling callbacks
    The *context* keyword-only parameter was added. See :pep:`567`
    for more details.
 
+.. _asyncio-pass-keywords:
+
 .. note::
 
    Most :mod:`asyncio` scheduling functions don't allow passing
-   keyword arguments.  To do that, use :func:`functools.partial`,
-   e.g.::
+   keyword arguments.  To do that, use :func:`functools.partial`::
 
       # will schedule "print("Hello", flush=True)"
       loop.call_soon(
           functools.partial(print, "Hello", flush=True))
 
    Using partial objects is usually more convenient than using lambdas,
-   as asyncio can better render partial objects in debug and error
+   as asyncio can render partial objects better in debug and error
    messages.
 
 
@@ -235,8 +231,8 @@ clocks to track time.
    be used to cancel the callback.
 
    *callback* will be called exactly once.  If two callbacks are
-   scheduled for exactly the same time, it is undefined which one will
-   be called first.
+   scheduled for exactly the same time, the order in which they
+   are called is undefined.
 
    The optional positional *args* will be passed to the callback when
    it is called. If you want the callback to be called with keyword
@@ -250,6 +246,11 @@ clocks to track time.
       The *context* keyword-only parameter was added. See :pep:`567`
       for more details.
 
+   .. versionchanged:: 3.8
+      In Python 3.7 and earlier with the default event loop implementation,
+      the *delay* could not exceed one day.
+      This has been fixed in Python 3.8.
+
 .. method:: loop.call_at(when, callback, *args, context=None)
 
    Schedule *callback* to be called at the given absolute timestamp
@@ -265,6 +266,11 @@ clocks to track time.
       The *context* keyword-only parameter was added. See :pep:`567`
       for more details.
 
+   .. versionchanged:: 3.8
+      In Python 3.7 and earlier with the default event loop implementation,
+      the difference between *when* and the current time could not exceed
+      one day.  This has been fixed in Python 3.8.
+
 .. method:: loop.time()
 
    Return the current time, as a :class:`float` value, according to
@@ -314,11 +320,10 @@ Creating Futures and Tasks
    :meth:`loop.create_task`.
 
    If *factory* is ``None`` the default task factory will be set.
-
-   If *factory* is a *callable*, it should have a signature matching
-   ``(loop, coro)``, where *loop* will be a reference to the active
-   event loop, *coro* will be a coroutine object.  The callable
-   must return an :class:`asyncio.Future` compatible object.
+   Otherwise, *factory* must be a *callable* with the signature matching
+   ``(loop, coro)``, where *loop* is a reference to the active
+   event loop, and *coro* is a coroutine object.  The callable
+   must return a :class:`asyncio.Future`-compatible object.
 
 .. method:: loop.get_task_factory()
 
@@ -365,28 +370,23 @@ Opening network connections
    The created transport is an implementation-dependent bidirectional
    stream.
 
-   .. note::
-      *protocol_factory* can be any kind of callable, not necessarily
-      a class.  For example, if you want to use a pre-created
-      protocol instance, you can pass ``lambda: my_protocol``.
-
    Other arguments:
 
-   * *ssl*: if given and not false, an SSL/TLS transport is created
+   * *ssl*: if given and not false, a SSL/TLS transport is created
      (by default a plain TCP transport is created).  If *ssl* is
      a :class:`ssl.SSLContext` object, this context is used to create
-     the transport; if *ssl* is :const:`True`, a context with some
-     unspecified default settings is used.
+     the transport; if *ssl* is :const:`True`, a default context returned
+     from :func:`ssl.create_default_context` is used.
 
      .. seealso:: :ref:`SSL/TLS security considerations <ssl-security>`
 
-   * *server_hostname*, is only for use together with *ssl*,
-     and sets or overrides the hostname that the target server's certificate
-     will be matched against.  By default the value of the *host* argument
+   * *server_hostname* sets or overrides the hostname that the target
+     server's certificate will be matched against.  Should only be passed
+     if *ssl* is not ``None``.  By default the value of the *host* argument
      is used.  If *host* is empty, there is no default and you must pass a
      value for *server_hostname*.  If *server_hostname* is an empty
      string, hostname matching is disabled (which is a serious security
-     risk, allowing for man-in-the-middle-attacks).
+     risk, allowing for potential man-in-the-middle attacks).
 
    * *family*, *proto*, *flags* are the optional address family, protocol
      and flags to be passed through to getaddrinfo() for *host* resolution.
@@ -402,8 +402,8 @@ Opening network connections
      to bind the socket to locally.  The *local_host* and *local_port*
      are looked up using ``getaddrinfo()``, similarly to *host* and *port*.
 
-   * *ssl_handshake_timeout* is (for an SSL connection) the time in seconds
-     to wait for the SSL handshake to complete before aborting the connection.
+   * *ssl_handshake_timeout* is (for a TLS connection) the time in seconds
+     to wait for the TLS handshake to complete before aborting the connection.
      ``60.0`` seconds if ``None`` (default).
 
    .. versionadded:: 3.7
@@ -417,7 +417,7 @@ Opening network connections
 
    .. versionchanged:: 3.5
 
-      Added support for SSL/TLS for :class:`ProactorEventLoop`.
+      Added support for SSL/TLS in :class:`ProactorEventLoop`.
 
    .. seealso::
 
@@ -462,12 +462,12 @@ Opening network connections
    * *reuse_address* tells the kernel to reuse a local socket in
      ``TIME_WAIT`` state, without waiting for its natural timeout to
      expire. If not specified will automatically be set to ``True`` on
-     UNIX.
+     Unix.
 
    * *reuse_port* tells the kernel to allow this endpoint to be bound to the
      same port as other existing endpoints are bound to, so long as they all
      set this flag when being created. This option is not supported on Windows
-     and some UNIX's. If the :py:data:`~socket.SO_REUSEPORT` constant is not
+     and some Unixes. If the :py:data:`~socket.SO_REUSEPORT` constant is not
      defined then this capability is unsupported.
 
    * *allow_broadcast* tells the kernel to allow this endpoint to send
@@ -478,7 +478,7 @@ Opening network connections
      transport. If specified, *local_addr* and *remote_addr* should be omitted
      (must be :const:`None`).
 
-   On Windows with :class:`ProactorEventLoop`, this method is not supported.
+   On Windows, with :class:`ProactorEventLoop`, this method is not supported.
 
    See :ref:`UDP echo client protocol <asyncio-udp-echo-client-protocol>` and
    :ref:`UDP echo server protocol <asyncio-udp-echo-server-protocol>` examples.
@@ -491,22 +491,22 @@ Opening network connections
                         path=None, \*, ssl=None, sock=None, \
                         server_hostname=None, ssl_handshake_timeout=None)
 
-   Create UNIX connection.
+   Create a Unix connection.
 
    The socket family will be :py:data:`~socket.AF_UNIX`; socket
    type will be :py:data:`~socket.SOCK_STREAM`.
 
    A tuple of ``(transport, protocol)`` is returned on success.
 
-   *path* is the name of a UNIX domain socket and is required,
-   unless a *sock* parameter is specified.  Abstract UNIX sockets,
+   *path* is the name of a Unix domain socket and is required,
+   unless a *sock* parameter is specified.  Abstract Unix sockets,
    :class:`str`, :class:`bytes`, and :class:`~pathlib.Path` paths are
    supported.
 
    See the documentation of the :meth:`loop.create_connection` method
    for information about arguments to this method.
 
-   Availability: UNIX.
+   Availability: Unix.
 
    .. versionadded:: 3.7
 
@@ -529,7 +529,7 @@ Creating network servers
                         ssl_handshake_timeout=None, start_serving=True)
 
    Create a TCP server (socket type :data:`~socket.SOCK_STREAM`) listening
-   on the *host* and *port* address.
+   on *port* of the *host* address.
 
    Returns a :class:`Server` object.
 
@@ -538,13 +538,18 @@ Creating network servers
    * *protocol_factory* must be a callable returning a
      :ref:`protocol <asyncio-protocol>` implementation.
 
-   * The *host* parameter can be set to several types which determine behavior:
-       - If *host* is a string, the TCP server is bound to *host* and *port*.
-       - if *host* is a sequence of strings, the TCP server is bound to all
-         hosts of the sequence.
-       - If *host* is an empty string or ``None``, all interfaces are
-         assumed and a list of multiple sockets will be returned (most likely
-         one for IPv4 and another one for IPv6).
+   * The *host* parameter can be set to several types which determine where
+     the server would be listening:
+
+     - If *host* is a string, the TCP server is bound to a single network
+       interface specified by *host*.
+
+     - If *host* is a sequence of strings, the TCP server is bound to all
+       network interfaces specified by the sequence.
+
+     - If *host* is an empty string or ``None``, all interfaces are
+       assumed and a list of multiple sockets will be returned (most likely
+       one for IPv4 and another one for IPv6).
 
    * *family* can be set to either :data:`socket.AF_INET` or
      :data:`~socket.AF_INET6` to force the socket to use IPv4 or IPv6.
@@ -554,27 +559,26 @@ Creating network servers
    * *flags* is a bitmask for :meth:`getaddrinfo`.
 
    * *sock* can optionally be specified in order to use a preexisting
-     socket object. If specified, *host* and *port* should be omitted (must be
-     :const:`None`).
+     socket object. If specified, *host* and *port* must not be specified.
 
    * *backlog* is the maximum number of queued connections passed to
      :meth:`~socket.socket.listen` (defaults to 100).
 
-   * *ssl* can be set to an :class:`~ssl.SSLContext` to enable SSL over the
-     accepted connections.
+   * *ssl* can be set to an :class:`~ssl.SSLContext` instance to enable
+     TLS over the accepted connections.
 
    * *reuse_address* tells the kernel to reuse a local socket in
      ``TIME_WAIT`` state, without waiting for its natural timeout to
      expire. If not specified will automatically be set to ``True`` on
-     UNIX.
+     Unix.
 
    * *reuse_port* tells the kernel to allow this endpoint to be bound to the
      same port as other existing endpoints are bound to, so long as they all
      set this flag when being created. This option is not supported on
      Windows.
 
-   * *ssl_handshake_timeout* is (for an SSL server) the time in seconds to wait
-     for the SSL handshake to complete before aborting the connection.
+   * *ssl_handshake_timeout* is (for a TLS server) the time in seconds to wait
+     for the TLS handshake to complete before aborting the connection.
      ``60.0`` seconds if ``None`` (default).
 
    * *start_serving* set to ``True`` (the default) causes the created server
@@ -594,8 +598,7 @@ Creating network servers
 
    .. versionchanged:: 3.5
 
-      Added support for SSL/TLS on Windows with
-      :class:`ProactorEventLoop`.
+      Added support for SSL/TLS in :class:`ProactorEventLoop`.
 
    .. versionchanged:: 3.5.1
 
@@ -615,15 +618,15 @@ Creating network servers
    Similar to :meth:`loop.create_server` but works with the
    :py:data:`~socket.AF_UNIX` socket family.
 
-   *path* is the name of a UNIX domain socket, and is required,
-   unless a *sock* argument is provided.  Abstract UNIX sockets,
+   *path* is the name of a Unix domain socket, and is required,
+   unless a *sock* argument is provided.  Abstract Unix sockets,
    :class:`str`, :class:`bytes`, and :class:`~pathlib.Path` paths
    are supported.
 
    See the documentation of the :meth:`loop.create_server` method
    for information about arguments to this method.
 
-   Availability: UNIX.
+   Availability: Unix.
 
    .. versionadded:: 3.7
 
@@ -680,17 +683,17 @@ Transferring files
 
    *offset* tells from where to start reading the file. If specified,
    *count* is the total number of bytes to transmit as opposed to
-   sending the file until EOF is reached. File position is updated on
-   return or also in case of error in which case :meth:`file.tell()
-   <io.IOBase.tell>` can be used to figure out the number of bytes
-   which were sent.
+   sending the file until EOF is reached. File position is always updated,
+   even when this method raises an error, and
+   :meth:`file.tell() <io.IOBase.tell>` can be used to obtain the actual
+   number of bytes sent.
 
    *fallback* set to ``True`` makes asyncio to manually read and send
    the file when the platform does not support the sendfile system call
    (e.g. Windows or SSL socket on Unix).
 
    Raise :exc:`SendfileNotAvailableError` if the system does not support
-   *sendfile* syscall and *fallback* is ``False``.
+   the *sendfile* syscall and *fallback* is ``False``.
 
    .. versionadded:: 3.7
 
@@ -722,8 +725,8 @@ TLS Upgrade
    * *server_hostname*: sets or overrides the host name that the target
      server's certificate will be matched against.
 
-   * *ssl_handshake_timeout* is (for an SSL connection) the time in seconds to
-     wait for the SSL handshake to complete before aborting the connection.
+   * *ssl_handshake_timeout* is (for a TLS connection) the time in seconds to
+     wait for the TLS handshake to complete before aborting the connection.
      ``60.0`` seconds if ``None`` (default).
 
    .. versionadded:: 3.7
@@ -734,24 +737,26 @@ Watching file descriptors
 
 .. method:: loop.add_reader(fd, callback, \*args)
 
-   Start watching the file descriptor *fd* for read availability and
-   call the *callback* with specified arguments.
+   Start monitoring the *fd* file descriptor for read availability and
+   invoke *callback* with the specified arguments once *fd* is available for
+   reading.
 
 .. method:: loop.remove_reader(fd)
 
-   Stop watching the file descriptor *fd* for read availability.
+   Stop monitoring the *fd* file descriptor for read availability.
 
 .. method:: loop.add_writer(fd, callback, \*args)
 
-   Start watching the file descriptor *fd* for write availability and then
-   call the *callback* with specified arguments.
+   Start monitoring the *fd* file descriptor for write availability and
+   invoke *callback* with the specified arguments once *fd* is available for
+   writing.
 
    Use :func:`functools.partial` :ref:`to pass keywords
    <asyncio-pass-keywords>` to *func*.
 
 .. method:: loop.remove_writer(fd)
 
-   Stop watching the file descriptor *fd* for write availability.
+   Stop monitoring the *fd* file descriptor for write availability.
 
 See also :ref:`Platform Support <asyncio-platform-support>` section
 for some limitations of these methods.
@@ -769,13 +774,12 @@ convenient.
 
 .. coroutinemethod:: loop.sock_recv(sock, nbytes)
 
-   Receive data.  Asynchronous version of
+   Receive up to *nbytes* from *sock*.  Asynchronous version of
    :meth:`socket.recv() <socket.socket.recv>`.
 
-   The received data is returned as a bytes object.  The maximum amount
-   of data to be received is specified by the *nbytes* argument.
+   Return the received data as a bytes object.
 
-   The socket *sock* must be non-blocking.
+   *sock* must be a non-blocking socket.
 
    .. versionchanged:: 3.7
       Even though this method was always documented as a coroutine
@@ -784,27 +788,27 @@ convenient.
 
 .. coroutinemethod:: loop.sock_recv_into(sock, buf)
 
-   Receive data into a buffer.  Modeled after the blocking
+   Receive data from *sock* into the *buf* buffer.  Modeled after the blocking
    :meth:`socket.recv_into() <socket.socket.recv_into>` method.
 
    Return the number of bytes written to the buffer.
 
-   The socket *sock* must be non-blocking.
+   *sock* must be a non-blocking socket.
 
    .. versionadded:: 3.7
 
 .. coroutinemethod:: loop.sock_sendall(sock, data)
 
-   Send data to the socket. Asynchronous version of
+   Send *data* to the *sock* socket. Asynchronous version of
    :meth:`socket.sendall() <socket.socket.sendall>`.
 
-   This method continues to send data from *data* to the socket until either
-   all data in *data* has been sent or an error occurs.  ``None`` is returned
+   This method continues to send to the socket until either all data
+   in *data* has been sent or an error occurs.  ``None`` is returned
    on success.  On error, an exception is raised. Additionally, there is no way
    to determine how much data, if any, was successfully processed by the
    receiving end of the connection.
 
-   The socket *sock* must be non-blocking.
+   *sock* must be a non-blocking socket.
 
    .. versionchanged:: 3.7
       Even though the method was always documented as a coroutine
@@ -813,11 +817,11 @@ convenient.
 
 .. coroutinemethod:: loop.sock_connect(sock, address)
 
-   Connect to a remote socket at *address*.
+   Connect *sock* to a remote socket at *address*.
 
    Asynchronous version of :meth:`socket.connect() <socket.socket.connect>`.
 
-   The socket *sock* must be non-blocking.
+   *sock* must be a non-blocking socket.
 
    .. versionchanged:: 3.5.2
       ``address`` no longer needs to be resolved.  ``sock_connect``
@@ -843,7 +847,7 @@ convenient.
    and *address* is the address bound to the socket on the other end of the
    connection.
 
-   The socket *sock* must be non-blocking.
+   *sock* must be a non-blocking socket.
 
    .. versionchanged:: 3.7
       Even though the method was always documented as a coroutine
@@ -858,21 +862,21 @@ convenient.
                                         \*, fallback=True)
 
    Send a file using high-performance :mod:`os.sendfile` if possible.
-   Return the total number of bytes which were sent.
+   Return the total number of bytes sent.
 
    Asynchronous version of :meth:`socket.sendfile() <socket.socket.sendfile>`.
 
-   *sock* must be non-blocking :class:`~socket.socket` of
-   :const:`socket.SOCK_STREAM` type.
+   *sock* must be a non-blocking :const:`socket.SOCK_STREAM`
+   :class:`~socket.socket`.
 
-   *file* must be a regular file object opened in binary mode.
+   *file* must be a regular file object open in binary mode.
 
    *offset* tells from where to start reading the file. If specified,
    *count* is the total number of bytes to transmit as opposed to
-   sending the file until EOF is reached. File position is updated on
-   return or also in case of error in which case :meth:`file.tell()
-   <io.IOBase.tell>` can be used to figure out the number of bytes
-   which were sent.
+   sending the file until EOF is reached. File position is always updated,
+   even when this method raises an error, and
+   :meth:`file.tell() <io.IOBase.tell>` can be used to obtain the actual
+   number of bytes sent.
 
    *fallback*, when set to ``True``, makes asyncio manually read and send
    the file when the platform does not support the sendfile syscall
@@ -881,7 +885,7 @@ convenient.
    Raise :exc:`SendfileNotAvailableError` if the system does not support
    *sendfile* syscall and *fallback* is ``False``.
 
-   The socket *sock* must be non-blocking.
+   *sock* must be a non-blocking socket.
 
    .. versionadded:: 3.7
 
@@ -910,7 +914,7 @@ Working with pipes
 
 .. coroutinemethod:: loop.connect_read_pipe(protocol_factory, pipe)
 
-   Register a read-pipe in the event loop.
+   Register the read end of *pipe* in the event loop.
 
    *protocol_factory* must be a callable returning an
    :ref:`asyncio protocol <asyncio-protocol>` implementation.
@@ -926,7 +930,7 @@ Working with pipes
 
 .. coroutinemethod:: loop.connect_write_pipe(protocol_factory, pipe)
 
-   Register a write-pipe in the event loop.
+   Register the write end of *pipe* in the event loop.
 
    *protocol_factory* must be a callable returning an
    :ref:`asyncio protocol <asyncio-protocol>` implementation.
@@ -951,12 +955,12 @@ Working with pipes
    :meth:`loop.subprocess_shell` methods.
 
 
-UNIX signals
+Unix signals
 ^^^^^^^^^^^^
 
 .. method:: loop.add_signal_handler(signum, callback, \*args)
 
-   Add a handler for a signal.
+   Set *callback* as the handler for the *signum* signal.
 
    Raise :exc:`ValueError` if the signal number is invalid or uncatchable.
    Raise :exc:`RuntimeError` if there is a problem setting up the handler.
@@ -966,11 +970,12 @@ UNIX signals
 
 .. method:: loop.remove_signal_handler(sig)
 
-   Remove a handler for a signal.
+   Remove the handler for the *sig* signal.
 
-   Return ``True`` if a signal handler was removed, ``False`` if not.
+   Return ``True`` if the signal handler was removed, or ``False`` if
+   no handler was set for the given signal.
 
-Availability: UNIX.
+Availability: Unix.
 
 .. seealso::
 
@@ -982,7 +987,7 @@ Executing code in thread or process pools
 
 .. coroutinemethod:: loop.run_in_executor(executor, func, \*args)
 
-   Arrange for a *func* to be called in the specified executor.
+   Arrange for *func* to be called in the specified executor.
 
    The *executor* argument should be an :class:`concurrent.futures.Executor`
    instance. The default executor is used if *executor* is ``None``.
@@ -1024,18 +1029,17 @@ Allows customizing how exceptions are handled in the event loop.
    Set *handler* as the new event loop exception handler.
 
    If *handler* is ``None``, the default exception handler will
-   be set.
-
-   If *handler* is a callable object, it should have a
-   matching signature to ``(loop, context)``, where ``loop``
-   will be a reference to the active event loop, ``context``
-   will be a ``dict`` object (see :meth:`call_exception_handler`
-   documentation for details about context).
+   be set.  Otherwise, *handler* must be a callable with the signature
+   matching ``(loop, context)``, where ``loop``
+   is a reference to the active event loop, and ``context``
+   is a ``dict`` object containing the details of the exception
+   (see :meth:`call_exception_handler` documentation for details
+   about context).
 
 .. method:: loop.get_exception_handler()
 
-   Return the exception handler, or ``None`` if the default one
-   is in use.
+   Return the current exception handler, or ``None`` if no custom
+   exception handler was set.
 
    .. versionadded:: 3.5.2
 
@@ -1055,7 +1059,7 @@ Allows customizing how exceptions are handled in the event loop.
    Call the current event loop exception handler.
 
    *context* is a ``dict`` object containing the following keys
-   (new keys may be introduced later):
+   (new keys may be introduced in future Python versions):
 
    * 'message': Error message;
    * 'exception' (optional): Exception object;
@@ -1068,8 +1072,8 @@ Allows customizing how exceptions are handled in the event loop.
    .. note::
 
        This method should not be overloaded in subclassed
-       event loops.  For any custom exception handling, use
-       :meth:`set_exception_handler()` method.
+       event loops.  For custom exception handling, use
+       the :meth:`set_exception_handler()` method.
 
 Enabling debug mode
 ^^^^^^^^^^^^^^^^^^^
@@ -1099,17 +1103,16 @@ Enabling debug mode
 Running Subprocesses
 ^^^^^^^^^^^^^^^^^^^^
 
-Methods described in this subsections are low-level.  In an
-async/await code consider using high-level convenient
+Methods described in this subsections are low-level.  In regular
+async/await code consider using the high-level
 :func:`asyncio.create_subprocess_shell` and
-:func:`asyncio.create_subprocess_exec` functions instead.
+:func:`asyncio.create_subprocess_exec` convenience functions instead.
 
 .. note::
 
-   The default event loop that asyncio is pre-configured
-   to use on **Windows** does not support subprocesses.
-   See :ref:`Subprocess Support on Windows <asyncio-windows-subprocess>`
-   for details.
+   The default asyncio event loop on **Windows** does not support
+   subprocesses. See :ref:`Subprocess Support on Windows
+   <asyncio-windows-subprocess>` for details.
 
 .. coroutinemethod:: loop.subprocess_exec(protocol_factory, \*args, \
                       stdin=subprocess.PIPE, stdout=subprocess.PIPE, \
@@ -1124,7 +1127,7 @@ async/await code consider using high-level convenient
    * or :class:`bytes`, encoded to the
      :ref:`filesystem encoding <filesystem-encoding>`.
 
-   The first string specifies the program to execute,
+   The first string specifies the program executable,
    and the remaining strings specify the arguments.  Together, string
    arguments form the ``argv`` of the program.
 
@@ -1134,7 +1137,7 @@ async/await code consider using high-level convenient
    a single argument which is list of strings, *subprocess_exec*
    takes multiple string arguments.
 
-   The *protocol_factory* must instantiate a subclass of the
+   The *protocol_factory* must be a callable returning a subclass of the
    :class:`asyncio.SubprocessProtocol` class.
 
    Other parameters:
@@ -1185,7 +1188,7 @@ async/await code consider using high-level convenient
    This is similar to the standard library :class:`subprocess.Popen`
    class called with ``shell=True``.
 
-   The *protocol_factory* must instantiate a subclass of the
+   The *protocol_factory* must be a callable returning a subclass of the
    :class:`SubprocessProtocol` class.
 
    See :meth:`~loop.subprocess_exec` for more details about
@@ -1197,10 +1200,10 @@ async/await code consider using high-level convenient
 
 .. note::
    It is the application's responsibility to ensure that all whitespace
-   and metacharacters are quoted appropriately to avoid `shell injection
+   and special characters are quoted appropriately to avoid `shell injection
    <https://en.wikipedia.org/wiki/Shell_injection#Shell_injection>`_
    vulnerabilities. The :func:`shlex.quote` function can be used to
-   properly escape whitespace and shell metacharacters in strings that
+   properly escape whitespace and special characters in strings that
    are going to be used to construct shell commands.
 
 
@@ -1214,12 +1217,12 @@ Callback Handles
 
    .. method:: cancel()
 
-      Cancel the call.  If the callback is already canceled or executed,
-      this method has no effect.
+      Cancel the callback.  If the callback has already been canceled
+      or executed, this method has no effect.
 
    .. method:: cancelled()
 
-      Return ``True`` if the call was cancelled.
+      Return ``True`` if the callback was cancelled.
 
       .. versionadded:: 3.7
 
@@ -1228,7 +1231,7 @@ Callback Handles
    A callback wrapper object returned by :meth:`loop.call_later`,
    and :meth:`loop.call_at`.
 
-   The class is inherited from :class:`Handle`.
+   This class is a subclass of :class:`Handle`.
 
    .. method:: when()
 
@@ -1280,7 +1283,7 @@ Do not instantiate the class directly.
 
    .. method:: get_loop()
 
-      Gives the event loop associated with the server object.
+      Return the event loop associated with the server object.
 
       .. versionadded:: 3.7
 
@@ -1291,12 +1294,12 @@ Do not instantiate the class directly.
       This method is idempotent, so it can be called when
       the server is already being serving.
 
-      The new *start_serving* keyword-only parameter to
+      The *start_serving* keyword-only parameter to
       :meth:`loop.create_server` and
-      :meth:`asyncio.start_server` allows to create a Server object
-      that is not accepting connections right away.  In which case
-      this method, or :meth:`Server.serve_forever` can be used
-      to make the Server object to start accepting connections.
+      :meth:`asyncio.start_server` allows creating a Server object
+      that is not accepting connections initially.  In this case
+      ``Server.start_serving()``, or :meth:`Server.serve_forever` can be used
+      to make the Server start accepting connections.
 
       .. versionadded:: 3.7
 
@@ -1338,19 +1341,19 @@ Do not instantiate the class directly.
 
    .. attribute:: sockets
 
-      List of :class:`socket.socket` objects the server is listening to,
+      List of :class:`socket.socket` objects the server is listening on,
       or ``None`` if the server is closed.
 
       .. versionchanged:: 3.7
-         Prior to Python 3.7 ``Server.sockets`` used to return the
-         internal list of server's sockets directly.  In 3.7 a copy
+         Prior to Python 3.7 ``Server.sockets`` used to return an
+         internal list of server sockets directly.  In 3.7 a copy
          of that list is returned.
 
 
 .. _asyncio-event-loops:
 
-Event Loops Implementations
-===========================
+Event Loop Implementations
+==========================
 
 asyncio ships with two different event loop implementations:
 :class:`SelectorEventLoop` and :class:`ProactorEventLoop`.
@@ -1364,8 +1367,8 @@ on all platforms.
    An event loop based on the :mod:`selectors` module.
 
    Uses the most efficient *selector* available for the given
-   platform.  It is also possible to manually configure what
-   exact selector implementation should be used::
+   platform.  It is also possible to manually configure the
+   exact selector implementation to be used::
 
       import asyncio
       import selectors
@@ -1375,7 +1378,7 @@ on all platforms.
       asyncio.set_event_loop(loop)
 
 
-   Availability: UNIX, Windows.
+   Availability: Unix, Windows.
 
 
 .. class:: ProactorEventLoop
@@ -1412,9 +1415,9 @@ Examples
 ========
 
 Note that all examples in this section **purposefully** show how
-to use low-level event loop APIs such as :meth:`loop.run_forever`
+to use the low-level event loop APIs, such as :meth:`loop.run_forever`
 and :meth:`loop.call_soon`.  Modern asyncio applications rarely
-need to be written this way; consider using high-level functions
+need to be written this way; consider using the high-level functions
 like :func:`asyncio.run`.
 
 
@@ -1456,9 +1459,9 @@ event loop::
 Display the current date with call_later()
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-An example of callback displaying the current date every second. The
+An example of a callback displaying the current date every second. The
 callback uses the :meth:`loop.call_later` method to reschedule itself
-during 5 seconds, and then stops the event loop::
+after 5 seconds, and then stops the event loop::
 
     import asyncio
     import datetime
@@ -1545,7 +1548,7 @@ Wait until a file descriptor received some data using the
 Set signal handlers for SIGINT and SIGTERM
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-(This ``signals`` example only works on UNIX.)
+(This ``signals`` example only works on Unix.)
 
 Register handlers for signals :py:data:`SIGINT` and :py:data:`SIGTERM`
 using the :meth:`loop.add_signal_handler` method::