From 7372c3bbefb4763dbd1b6d66f7971bef28c0f056 Mon Sep 17 00:00:00 2001 From: Yury Selivanov Date: Fri, 14 Sep 2018 15:11:24 -0700 Subject: bpo-33649: Add high-level APIs cheat-sheet (GH-9319) --- Doc/library/asyncio-api-index.rst | 206 +++++++++++++++++++++++++++++++++++++ Doc/library/asyncio-eventloop.rst | 2 +- Doc/library/asyncio-exceptions.rst | 6 +- Doc/library/asyncio-queue.rst | 2 + Doc/library/asyncio-stream.rst | 2 + Doc/library/asyncio-subprocess.rst | 2 + Doc/library/asyncio-sync.rst | 2 + Doc/library/asyncio-task.rst | 8 +- Doc/library/asyncio.rst | 5 +- 9 files changed, 229 insertions(+), 6 deletions(-) create mode 100644 Doc/library/asyncio-api-index.rst diff --git a/Doc/library/asyncio-api-index.rst b/Doc/library/asyncio-api-index.rst new file mode 100644 index 0000000..a4d0e1b --- /dev/null +++ b/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 + `. + +* :ref:`Using asyncio.wait_for() to enforce a timeout + `. + +* :ref:`Cancellation `. + +* :ref:`Using asyncio.sleep() `. + +* See also the main :ref:`Tasks documentation page `. + + +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 `. + +* See also the :ref:`Queues documentation page `. + + +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 `. + +* See also the :ref:`subprocess APIs ` + 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 `. + +* See also the :ref:`streams APIs ` + 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 `. + +* See also the documentation of asyncio + :ref:`synchronization primitives `. + + +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 + `. + +* See also the full list of + :ref:`asyncio-specific exceptions `. diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst index e1b47d2..19a0acd 100644 --- a/Doc/library/asyncio-eventloop.rst +++ b/Doc/library/asyncio-eventloop.rst @@ -1466,7 +1466,7 @@ during 5 seconds, and then stops the event loop:: .. seealso:: - A similar :ref:`current date ` example + A similar :ref:`current date ` example created with a coroutine and the :func:`run` function. diff --git a/Doc/library/asyncio-exceptions.rst b/Doc/library/asyncio-exceptions.rst index 7f3ed85..31bc1ed 100644 --- a/Doc/library/asyncio-exceptions.rst +++ b/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:: diff --git a/Doc/library/asyncio-queue.rst b/Doc/library/asyncio-queue.rst index fcad751..23d2f3c 100644 --- a/Doc/library/asyncio-queue.rst +++ b/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:: diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst index 80b7625..29163a2 100644 --- a/Doc/library/asyncio-stream.rst +++ b/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:: diff --git a/Doc/library/asyncio-subprocess.rst b/Doc/library/asyncio-subprocess.rst index 92c081b..ef8a1cb 100644 --- a/Doc/library/asyncio-subprocess.rst +++ b/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:: diff --git a/Doc/library/asyncio-sync.rst b/Doc/library/asyncio-sync.rst index 8da5aa8..f299885 100644 --- a/Doc/library/asyncio-sync.rst +++ b/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): diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst index 7e09b16..d3cfd5f 100644 --- a/Doc/library/asyncio-task.rst +++ b/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:: diff --git a/Doc/library/asyncio.rst b/Doc/library/asyncio.rst index c1b0408..25daeb6 100644 --- a/Doc/library/asyncio.rst +++ b/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 -- cgit v0.12