[Python-checkins] bpo-33649: Add high-level APIs cheat-sheet (GH-9319)
Yury Selivanov
webhook-mailer at python.org
Fri Sep 14 18:11:27 EDT 2018
https://github.com/python/cpython/commit/7372c3bbefb4763dbd1b6d66f7971bef28c0f056
commit: 7372c3bbefb4763dbd1b6d66f7971bef28c0f056
branch: master
author: Yury Selivanov <yury at magic.io>
committer: GitHub <noreply at github.com>
date: 2018-09-14T15:11:24-07:00
summary:
bpo-33649: Add high-level APIs cheat-sheet (GH-9319)
files:
A Doc/library/asyncio-api-index.rst
M Doc/library/asyncio-eventloop.rst
M Doc/library/asyncio-exceptions.rst
M Doc/library/asyncio-queue.rst
M Doc/library/asyncio-stream.rst
M Doc/library/asyncio-subprocess.rst
M Doc/library/asyncio-sync.rst
M Doc/library/asyncio-task.rst
M Doc/library/asyncio.rst
diff --git a/Doc/library/asyncio-api-index.rst b/Doc/library/asyncio-api-index.rst
new file mode 100644
index 000000000000..a4d0e1ba32e1
--- /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
+ <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>`.
diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst
index e1b47d2588cd..19a0acdfd55e 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 <asyncio-date-coroutine>` example
+ A similar :ref:`current date <asyncio_example_sleep>` 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 7f3ed857943d..31bc1edf0142 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 fcad751fe19d..23d2f3cb1d7c 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 80b76253d065..29163a217dce 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 92c081b70bfc..ef8a1cbb4b1c 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 8da5aa81ab9e..f29988554cee 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 7e09b166ebc9..d3cfd5ff31ce 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 c1b04086c35f..25daeb6b8531 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
More information about the Python-checkins
mailing list