bpo-33649: First asyncio docs improvement pass (GH-9142)

Rewritten/updated sections:

* Event Loop APIs
* Transports & Protocols
* Streams
* Exceptions
* Policies
* Queues
* Subprocesses
* Platforms

Doc/library/asyncio-dev.rst

@@ -23,7 +23,7 @@ To enable all debug checks for an application:
 * Enable the asyncio debug mode globally by setting the environment variable
   :envvar:`PYTHONASYNCIODEBUG` to ``1``, using ``-X dev`` command line option
   (see the :option:`-X` option), or by calling
-  :meth:`AbstractEventLoop.set_debug`.
+  :meth:`loop.set_debug`.
 * Set the log level of the :ref:`asyncio logger <asyncio-logger>` to
   :py:data:`logging.DEBUG`. For example, call
   ``logging.basicConfig(level=logging.DEBUG)`` at startup.
@@ -35,11 +35,11 @@ Examples debug checks:
 
 * Log :ref:`coroutines defined but never "yielded from"
   <asyncio-coroutine-not-scheduled>`
-* :meth:`~AbstractEventLoop.call_soon` and :meth:`~AbstractEventLoop.call_at` methods
+* :meth:`loop.call_soon` and :meth:`loop.call_at` methods
   raise an exception if they are called from the wrong thread.
 * Log the execution time of the selector
 * Log callbacks taking more than 100 ms to be executed. The
-  :attr:`AbstractEventLoop.slow_callback_duration` attribute is the minimum
+  :attr:`loop.slow_callback_duration` attribute is the minimum
   duration in seconds of "slow" callbacks.
 * :exc:`ResourceWarning` warnings are emitted when transports and event loops
   are :ref:`not closed explicitly <asyncio-close-transports>`.
@@ -51,7 +51,7 @@ Examples debug checks:
 
 .. seealso::
 
-   The :meth:`AbstractEventLoop.set_debug` method and the :ref:`asyncio logger
+   The :meth:`loop.set_debug` method and the :ref:`asyncio logger
    <asyncio-logger>`.
 
 
@@ -75,7 +75,7 @@ For example, write::
 
 Don't schedule directly a call to the :meth:`~Future.set_result` or the
 :meth:`~Future.set_exception` method of a future with
-:meth:`AbstractEventLoop.call_soon`: the future can be cancelled before its method
+:meth:`loop.call_soon`: the future can be cancelled before its method
 is called.
 
 If you wait for a future, you should check early if the future was cancelled to
@@ -96,13 +96,14 @@ The :func:`shield` function can also be used to ignore cancellation.
 Concurrency and multithreading
 ------------------------------
 
-An event loop runs in a thread and executes all callbacks and tasks in the same
-thread. While a task is running in the event loop, no other task is running in
-the same thread. But when the task uses ``await``, the task is suspended
-and the event loop executes the next task.
+An event loop runs in a thread (typically the main thread) and executes
+all callbacks and tasks in its thread.  While a task is running in the
+event loop, no other task is running in the same thread. When a task
+executes an ``await`` expression, the task gets suspended and the
+event loop executes the next task.
 
 To schedule a callback from a different thread, the
-:meth:`AbstractEventLoop.call_soon_threadsafe` method should be used. Example::
+:meth:`loop.call_soon_threadsafe` method should be used. Example::
 
     loop.call_soon_threadsafe(callback, *args)
 
@@ -122,7 +123,7 @@ To schedule a coroutine object from a different thread, the
      future = asyncio.run_coroutine_threadsafe(coro_func(), loop)
      result = future.result(timeout)  # Wait for the result with a timeout
 
-The :meth:`AbstractEventLoop.run_in_executor` method can be used with a thread pool
+The :meth:`loop.run_in_executor` method can be used with a thread pool
 executor to execute a callback in different thread to not block the thread of
 the event loop.
 
@@ -151,7 +152,7 @@ APIs like :ref:`protocols <asyncio-protocol>`.
 
 An executor can be used to run a task in a different thread or even in a
 different process, to not block the thread of the event loop. See the
-:meth:`AbstractEventLoop.run_in_executor` method.
+:meth:`loop.run_in_executor` method.
 
 .. seealso::
 
@@ -182,7 +183,7 @@ Detect coroutine objects never scheduled
 ----------------------------------------
 
 When a coroutine function is called and its result is not passed to
-:func:`ensure_future` or to the :meth:`AbstractEventLoop.create_task` method,
+:func:`ensure_future` or to the :meth:`loop.create_task` method,
 the execution of the coroutine object will never be scheduled which is
 probably a bug.  :ref:`Enable the debug mode of asyncio <asyncio-debug-mode>`
 to :ref:`log a warning <asyncio-logger>` to detect it.
@@ -204,7 +205,7 @@ Output in debug mode::
         test()
 
 The fix is to call the :func:`ensure_future` function or the
-:meth:`AbstractEventLoop.create_task` method with the coroutine object.
+:meth:`loop.create_task` method with the coroutine object.
 
 .. seealso::
 
@@ -279,7 +280,7 @@ coroutine in another coroutine and use classic try/except::
     loop.run_forever()
     loop.close()
 
-Another option is to use the :meth:`AbstractEventLoop.run_until_complete`
+Another option is to use the :meth:`loop.run_until_complete`
 function::
 
     task = asyncio.ensure_future(bug())

Doc/library/asyncio-eventloops.rst

-.. currentmodule:: asyncio
-
-Event loops
-===========
-
-**Source code:** :source:`Lib/asyncio/events.py`
-
-Event loop functions
---------------------
-
-The following functions are convenient shortcuts to accessing the methods of the
-global policy. Note that this provides access to the default policy, unless an
-alternative policy was set by calling :func:`set_event_loop_policy` earlier in
-the execution of the process.
-
-.. function:: get_event_loop()
-
-   Equivalent to calling ``get_event_loop_policy().get_event_loop()``.
-
-.. function:: set_event_loop(loop)
-
-   Equivalent to calling ``get_event_loop_policy().set_event_loop(loop)``.
-
-.. function:: new_event_loop()
-
-   Equivalent to calling ``get_event_loop_policy().new_event_loop()``.
-
-.. function:: get_running_loop()
-
-   Return the running event loop in the current OS thread.  If there
-   is no running event loop a :exc:`RuntimeError` is raised.
-
-   .. versionadded:: 3.7
-
-
-.. _asyncio-event-loops:
-
-Available event loops
----------------------
-
-asyncio currently provides two implementations of event loops:
-:class:`SelectorEventLoop` and :class:`ProactorEventLoop`.
-
-.. class:: SelectorEventLoop
-
-   Event loop based on the :mod:`selectors` module. Subclass of
-   :class:`AbstractEventLoop`.
-
-   Use the most efficient selector available on the platform.
-
-   On Windows, only sockets are supported (ex: pipes are not supported):
-   see the `MSDN documentation of select
-   <https://msdn.microsoft.com/en-us/library/windows/desktop/ms740141%28v=vs.85%29.aspx>`_.
-
-.. class:: ProactorEventLoop
-
-   Proactor event loop for Windows using "I/O Completion Ports" aka IOCP.
-   Subclass of :class:`AbstractEventLoop`.
-
-   Availability: Windows.
-
-   .. seealso::
-
-      `MSDN documentation on I/O Completion Ports
-      <https://msdn.microsoft.com/en-us/library/windows/desktop/aa365198%28v=vs.85%29.aspx>`_.
-
-Example to use a :class:`ProactorEventLoop` on Windows::
-
-    import asyncio, sys
-
-    if sys.platform == 'win32':
-        loop = asyncio.ProactorEventLoop()
-        asyncio.set_event_loop(loop)
-
-.. _asyncio-platform-support:
-
-Platform support
-----------------
-
-The :mod:`asyncio` module has been designed to be portable, but each platform
-still has subtle differences and may not support all :mod:`asyncio` features.
-
-Windows
-^^^^^^^
-
-Common limits of Windows event loops:
-
-- :meth:`~AbstractEventLoop.create_unix_connection` and
-  :meth:`~AbstractEventLoop.create_unix_server` are not supported: the socket
-  family :data:`socket.AF_UNIX` is specific to UNIX
-- :meth:`~AbstractEventLoop.add_signal_handler` and
-  :meth:`~AbstractEventLoop.remove_signal_handler` are not supported
-- :meth:`EventLoopPolicy.set_child_watcher` is not supported.
-  :class:`ProactorEventLoop` supports subprocesses. It has only one
-  implementation to watch child processes, there is no need to configure it.
-
-:class:`SelectorEventLoop` specific limits:
-
-- :class:`~selectors.SelectSelector` is used which only supports sockets
-  and is limited to 512 sockets.
-- :meth:`~AbstractEventLoop.add_reader` and :meth:`~AbstractEventLoop.add_writer` only
-  accept file descriptors of sockets
-- Pipes are not supported
-  (ex: :meth:`~AbstractEventLoop.connect_read_pipe`,
-  :meth:`~AbstractEventLoop.connect_write_pipe`)
-- :ref:`Subprocesses <asyncio-subprocess>` are not supported
-  (ex: :meth:`~AbstractEventLoop.subprocess_exec`,
-  :meth:`~AbstractEventLoop.subprocess_shell`)
-
-:class:`ProactorEventLoop` specific limits:
-
-- :meth:`~AbstractEventLoop.create_datagram_endpoint` (UDP) is not supported
-- :meth:`~AbstractEventLoop.add_reader` and :meth:`~AbstractEventLoop.add_writer` are
-  not supported
-
-The resolution of the monotonic clock on Windows is usually around 15.6 msec.
-The best resolution is 0.5 msec. The resolution depends on the hardware
-(availability of `HPET
-<https://en.wikipedia.org/wiki/High_Precision_Event_Timer>`_) and on the Windows
-configuration. See :ref:`asyncio delayed calls <asyncio-delayed-calls>`.
-
-.. versionchanged:: 3.5
-
-   :class:`ProactorEventLoop` now supports SSL.
-
-
-Mac OS X
-^^^^^^^^
-
-Character devices like PTY are only well supported since Mavericks (Mac OS
-10.9). They are not supported at all on Mac OS 10.5 and older.
-
-On Mac OS 10.6, 10.7 and 10.8, the default event loop is
-:class:`SelectorEventLoop` which uses :class:`selectors.KqueueSelector`.
-:class:`selectors.KqueueSelector` does not support character devices on these
-versions.  The :class:`SelectorEventLoop` can be used with
-:class:`~selectors.SelectSelector` or :class:`~selectors.PollSelector` to
-support character devices on these versions of Mac OS X. Example::
-
-    import asyncio
-    import selectors
-
-    selector = selectors.SelectSelector()
-    loop = asyncio.SelectorEventLoop(selector)
-    asyncio.set_event_loop(loop)
-
-
-Event loop policies and the default policy
-------------------------------------------
-
-Event loop management is abstracted with a *policy* pattern, to provide maximal
-flexibility for custom platforms and frameworks. Throughout the execution of a
-process, a single global policy object manages the event loops available to the
-process based on the calling context. A policy is an object implementing the
-:class:`AbstractEventLoopPolicy` interface.
-
-For most users of :mod:`asyncio`, policies never have to be dealt with
-explicitly, since the default global policy is sufficient (see below).
-
-The module-level functions
-:func:`get_event_loop` and :func:`set_event_loop` provide convenient access to
-event loops managed by the default policy.
-
-
-Event loop policy interface
----------------------------
-
-An event loop policy must implement the following interface:
-
-.. class:: AbstractEventLoopPolicy
-
-   Event loop policy.
-
-   .. method:: get_event_loop()
-
-      Get the event loop for the current context.
-
-      Returns an event loop object implementing the :class:`AbstractEventLoop`
-      interface. In case called from coroutine, it returns the currently
-      running event loop.
-
-      Raises an exception in case no event loop has been set for the current
-      context and the current policy does not specify to create one. It must
-      never return ``None``.
-
-      .. versionchanged:: 3.6
-
-   .. method:: set_event_loop(loop)
-
-      Set the event loop for the current context to *loop*.
-
-   .. method:: new_event_loop()
-
-      Create and return a new event loop object according to this policy's
-      rules.
-
-      If there's need to set this loop as the event loop for the current
-      context, :meth:`set_event_loop` must be called explicitly.
-
-
-The default policy defines context as the current thread, and manages an event
-loop per thread that interacts with :mod:`asyncio`. An exception to this rule
-happens when :meth:`~AbstractEventLoopPolicy.get_event_loop` is called from a
-running future/coroutine, in which case it will return the current loop
-running that future/coroutine.
-
-If the current thread doesn't already have an event loop associated with it,
-the default policy's :meth:`~AbstractEventLoopPolicy.get_event_loop` method
-creates one when called from the main thread, but raises :exc:`RuntimeError`
-otherwise.
-
-
-Access to the global loop policy
---------------------------------
-
-.. function:: get_event_loop_policy()
-
-   Get the current event loop policy.
-
-.. function:: set_event_loop_policy(policy)
-
-   Set the current event loop policy. If *policy* is ``None``, the default
-   policy is restored.
-
-
-Customizing the event loop policy
----------------------------------
-
-To implement a new event loop policy, it is recommended you subclass the
-concrete default event loop policy :class:`DefaultEventLoopPolicy`
-and override the methods for which you want to change behavior, for example::
-
-    class MyEventLoopPolicy(asyncio.DefaultEventLoopPolicy):
-
-        def get_event_loop(self):
-            """Get the event loop.
-
-            This may be None or an instance of EventLoop.
-            """
-            loop = super().get_event_loop()
-            # Do something with loop ...
-            return loop
-
-    asyncio.set_event_loop_policy(MyEventLoopPolicy())

Doc/library/asyncio-exceptions.rst

+.. currentmodule:: asyncio
+
+
+==========
+Exceptions
+==========
+
+
+.. exception:: TimeoutError
+
+   The operation has exceeded the given deadline.
+
+   .. note::
+      This exception is different from the builtin :exc:`TimeoutError`
+      exception.
+
+
+.. exception:: CancelledError
+
+   The operation has been cancelled.
+
+   This exception can be caught to perform custom operations on
+   when asyncio Tasks are cancelled.  In almost all situations the
+   exception must always be re-raised.
+
+   .. note::
+      This exception is a subclass of :exc:`Exception`, so it can be
+      accidentally suppressed by ``try..except`` block::
+
+        try:
+            await operation
+        except Exception:
+            # The cancellation is broken because the *except* block
+            # suppresses the CancelledError exception.
+            log.log('an error has occurred')
+
+      Instead, the following pattern should be used::
+
+        try:
+            await operation
+        except asyncio.CancelledError:
+            raise
+        except Exception:
+            log.log('an error has occurred')
+
+
+.. exception:: InvalidStateError
+
+   Invalid internal state of :class:`Task` or :class:`Future`.
+
+   Can be raised in situations like setting a result value for a
+   *Future* object that already has a result value set.
+
+
+.. exception:: SendfileNotAvailableError
+
+   The "sendfile" syscall for is not available for the given
+   socket or file type.
+
+   A subclass of :exc:`RuntimeError`.
+
+
+.. exception:: IncompleteReadError
+
+    Incomplete read error.
+
+    Raised by :ref:`asyncio streams <asyncio-streams>` APIs.
+
+    This exception is a subclass of :exc:`EOFError`.
+
+   .. attribute:: expected
+
+      Total number (:class:`int`) of expected bytes.
+
+   .. attribute:: partial
+
+      Read :class:`bytes` string before the end of stream was reached.
+
+
+.. exception:: LimitOverrunError
+
+   Reached the buffer limit while looking for a separator.
+
+   Raised by :ref:`asyncio streams <asyncio-streams>` APIs.
+
+   .. attribute:: consumed
+
+      Total number of to be consumed bytes.

Doc/library/asyncio-platforms.rst

+.. currentmodule:: asyncio
+
+
+.. _asyncio-platform-support:
+
+
+=================
+Platforms Support
+=================
+
+The :mod:`asyncio` module has been designed to be portable,
+but some platforms have subtle differences and limitations.
+
+
+All Platforms
+=============
+
+* :meth:`loop.add_reader` and :meth:`loop.add_writer`
+  cannot be used to monitor file IO.
+
+
+Windows
+=======
+
+All event loops on Windows do not support the following methods:
+
+* :meth:`loop.create_unix_connection` and
+  :meth:`loop.create_unix_server` are not supported.
+  The :data:`socket.AF_UNIX` socket family is specific to UNIX/
+
+* :meth:`loop.add_signal_handler` and
+  :meth:`loop.remove_signal_handler` are not supported.
+
+:class:`SelectorEventLoop` has the following limitations:
+
+* :class:`~selectors.SelectSelector` is used to wait on socket events:
+  it supports sockets and is limited to 512 sockets.
+
+* :meth:`loop.add_reader` and :meth:`loop.add_writer` only accept
+  socket handles (e.g. pipe file descriptors are not supported).
+
+* Pipes are not supported, so the :meth:`loop.connect_read_pipe`
+  and :meth:`loop.connect_write_pipe` methods are not implemented.
+
+* :ref:`Subprocesses <asyncio-subprocess>` are not supported, i.e.
+  :meth:`loop.subprocess_exec` and :meth:`loop.subprocess_shell`
+  methods are not implemented.
+
+:class:`ProactorEventLoop` has the following limitations:
+
+* The :meth:`loop.create_datagram_endpoint` method
+  is not supported.
+
+* The :meth:`loop.add_reader` and :meth:`loop.add_writer`
+  methods are not supported.
+
+The resolution of the monotonic clock on Windows is usually around 15.6
+msec.  The best resolution is 0.5 msec. The resolution depends on the
+hardware (availability of `HPET
+<https://en.wikipedia.org/wiki/High_Precision_Event_Timer>`_) and on the
+Windows configuration.
+
+
+.. _asyncio-windows-subprocess:
+
+Subprocess Support on Windows
+-----------------------------
+
+:class:`SelectorEventLoop` on Windows does not support subproceses,
+so :class:`ProactorEventLoop` should be used instead::
+
+  import asyncio
+
+  asyncio.set_event_loop_policy(
+      asyncio.WindowsProactorEventLoopPolicy())
+
+  asyncio.run(your_code())
+
+
+The :meth:`policy.set_child_watcher()
+<AbstractEventLoopPolicy.set_child_watcher>` function is also
+not supported, as :class:`ProactorEventLoop` has a different mechanism
+to watch child processes.
+
+
+macOS
+=====
+
+Modern macOS versions are fully supported.
+
+.. rubric:: macOS <= 10.8
+
+On macOS 10.6, 10.7 and 10.8, the default event loop
+uses :class:`selectors.KqueueSelector`, which does not support
+character devices on these versions.  The :class:`SelectorEventLoop`
+can be manually configured to use :class:`~selectors.SelectSelector`
+or :class:`~selectors.PollSelector` to support character devices on
+these older versions of macOS.  Example::
+
+    import asyncio
+    import selectors
+
+    selector = selectors.SelectSelector()
+    loop = asyncio.SelectorEventLoop(selector)
+    asyncio.set_event_loop(loop)

Doc/library/asyncio-policy.rst

+.. currentmodule:: asyncio
+
+
+.. _asyncio-policies:
+
+========
+Policies
+========
+
+An event loop policy, a global per-process object, controls
+management of the event loop. Each event loop has a default
+policy, which can be changed and customized using the API.
+
+A policy defines the notion of context and manages a
+separate event loop per context. The default policy
+defines context to be the current thread.
+
+By using a custom event loop policy, the behavior of
+:func:`get_event_loop`, :func:`set_event_loop`, and
+:func:`new_event_loop` functions can be customized.
+
+Policy objects should implement the APIs defined
+in the abstract base class :class:`AbstractEventLoopPolicy`.
+
+
+Access the Policy
+=================
+
+The following functions can be used to get and set the policy
+for the current process:
+
+.. function:: get_event_loop_policy()
+
+   Return the current process-wide policy.
+
+.. function:: set_event_loop_policy(policy)
+
+   Set the current process-wide policy to *policy*.
+
+   If *policy* is set to ``None``, the default policy is restored.
+
+
+Policy Objects
+==============
+
+The abstract event loop policy base class is defined as follows:
+
+.. class:: AbstractEventLoopPolicy
+
+   An abstract base class for asyncio policies.
+
+   .. method:: get_event_loop()
+
+      Get the event loop for the current context.
+
+      Return an event loop object implementing the
+      :class:`AbstractEventLoop` interface.
+
+      This method should never return ``None``.
+
+      .. versionchanged:: 3.6
+
+   .. method:: set_event_loop(loop)
+
+      Set the event loop for the current context to *loop*.
+
+   .. method:: new_event_loop()
+
+      Create and return a new event loop object.
+
+      This method should never return ``None``.
+
+   .. method:: get_child_watcher()
+
+      Get a child process watcher object.
+
+      Return a watcher object implementing the
+      :class:`AbstractChildWatcher` interface.
+
+      This function is Unix specific.
+
+   .. method:: set_child_watcher(watcher)
+
+      Get the current child process watcher to *watcher*.
+
+      This function is Unix specific.
+
+
+asyncio ships with the following built-in policies:
+
+
+.. class:: DefaultEventLoopPolicy
+
+   The default asyncio policy.  Uses :class:`SelectorEventLoop`
+   on both Unix and Windows platforms.
+
+   There is no need to install the default policy manually; asyncio
+   is configured to use it automatically.
+
+
+.. class:: WindowsProactorEventLoopPolicy
+
+   An alternative event loop policy that uses the
+   :class:`ProactorEventLoop` event loop implementation.
+
+   Availability: Windows.
+
+
+Process Watchers
+================
+
+A process watcher allows customization of how an event loop monitors
+child processes on Unix. Specifically, the event loop needs to know
+when a child process has finished its execution.
+
+In asyncio, child processes are created with
+:func:`create_subprocess_exec` and :meth:`loop.subprocess_exec`
+functions.
+
+asyncio defines an abstract base class :class:`AbstractChildWatcher`
+that child watchers should implement, and has two different
+implementations: :class:`SafeChildWatcher` (configured to be used
+by default) and :class:`FastChildWatcher`.
+
+See also the :ref:`Subprocess and Threads <asyncio-subprocess-threads>`
+section.
+
+The following two functions can be used to customize the watcher
+implementation used by the asyncio event loop:
+
+.. function:: get_child_watcher()
+
+   Return the current child watcher for the current policy.
+
+.. function:: set_child_watcher(watcher)
+
+   Set the current child watcher to *watcher* for the current
+   policy.  *watcher* must implement methods defined in the
+   :class:`AbstractChildWatcher` base class.
+
+.. note::
+   Third-party event loops implementations might not support
+   custom child watchers.  For such event loops, using
+   :func:`set_child_watcher` might have no effect or even can
+   be prohibited.
+
+.. class:: AbstractChildWatcher
+
+   .. method:: add_child_handler(pid, callback, \*args)
+
+      Register a new child handler.
+
+      Arrange for ``callback(pid, returncode, *args)`` to be called
+      when a process with PID equal to *pid* terminates.  Specifying
+      another callback for the same process replaces the previous
+      handler.
+
+      *callback* callable must be thread-safe.
+
+   .. method:: remove_child_handler(pid)
+
+      Removes the handler for process with PID equal to *pid*.
+
+      The function returns ``True`` if the handler was successfully
+      removed, ``False`` if there was nothing to remove.
+
+   .. method:: attach_loop(loop)
+
+      Attach the watcher to an event loop.
+
+      If the watcher was previously attached to an event loop, then
+      it is first detached before attaching to the new loop.
+
+      Note: loop may be ``None``.
+
+   .. method:: close()
+
+      Close the watcher.
+
+      This method has to be called to ensure that underlying
+      resources are cleaned-up.
+
+.. class:: SafeChildWatcher
+
+   This implementation avoids disrupting other code spawning processes
+   by polling every process explicitly on a :py:data:`SIGCHLD` signal.
+
+   This is a safe solution but it has a significant overhead when
+   handling a big number of processes (*O(n)* each time a
+   :py:data:`SIGCHLD` is received).
+
+   asyncio uses this implementation by default.
+
+.. class:: FastChildWatcher
+
+   This implementation reaps every terminated processes by calling
+   ``os.waitpid(-1)`` directly, possibly breaking other code spawning
+   processes and waiting for their termination.
+
+   There is no noticeable overhead when handling a big number of
+   children (*O(1)* each time a child terminates).
+
+
+Custom Policies
+===============
+
+To implement a new event loop policy, it is recommended to subclass
+:class:`DefaultEventLoopPolicy` and override the methods for which
+custom behavior is wanted, e.g.::
+
+    class MyEventLoopPolicy(asyncio.DefaultEventLoopPolicy):
+
+        def get_event_loop(self):
+            """Get the event loop.
+
+            This may be None or an instance of EventLoop.
+            """
+            loop = super().get_event_loop()
+            # Do something with loop ...
+            return loop
+
+    asyncio.set_event_loop_policy(MyEventLoopPolicy())

Doc/library/asyncio-queue.rst

 .. currentmodule:: asyncio
 
+
+======
 Queues
 ======
 
-**Source code:** :source:`Lib/asyncio/queues.py`
-
-Queues:
+asyncio queues are designed to be similar to classes of the
+:mod:`queue` module.  Although asyncio queues are not thread-safe,
+they are designed to be used specifically in async/await code.
 
-* :class:`Queue`
-* :class:`PriorityQueue`
-* :class:`LifoQueue`
+Note that methods on asyncio queues don't have a *timeout* parameter;
+use :func:`asyncio.wait_for` function to do queue operations with a
+timeout.
 
-asyncio queue API was designed to be close to classes of the :mod:`queue`
-module (:class:`~queue.Queue`, :class:`~queue.PriorityQueue`,
-:class:`~queue.LifoQueue`), but it has no *timeout* parameter. The
-:func:`asyncio.wait_for` function can be used to cancel a task after a timeout.
+See also the `Examples`_ section below.
 
 Queue
------
+=====
 
 .. class:: Queue(maxsize=0, \*, loop=None)
 
-   A queue, useful for coordinating producer and consumer coroutines.
+   A first in, first out (FIFO) queue.
 
-   If *maxsize* is less than or equal to zero, the queue size is infinite. If
-   it is an integer greater than ``0``, then ``await put()`` will block
-   when the queue reaches *maxsize*, until an item is removed by :meth:`get`.
+   If *maxsize* is less than or equal to zero, the queue size is
+   infinite.  If it is an integer greater than ``0``, then
+   ``await put()`` blocks when the queue reaches *maxsize*
+   until an item is removed by :meth:`get`.
 
-   Unlike the standard library :mod:`queue`, you can reliably know this Queue's
-   size with :meth:`qsize`, since your single-threaded asyncio application won't
-   be interrupted between calling :meth:`qsize` and doing an operation on the
-   Queue.
+   Unlike the standard library threading :mod:`queue`, the size of
+   the queue is always known and can be returned by calling the
+   :meth:`qsize` method.
 
    This class is :ref:`not thread safe <asyncio-multithreading>`.
 
-   .. versionchanged:: 3.4.4
-      New :meth:`join` and :meth:`task_done` methods.
+   .. attribute:: maxsize
+
+      Number of items allowed in the queue.
 
    .. method:: empty()
 
@@ -45,26 +45,16 @@ Queue
 
       Return ``True`` if there are :attr:`maxsize` items in the queue.
 
-      .. note::
-
-         If the Queue was initialized with ``maxsize=0`` (the default), then
-         :meth:`full()` is never ``True``.
+      If the queue was initialized with ``maxsize=0`` (the default),
+      then :meth:`full()` never returns ``True``.
 
    .. coroutinemethod:: get()
 
-      Remove and return an item from the queue. If queue is empty, wait until
-      an item is available.
-
-      This method is a :ref:`coroutine <coroutine>`.
-
-      .. seealso::
-
-         The :meth:`empty` method.
+      Remove and return an item from the queue. If queue is empty,
+      wait until an item is available.
 
    .. method:: get_nowait()
 
-      Remove and return an item from the queue.
-
       Return an item if one is immediately available, else raise
       :exc:`QueueEmpty`.
 
@@ -72,26 +62,16 @@ Queue
 
       Block until all items in the queue have been gotten and processed.
 
-      The count of unfinished tasks goes up whenever an item is added to the
-      queue. The count goes down whenever a consumer thread calls
-      :meth:`task_done` to indicate that the item was retrieved and all work on
-      it is complete.  When the count of unfinished tasks drops to zero,
-      :meth:`join` unblocks.
-
-      This method is a :ref:`coroutine <coroutine>`.
-
-      .. versionadded:: 3.4.4
+      The count of unfinished tasks goes up whenever an item is added
+      to the queue. The count goes down whenever a consumer thread calls
+      :meth:`task_done` to indicate that the item was retrieved and all
+      work on it is complete.  When the count of unfinished tasks drops
+      to zero, :meth:`join` unblocks.
 
    .. coroutinemethod:: put(item)
 
-      Put an item into the queue. If the queue is full, wait until a free slot
-      is available before adding item.
-
-      This method is a :ref:`coroutine <coroutine>`.
-
-      .. seealso::
-
-         The :meth:`full` method.
+      Put an item into the queue. If the queue is full, wait until a
+      free slot is available before adding item.
 
    .. method:: put_nowait(item)
 
@@ -107,54 +87,111 @@ Queue
 
       Indicate that a formerly enqueued task is complete.
 
-      Used by queue consumers. For each :meth:`~Queue.get` used to fetch a task, a
-      subsequent call to :meth:`task_done` tells the queue that the processing
-      on the task is complete.
-
-      If a :meth:`join` is currently blocking, it will resume when all items
-      have been processed (meaning that a :meth:`task_done` call was received
-      for every item that had been :meth:`~Queue.put` into the queue).
+      Used by queue consumers. For each :meth:`~Queue.get` used to
+      fetch a task, a subsequent call to :meth:`task_done` tells the
+      queue that the processing on the task is complete.
 
-      Raises :exc:`ValueError` if called more times than there were items
-      placed in the queue.
+      If a :meth:`join` is currently blocking, it will resume when all
+      items have been processed (meaning that a :meth:`task_done`
+      call was received for every item that had been :meth:`~Queue.put`
+      into the queue).
 
-      .. versionadded:: 3.4.4
+      Raises :exc:`ValueError` if called more times than there were
+      items placed in the queue.
 
-   .. attribute:: maxsize
-
-      Number of items allowed in the queue.
 
-
-PriorityQueue
--------------
+Priority Queue
+==============
 
 .. class:: PriorityQueue
 
-   A subclass of :class:`Queue`; retrieves entries in priority order (lowest
-   first).
+   A variant of :class:`Queue`; retrieves entries in priority order
+   (lowest first).
 
-   Entries are typically tuples of the form: (priority number, data).
+   Entries are typically tuples of the form
+   ``(priority_number, data)``.
 
 
-LifoQueue
----------
+LIFO Queue
+==========
 
 .. class:: LifoQueue
 
-    A subclass of :class:`Queue` that retrieves most recently added entries
-    first.
+   A variant of :class:`Queue` that retrieves most recently added
+   entries first (last in, first out).
 
 
 Exceptions
-^^^^^^^^^^
+==========
 
 .. exception:: QueueEmpty
 
-   Exception raised when the :meth:`~Queue.get_nowait` method is called on a
-   :class:`Queue` object which is empty.
+   This exception is raised when the :meth:`~Queue.get_nowait` method
+   is called on an empty queue.
 
 
 .. exception:: QueueFull
 
-   Exception raised when the :meth:`~Queue.put_nowait` method is called on a
-   :class:`Queue` object which is full.
+   Exception raised when the :meth:`~Queue.put_nowait` method is called
+   on a queue that has reached its *maxsize*.
+
+
+Examples
+========
+
+Queues can be used to distribute workload between several
+concurrent tasks::
+
+   import asyncio
+   import random
+   import time
+
+
+   async def worker(name, queue):
+       while True:
+           # Get a "work item" out of the queue.
+           sleep_for = await queue.get()
+
+           # Sleep for the "sleep_for" seconds.
+           await asyncio.sleep(sleep_for)
+
+           # Notify the queue that the "work item" has been processed.
+           queue.task_done()
+
+           print(f'{name} has slept for {sleep_for:.2f} seconds')
+
+
+   async def main():
+       # Create a queue that we will use to store our "workload".
+       queue = asyncio.Queue()
+
+       # Generate random timings and put them into the queue.
+       total_sleep_time = 0
+       for _ in range(20):
+           sleep_for = random.uniform(0.05, 1.0)
+           total_sleep_time += sleep_for
+           queue.put_nowait(sleep_for)
+
+       # Create three worker tasks to process the queue concurrently.
+       tasks = []
+       for i in range(3):
+           task = asyncio.create_task(worker(f'worker-{i}', queue))
+           tasks.append(task)
+
+       # Wait until the queue is fully processed.
+       started_at = time.monotonic()
+       await queue.join()
+       total_slept_for = time.monotonic() - started_at
+
+       # Cancel our worker tasks.
+       for task in tasks:
+           task.cancel()
+       # Wait until all worker tasks are cancelled.
+       await asyncio.gather(*tasks, return_exceptions=True)
+
+       print('====')
+       print(f'3 workers slept in parallel for {total_slept_for:.2f} seconds')
+       print(f'total expected sleep time: {total_sleep_time:.2f} seconds')
+
+
+   asyncio.run(main())

Doc/library/asyncio-task.rst

@@ -63,7 +63,7 @@ the coroutine object returned by the call doesn't do anything until you
 schedule its execution.  There are two basic ways to start it running:
 call ``await coroutine`` or ``yield from coroutine`` from another coroutine
 (assuming the other coroutine is already running!), or schedule its execution
-using the :func:`ensure_future` function or the :meth:`AbstractEventLoop.create_task`
+using the :func:`ensure_future` function or the :meth:`loop.create_task`
 method.
 
 
@@ -129,7 +129,7 @@ Example of coroutine displaying ``"Hello World"``::
 .. seealso::
 
    The :ref:`Hello World with call_soon() <asyncio-hello-world-callback>`
-   example uses the :meth:`AbstractEventLoop.call_soon` method to schedule a
+   example uses the :meth:`loop.call_soon` method to schedule a
    callback.
 
 
@@ -159,7 +159,7 @@ using the :meth:`sleep` function::
 
    The :ref:`display the current date with call_later()
    <asyncio-date-callback>` example uses a callback with the
-   :meth:`AbstractEventLoop.call_later` method.
+   :meth:`loop.call_later` method.
 
 
 Example: Chain coroutines
@@ -190,32 +190,12 @@ Sequence diagram of the example:
 .. image:: tulip_coro.png
    :align: center
 
-The "Task" is created by the :meth:`AbstractEventLoop.run_until_complete` method
+The "Task" is created by the :meth:`loop.run_until_complete` method
 when it gets a coroutine object instead of a task.
 
 The diagram shows the control flow, it does not describe exactly how things
 work internally. For example, the sleep coroutine creates an internal future
-which uses :meth:`AbstractEventLoop.call_later` to wake up the task in 1 second.
-
-
-InvalidStateError
------------------
-
-.. exception:: InvalidStateError
-
-   The operation is not allowed in this state.
-
-
-TimeoutError
-------------
-
-.. exception:: TimeoutError
-
-   The operation exceeded the given deadline.
-
-.. note::
-
-   This exception is different from the builtin :exc:`TimeoutError` exception!
+which uses :meth:`loop.call_later` to wake up the task in 1 second.
 
 
 Future
@@ -231,7 +211,7 @@ Future
      raise an exception when the future isn't done yet.
 
    - Callbacks registered with :meth:`add_done_callback` are always called
-     via the event loop's :meth:`~AbstractEventLoop.call_soon`.
+     via the event loop's :meth:`loop.call_soon`.
 
    - This class is not compatible with the :func:`~concurrent.futures.wait` and
      :func:`~concurrent.futures.as_completed` functions in the
@@ -281,7 +261,7 @@ Future
 
       The *callback* is called with a single argument - the future object. If the
       future is already done when this is called, the callback is scheduled
-      with :meth:`~AbstractEventLoop.call_soon`.
+      with :meth:`loop.call_soon`.
 
       An optional keyword-only *context* argument allows specifying a custom
       :class:`contextvars.Context` for the *callback* to run in.  The current
@@ -344,11 +324,11 @@ Example combining a :class:`Future` and a :ref:`coroutine function
 
 The coroutine function is responsible for the computation (which takes 1 second)
 and it stores the result into the future. The
-:meth:`~AbstractEventLoop.run_until_complete` method waits for the completion of
+:meth:`loop.run_until_complete` method waits for the completion of
 the future.
 
 .. note::
-   The :meth:`~AbstractEventLoop.run_until_complete` method uses internally the
+   The :meth:`loop.run_until_complete` method uses internally the
    :meth:`~Future.add_done_callback` method to be notified when the future is
    done.
 
@@ -433,7 +413,7 @@ Task
    logged: see :ref:`Pending task destroyed <asyncio-pending-task-destroyed>`.
 
    Don't directly create :class:`Task` instances: use the :func:`create_task`
-   function or the :meth:`AbstractEventLoop.create_task` method.
+   function or the :meth:`loop.create_task` method.
 
    Tasks support the :mod:`contextvars` module.  When a Task
    is created it copies the current context and later runs its coroutine
@@ -644,7 +624,7 @@ Task functions
    .. seealso::
 
       The :func:`create_task` function and
-      :meth:`AbstractEventLoop.create_task` method.
+      :meth:`loop.create_task` method.
 
 .. function:: wrap_future(future, \*, loop=None)
 

Doc/library/asyncio.rst

@@ -50,7 +50,8 @@ Table of contents:
    :maxdepth: 3
 
    asyncio-eventloop.rst
-   asyncio-eventloops.rst
+   asyncio-policy.rst
+   asyncio-platforms.rst
    asyncio-task.rst
    asyncio-protocol.rst
    asyncio-stream.rst
@@ -58,6 +59,7 @@ Table of contents:
    asyncio-sync.rst
    asyncio-queue.rst
    asyncio-dev.rst
+   asyncio-exceptions.rst
 
 .. seealso::
 

Doc/library/ipc.rst

@@ -16,11 +16,11 @@ The list of modules described in this chapter is:
 
 .. toctree::
 
+   asyncio.rst
    socket.rst
    ssl.rst
    select.rst
    selectors.rst
-   asyncio.rst
    asyncore.rst
    asynchat.rst
    signal.rst

Doc/whatsnew/3.5.rst

@@ -777,18 +777,18 @@ all changes introduced in Python 3.5 have also been backported to Python 3.4.x.
 
 Notable changes in the :mod:`asyncio` module since Python 3.4.0:
 
-* New debugging APIs: :meth:`loop.set_debug() <asyncio.BaseEventLoop.set_debug>`
-  and :meth:`loop.get_debug() <asyncio.BaseEventLoop.get_debug>` methods.
+* New debugging APIs: :meth:`loop.set_debug() <asyncio.loop.set_debug>`
+  and :meth:`loop.get_debug() <asyncio.loop.get_debug>` methods.
   (Contributed by Victor Stinner.)
 
 * The proactor event loop now supports SSL.
   (Contributed by Antoine Pitrou and Victor Stinner in :issue:`22560`.)
 
-* A new :meth:`loop.is_closed() <asyncio.BaseEventLoop.is_closed>` method to
+* A new :meth:`loop.is_closed() <asyncio.loop.is_closed>` method to
   check if the event loop is closed.
   (Contributed by Victor Stinner in :issue:`21326`.)
 
-* A new :meth:`loop.create_task() <asyncio.BaseEventLoop.create_task>`
+* A new :meth:`loop.create_task() <asyncio.loop.create_task>`
   to conveniently create and schedule a new :class:`~asyncio.Task`
   for a coroutine.  The ``create_task`` method is also used by all
   asyncio functions that wrap coroutines into tasks, such as
@@ -805,10 +805,10 @@ Notable changes in the :mod:`asyncio` module since Python 3.4.0:
   (Contributed by Yury Selivanov.)
 
 * New :meth:`loop.set_task_factory()
-  <asyncio.AbstractEventLoop.set_task_factory>` and
-  :meth:`loop.get_task_factory() <asyncio.AbstractEventLoop.get_task_factory>`
+  <asyncio.loop.set_task_factory>` and
+  :meth:`loop.get_task_factory() <asyncio.loop.get_task_factory>`
   methods to customize the task factory that :meth:`loop.create_task()
-  <asyncio.BaseEventLoop.create_task>` method uses.  (Contributed by Yury
+  <asyncio.loop.create_task>` method uses.  (Contributed by Yury
   Selivanov.)
 
 * New :meth:`Queue.join() <asyncio.Queue.join>` and
@@ -822,7 +822,7 @@ Notable changes in the :mod:`asyncio` module since Python 3.4.0:
 Updates in 3.5.1:
 
 * The :func:`~asyncio.ensure_future` function and all functions that
-  use it, such as :meth:`loop.run_until_complete() <asyncio.BaseEventLoop.run_until_complete>`,
+  use it, such as :meth:`loop.run_until_complete() <asyncio.loop.run_until_complete>`,
   now accept all kinds of :term:`awaitable objects <awaitable>`.
   (Contributed by Yury Selivanov.)
 
@@ -834,20 +834,20 @@ Updates in 3.5.1:
   method to check if the transport is closing or closed.
   (Contributed by Yury Selivanov.)
 
-* The :meth:`loop.create_server() <asyncio.BaseEventLoop.create_server>`
+* The :meth:`loop.create_server() <asyncio.loop.create_server>`
   method can now accept a list of hosts.
   (Contributed by Yann Sionneau.)
 
 Updates in 3.5.2:
 
-* New :meth:`loop.create_future() <asyncio.BaseEventLoop.create_future>`
+* New :meth:`loop.create_future() <asyncio.loop.create_future>`
   method to create Future objects.  This allows alternative event
   loop implementations, such as
   `uvloop <https://github.com/MagicStack/uvloop>`_, to provide a faster
   :class:`asyncio.Future` implementation.
   (Contributed by Yury Selivanov.)
 
-* New :meth:`loop.get_exception_handler() <asyncio.BaseEventLoop.get_exception_handler>`
+* New :meth:`loop.get_exception_handler() <asyncio.loop.get_exception_handler>`
   method to get the current exception handler.
   (Contributed by Yury Selivanov.)
 
@@ -856,13 +856,13 @@ Updates in 3.5.2:
   sequence appears.
   (Contributed by Mark Korenberg.)
 
-* The :meth:`loop.create_connection() <asyncio.BaseEventLoop.create_connection>`
-  and :meth:`loop.create_server() <asyncio.BaseEventLoop.create_server>`
+* The :meth:`loop.create_connection() <asyncio.loop.create_connection>`
+  and :meth:`loop.create_server() <asyncio.loop.create_server>`
   methods are optimized to avoid calling the system ``getaddrinfo``
   function if the address is already resolved.
   (Contributed by A. Jesse Jiryu Davis.)
 
-* The :meth:`loop.sock_connect(sock, address) <asyncio.BaseEventLoop.sock_connect>`
+* The :meth:`loop.sock_connect(sock, address) <asyncio.loop.sock_connect>`
   no longer requires the *address* to be resolved prior to the call.
   (Contributed by A. Jesse Jiryu Davis.)
 

Doc/whatsnew/3.6.rst

@@ -824,7 +824,7 @@ Notable changes in the :mod:`asyncio` module since Python 3.5.0
   (Contributed by Yury Selivanov in :issue:`28613`.)
 
 * The :func:`~asyncio.ensure_future` function and all functions that
-  use it, such as :meth:`loop.run_until_complete() <asyncio.BaseEventLoop.run_until_complete>`,
+  use it, such as :meth:`loop.run_until_complete() <asyncio.loop.run_until_complete>`,
   now accept all kinds of :term:`awaitable objects <awaitable>`.
   (Contributed by Yury Selivanov.)
 
@@ -836,18 +836,18 @@ Notable changes in the :mod:`asyncio` module since Python 3.5.0
   method to check if the transport is closing or closed.
   (Contributed by Yury Selivanov.)
 
-* The :meth:`loop.create_server() <asyncio.BaseEventLoop.create_server>`
+* The :meth:`loop.create_server() <asyncio.loop.create_server>`
   method can now accept a list of hosts.
   (Contributed by Yann Sionneau.)
 
-* New :meth:`loop.create_future() <asyncio.BaseEventLoop.create_future>`
+* New :meth:`loop.create_future() <asyncio.loop.create_future>`
   method to create Future objects.  This allows alternative event
   loop implementations, such as
   `uvloop <https://github.com/MagicStack/uvloop>`_, to provide a faster
   :class:`asyncio.Future` implementation.
   (Contributed by Yury Selivanov in :issue:`27041`.)
 
-* New :meth:`loop.get_exception_handler() <asyncio.BaseEventLoop.get_exception_handler>`
+* New :meth:`loop.get_exception_handler() <asyncio.loop.get_exception_handler>`
   method to get the current exception handler.
   (Contributed by Yury Selivanov in :issue:`27040`.)
 
@@ -860,12 +860,12 @@ Notable changes in the :mod:`asyncio` module since Python 3.5.0
   has been improved.
   (Contributed by Mark Korenberg in :issue:`28370`.)
 
-* The :meth:`loop.getaddrinfo() <asyncio.BaseEventLoop.getaddrinfo>`
+* The :meth:`loop.getaddrinfo() <asyncio.loop.getaddrinfo>`
   method is optimized to avoid calling the system ``getaddrinfo``
   function if the address is already resolved.
   (Contributed by A. Jesse Jiryu Davis.)
 
-* The :meth:`loop.stop() <asyncio.BaseEventLoop.stop>`
+* The :meth:`loop.stop() <asyncio.loop.stop>`
   method has been changed to stop the loop immediately after
   the current iteration.  Any new callbacks scheduled as a result
   of the last iteration will be discarded.
@@ -876,7 +876,7 @@ Notable changes in the :mod:`asyncio` module since Python 3.5.0
   the :exc:`StopIteration` exception.
   (Contributed by Chris Angelico in :issue:`26221`.)
 
-* New :meth:`loop.connect_accepted_socket() <asyncio.BaseEventLoop.connect_accepted_socket>`
+* New :meth:`loop.connect_accepted_socket() <asyncio.loop.connect_accepted_socket>`
   method to be used by servers that accept connections outside of asyncio,
   but that use asyncio to handle them.
   (Contributed by Jim Fulton in :issue:`27392`.)
@@ -884,7 +884,7 @@ Notable changes in the :mod:`asyncio` module since Python 3.5.0
 * ``TCP_NODELAY`` flag is now set for all TCP transports by default.
   (Contributed by Yury Selivanov in :issue:`27456`.)
 
-* New :meth:`loop.shutdown_asyncgens() <asyncio.AbstractEventLoop.shutdown_asyncgens>`
+* New :meth:`loop.shutdown_asyncgens() <asyncio.loop.shutdown_asyncgens>`
   to properly close pending asynchronous generators before closing the
   loop.
   (Contributed by Yury Selivanov in :issue:`28003`.)

Doc/whatsnew/3.7.rst

@@ -637,10 +637,10 @@ include:
   (Contributed by Yury Selivanov in :issue:`32314`.)
 
 * asyncio gained support for :mod:`contextvars`.
-  :meth:`loop.call_soon() <asyncio.AbstractEventLoop.call_soon>`,
-  :meth:`loop.call_soon_threadsafe() <asyncio.AbstractEventLoop.call_soon_threadsafe>`,
-  :meth:`loop.call_later() <asyncio.AbstractEventLoop.call_later>`,
-  :meth:`loop.call_at() <asyncio.AbstractEventLoop.call_at>`, and
+  :meth:`loop.call_soon() <asyncio.loop.call_soon>`,
+  :meth:`loop.call_soon_threadsafe() <asyncio.loop.call_soon_threadsafe>`,
+  :meth:`loop.call_later() <asyncio.loop.call_later>`,
+  :meth:`loop.call_at() <asyncio.loop.call_at>`, and
   :meth:`Future.add_done_callback() <asyncio.Future.add_done_callback>`
   have a new optional keyword-only *context* parameter.
   :class:`Tasks <asyncio.Task>` now track their context automatically.
@@ -651,11 +651,11 @@ include:
   to ``asyncio.get_event_loop().create_task()``.
   (Contributed by Andrew Svetlov in :issue:`32311`.)
 
-* The new :meth:`loop.start_tls() <asyncio.AbstractEventLoop.start_tls>`
+* The new :meth:`loop.start_tls() <asyncio.loop.start_tls>`
   method can be used to upgrade an existing connection to TLS.
   (Contributed by Yury Selivanov in :issue:`23749`.)
 
-* The new :meth:`loop.sock_recv_into() <asyncio.AbstractEventLoop.sock_recv_into>`
+* The new :meth:`loop.sock_recv_into() <asyncio.loop.sock_recv_into>`
   method allows reading data from a socket directly into a provided buffer making
   it possible to reduce data copies.
   (Contributed by Antoine Pitrou in :issue:`31819`.)
@@ -683,13 +683,13 @@ include:
   can be used to determine if the writer is closing.
   (Contributed by Andrew Svetlov in :issue:`32391`.)
 
-* The new :meth:`loop.sock_sendfile() <asyncio.AbstractEventLoop.sock_sendfile>`
+* The new :meth:`loop.sock_sendfile() <asyncio.loop.sock_sendfile>`
   coroutine method allows sending files using :mod:`os.sendfile` when possible.
   (Contributed by Andrew Svetlov in :issue:`32410`.)
 
-* The new :meth:`Task.get_loop() <asyncio.Task.get_loop>` and
-  :meth:`Future.get_loop() <asyncio.Future.get_loop>` methods
-  return the instance of the loop on which a task or a future were created.
+* The new :meth:`Future.get_loop() <asyncio.Future.get_loop>` and
+  ``Task.get_loop()`` methods return the instance of the loop on which a task or
+  a future were created.
   :meth:`Server.get_loop() <asyncio.Server.get_loop>` allows doing the same for
   :class:`asyncio.Server` objects.
   (Contributed by Yury Selivanov in :issue:`32415` and
@@ -698,8 +698,8 @@ include:
 * It is now possible to control how instances of :class:`asyncio.Server` begin
   serving.  Previously, the server would start serving immediately when created.
   The new *start_serving* keyword argument to
-  :meth:`loop.create_server() <asyncio.AbstractEventLoop.create_server>` and
-  :meth:`loop.create_unix_server() <asyncio.AbstractEventLoop.create_unix_server>`,
+  :meth:`loop.create_server() <asyncio.loop.create_server>` and
+  :meth:`loop.create_unix_server() <asyncio.loop.create_unix_server>`,
   as well as :meth:`Server.start_serving() <asyncio.Server.start_serving>`, and
   :meth:`Server.serve_forever() <asyncio.Server.serve_forever>`
   can be used to decouple server instantiation and serving.  The new
@@ -717,20 +717,20 @@ include:
   (Contributed by Yury Selivanov in :issue:`32662`.)
 
 * Callback objects returned by
-  :func:`loop.call_later() <asyncio.AbstractEventLoop.call_later>`
+  :func:`loop.call_later() <asyncio.loop.call_later>`
   gained the new :meth:`when() <asyncio.TimerHandle.when>` method which
   returns an absolute scheduled callback timestamp.
   (Contributed by Andrew Svetlov in :issue:`32741`.)
 
 * The :meth:`loop.create_datagram_endpoint() \
-  <asyncio.AbstractEventLoop.create_datagram_endpoint>` method
+  <asyncio.loop.create_datagram_endpoint>` method
   gained support for Unix sockets.
   (Contributed by Quentin Dawans in :issue:`31245`.)
 
 * The :func:`asyncio.open_connection`, :func:`asyncio.start_server` functions,
-  :meth:`loop.create_connection() <asyncio.AbstractEventLoop.create_connection>`,
-  :meth:`loop.create_server() <asyncio.AbstractEventLoop.create_server>`,
-  :meth:`loop.create_accepted_socket() <asyncio.BaseEventLoop.connect_accepted_socket>`
+  :meth:`loop.create_connection() <asyncio.loop.create_connection>`,
+  :meth:`loop.create_server() <asyncio.loop.create_server>`,
+  :meth:`loop.create_accepted_socket() <asyncio.loop.connect_accepted_socket>`
   methods and their corresponding UNIX socket variants now accept the
   *ssl_handshake_timeout* keyword argument.
   (Contributed by Neil Aspinall in :issue:`29970`.)
@@ -2360,11 +2360,11 @@ Changes in the Python API
   (Contributed by Brett Cannon in :issue:`33169`.)
 
 * In :mod:`asyncio`,
-  :meth:`loop.sock_recv() <asyncio.AbstractEventLoop.sock_recv>`,
-  :meth:`loop.sock_sendall() <asyncio.AbstractEventLoop.sock_sendall>`,
-  :meth:`loop.sock_accept() <asyncio.AbstractEventLoop.sock_accept>`,
-  :meth:`loop.getaddrinfo() <asyncio.AbstractEventLoop.getaddrinfo>`,
-  :meth:`loop.getnameinfo() <asyncio.AbstractEventLoop.getnameinfo>`
+  :meth:`loop.sock_recv() <asyncio.loop.sock_recv>`,
+  :meth:`loop.sock_sendall() <asyncio.loop.sock_sendall>`,
+  :meth:`loop.sock_accept() <asyncio.loop.sock_accept>`,
+  :meth:`loop.getaddrinfo() <asyncio.loop.getaddrinfo>`,
+  :meth:`loop.getnameinfo() <asyncio.loop.getnameinfo>`
   have been changed to be proper coroutine methods to match their
   documentation.  Previously, these methods returned :class:`asyncio.Future`
   instances.