bpo-33649: Add high-level APIs cheat-sheet (GH-9319)

Doc/library/asyncio-api-index.rst

@@ -0,0 +1,206 @@
+.. currentmodule:: asyncio
+
+
+=====================
+High-level APIs Index
+=====================
+
+This page lists all high-level async/await enabled asyncio APIs.
+
+
+Tasks
+=====
+
+Utilities to run asyncio programs, create Tasks, and
+await on multiple things with timeouts.
+
+.. list-table::
+    :widths: 30 70
+
+    * - :func:`run`
+      - Create event loop, run a coroutine, close the loop.
+
+    * - :func:`create_task`
+      - Start an asyncio Task.
+
+    * - ``await`` :func:`sleep`
+      - Sleep for a number of seconds.
+
+    * - ``await`` :func:`gather`
+      - Schedule and wait for things concurrently.
+
+    * - ``await`` :func:`wait_for`
+      - Run with a timeout.
+
+    * - ``await`` :func:`shield`
+      - Shield from cancellation.
+
+    * - ``await`` :func:`wait`
+      - Monitor for completeness.
+
+    * - :func:`current_task`
+      - Return the current Task.
+
+    * - :func:`all_tasks`
+      - Return all tasks for an event loop.
+
+    * - :class:`Task`
+      - Task object.
+
+
+.. rubric:: Examples
+
+* :ref:`Using asyncio.gather() to run things in parallel
+  <asyncio_example_gather>`.
+
+* :ref:`Using asyncio.wait_for() to enforce a timeout
+  <asyncio_example_waitfor>`.
+
+* :ref:`Cancellation <asyncio_example_task_cancel>`.
+
+* :ref:`Using asyncio.sleep() <asyncio_example_sleep>`.
+
+* See also the main :ref:`Tasks documentation page <coroutine>`.
+
+
+Queues
+======
+
+Queues should be used to distribute work amongst multiple asyncio Tasks,
+implement connection pools, and pub/sub patterns.
+
+
+.. list-table::
+    :widths: 30 70
+
+    * - :class:`Queue`
+      - A FIFO queue.
+
+    * - :class:`PriorityQueue`
+      - A priority queue.
+
+    * - :class:`LifoQueue`
+      - A LIFO queue.
+
+
+.. rubric:: Examples
+
+* :ref:`Using asyncio.Queue to distribute workload between several
+  Tasks <asyncio_example_queue_dist>`.
+
+* See also the :ref:`Queues documentation page <asyncio-queues>`.
+
+
+Subprocesses
+============
+
+Utilities to spawn subprocesses and run shell commands.
+
+.. list-table::
+    :widths: 30 70
+
+    * - ``await`` :func:`create_subprocess_exec`
+      - Create a subprocess.
+
+    * - ``await`` :func:`create_subprocess_shell`
+      - Run a shell command.
+
+
+.. rubric:: Examples
+
+* :ref:`Executing a shell command <asyncio_example_subprocess_shell>`.
+
+* See also the :ref:`subprocess APIs <asyncio-subprocess>`
+  documentation.
+
+
+Streams
+=======
+
+High-level APIs to work with network IO.
+
+.. list-table::
+    :widths: 30 70
+
+    * - ``await`` :func:`open_connection`
+      -  Establish a TCP connection.
+
+    * - ``await`` :func:`open_unix_connection`
+      -  Establish a Unix socket connection.
+
+    * - ``await`` :func:`start_server`
+      - Start a TCP server.
+
+    * - ``await`` :func:`start_unix_server`
+      - Start a Unix socket server.
+
+    * - :class:`StreamReader`
+      - High-level async/await object to receive network data.
+
+    * - :class:`StreamWriter`
+      - High-level async/await object to send network data.
+
+
+.. rubric:: Examples
+
+* :ref:`Example TCP client <asyncio_example_stream>`.
+
+* See also the :ref:`streams APIs <asyncio-streams>`
+  documentation.
+
+
+Synchronization
+===============
+
+Threading-like synchronization primitives that can be used in Tasks.
+
+.. list-table::
+    :widths: 30 70
+
+    * - :class:`Lock`
+      - A mutex lock.
+
+    * - :class:`Event`
+      - An event object.
+
+    * - :class:`Condition`
+      - A condition object.
+
+    * - :class:`Semaphore`
+      - A semaphore.
+
+    * - :class:`BoundedSemaphore`
+      - A bounded semaphore.
+
+
+.. rubric:: Examples
+
+* :ref:`Using asyncio.Event <asyncio_example_sync_event>`.
+
+* See also the documentation of asyncio
+  :ref:`synchronization primitives <asyncio-sync>`.
+
+
+Exceptions
+==========
+
+.. list-table::
+    :widths: 30 70
+
+
+    * - :exc:`asyncio.TimeoutError`
+      - Raised on timeout by functions like :func:`wait_for`.
+        Keep in mind that ``asyncio.TimeoutError`` is **unrelated**
+        to the built-in :exc:`TimeoutError` exception.
+
+    * - :exc:`asyncio.CancelledError`
+      - Raised when a Task is cancelled. See also :meth:`Task.cancel`.
+
+
+.. rubric:: Examples
+
+* :ref:`Handling CancelledError to run code on cancellation request
+  <asyncio_example_task_cancel>`.
+
+* See also the full list of
+  :ref:`asyncio-specific exceptions <asyncio-exceptions>`.

Doc/library/asyncio-eventloop.rst

@@ -1466,7 +1466,7 @@ during 5 seconds, and then stops the event loop::
 
 .. seealso::
 
-   A similar :ref:`current date <asyncio-date-coroutine>` example
+   A similar :ref:`current date <asyncio_example_sleep>` example
    created with a coroutine and the :func:`run` function.
 
 

Doc/library/asyncio-exceptions.rst

@@ -1,6 +1,8 @@
 .. currentmodule:: asyncio
 
 
+.. _asyncio-exceptions:
+
 ==========
 Exceptions
 ==========
@@ -10,7 +12,7 @@ Exceptions
 
    The operation has exceeded the given deadline.
 
-   .. note::
+   .. important::
       This exception is different from the builtin :exc:`TimeoutError`
       exception.
 
@@ -23,7 +25,7 @@ Exceptions
    when asyncio Tasks are cancelled.  In almost all situations the
    exception must always be re-raised.
 
-   .. note::
+   .. important::
 
       This exception is a subclass of :exc:`Exception`, so it can be
       accidentally suppressed by ``try..except`` block::

Doc/library/asyncio-queue.rst

@@ -140,6 +140,8 @@ Exceptions
 Examples
 ========
 
+.. _asyncio_example_queue_dist:
+
 Queues can be used to distribute workload between several
 concurrent tasks::
 

Doc/library/asyncio-stream.rst

@@ -10,6 +10,8 @@ Streams are high-level async/await-ready primitives to work with
 network connections.  Streams allow sending and receiving data without
 using callbacks or low-level protocols and transports.
 
+.. _asyncio_example_stream:
+
 Here is an example of a TCP echo client written using asyncio
 streams::
 

Doc/library/asyncio-subprocess.rst

@@ -9,6 +9,8 @@ Subprocesses
 This section describes high-level async/await asyncio APIs to
 create and manage subprocesses.
 
+.. _asyncio_example_subprocess_shell:
+
 Here's an example of how asyncio can run a shell command and
 communicate its result back::
 

Doc/library/asyncio-sync.rst

@@ -94,6 +94,8 @@ Event
    :meth:`clear` method.  The :meth:`wait` method blocks until the
    flag is set to *true*.  The flag is set to *false* initially.
 
+   .. _asyncio_example_sync_event:
+
    Example::
 
       async def waiter(event):

Doc/library/asyncio-task.rst

@@ -165,7 +165,7 @@ Sleeping
    If *result* is provided, it is returned to the caller
    when the coroutine completes.
 
-   .. _asyncio-date-coroutine:
+   .. _asyncio_example_sleep:
 
    Example of coroutine displaying the current date every second
    during 5 seconds::
@@ -219,6 +219,8 @@ Running Tasks Concurrently
       If the *gather* itself is cancelled, the cancellation is
       propagated regardless of *return_exceptions*.
 
+   .. _asyncio_example_gather:
+
    Example::
 
       import asyncio
@@ -316,6 +318,8 @@ Timeouts
 
    If the wait is cancelled, the future *fut* is also cancelled.
 
+   .. _asyncio_example_waitfor:
+
    Example::
 
        async def eternity():
@@ -539,6 +543,8 @@ Task Object
       suppressing cancellation completely is not common and is actively
       discouraged.
 
+      .. _asyncio_example_task_cancel:
+
       The following example illustrates how coroutines can intercept
       the cancellation request::
 

Doc/library/asyncio.rst

@@ -42,8 +42,8 @@ as well as **low-level** APIs for *library and framework developers* to:
   with async/await syntax.
 
 
-Contents
---------
+Reference
+---------
 
 .. rubric:: High-level APIs
 
@@ -73,6 +73,7 @@ Contents
 .. toctree::
    :maxdepth: 1
 
+   asyncio-api-index.rst
    asyncio-dev.rst