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

Rewritten/updated sections:

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

4 files changed, 46 insertions, 46 deletions

diff --git a/Doc/whatsnew/3.5.rst b/Doc/whatsnew/3.5.rst
index 96f86e6..d3aed84 100644
--- a/Doc/whatsnew/3.5.rst
+++ b/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.)
 
diff --git a/Doc/whatsnew/3.6.rst b/Doc/whatsnew/3.6.rst
index 1360af7..b413b5a 100644
--- a/Doc/whatsnew/3.6.rst
+++ b/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`.)
diff --git a/Doc/whatsnew/3.7.rst b/Doc/whatsnew/3.7.rst
index cb4865e..fbaa2cf 100644
--- a/Doc/whatsnew/3.7.rst
+++ b/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.
diff --git a/Doc/whatsnew/3.8.rst b/Doc/whatsnew/3.8.rst
index a9b689d..259dcf6 100644
--- a/Doc/whatsnew/3.8.rst
+++ b/Doc/whatsnew/3.8.rst
@@ -170,7 +170,7 @@ Deprecated
 
 * Passing an object that is not an instance of
   :class:`concurrent.futures.ThreadPoolExecutor` to
-  :meth:`asyncio.AbstractEventLoop.set_default_executor()` is
+  :meth:`asyncio.loop.set_default_executor()` is
   deprecated and will be prohibited in Python 3.9.
   (Contributed by Elvis Pranskevichus in :issue:`34075`.)
 
@@ -264,7 +264,7 @@ Changes in the Python API
 
 * Asyncio tasks can now be named, either by passing the ``name`` keyword
   argument to :func:`asyncio.create_task` or
-  the :meth:`~asyncio.AbstractEventLoop.create_task` event loop method, or by
+  the :meth:`~asyncio.loop.create_task` event loop method, or by
   calling the :meth:`~asyncio.Task.set_name` method on the task object. The
   task name is visible in the ``repr()`` output of :class:`asyncio.Task` and
   can also be retrieved using the :meth:`~asyncio.Task.get_name` method.