asyncio-api-index.rst

.. currentmodule:: asyncio

High-level API 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.

:func:`run`	Create event loop, run a coroutine, close the loop.
:class:`Runner`	A context manager that simplifies multiple async function calls.
:class:`Task`	Task object.
:class:`TaskGroup`	A context manager that holds a group of tasks. Provides a convenient and reliable way to wait for all tasks in the group to finish.
:func:`create_task`	Start an asyncio Task, then returns it.
:func:`current_task`	Return the current Task.
:func:`all_tasks`	Return all tasks that are not yet finished for an event loop.
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 completion.
:func:`timeout`	Run with a timeout. Useful in cases when wait_for is not suitable.
:func:`to_thread`	Asynchronously run a function in a separate OS thread.
:func:`run_coroutine_threadsafe`	Schedule a coroutine from another OS thread.
for in :func:`as_completed`	Monitor for completion with a for loop.

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.

:class:`Queue`	A FIFO queue.
:class:`PriorityQueue`	A priority queue.
:class:`LifoQueue`	A LIFO queue.

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.

await :func:`create_subprocess_exec`	Create a subprocess.
await :func:`create_subprocess_shell`	Run a shell command.

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.

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.

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.

:class:`Lock`	A mutex lock.
:class:`Event`	An event object.
:class:`Condition`	A condition object.
:class:`Semaphore`	A semaphore.
:class:`BoundedSemaphore`	A bounded semaphore.
:class:`Barrier`	A barrier object.

Examples

• :ref:`Using asyncio.Event <asyncio_example_sync_event>`.
• :ref:`Using asyncio.Barrier <asyncio_example_barrier>`.
• See also the documentation of asyncio :ref:`synchronization primitives <asyncio-sync>`.

Exceptions

:exc:`asyncio.CancelledError`	Raised when a Task is cancelled. See also :meth:`Task.cancel`.
:exc:`asyncio.BrokenBarrierError`	Raised when a Barrier is broken. See also :meth:`Barrier.wait`.

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>`.