python_doc_md/Intermediate/library/asyncio-api-index.md

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

---

run{.interpreted-text role="func"} Create event loop, run a coroutine, close the loop.

Runner{.interpreted-text role="class"} A context manager that simplifies multiple async function calls.

Task{.interpreted-text role="class"} Task object.

TaskGroup{.interpreted-text role="class"} 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.

create_task{.interpreted-text role="func"} Start an asyncio Task, then returns it.

current_task{.interpreted-text role="func"} Return the current Task.

all_tasks{.interpreted-text role="func"} Return all tasks that are not yet finished for an event loop.

await sleep{.interpreted-text role="func"} Sleep for a number of seconds.

await gather{.interpreted-text role="func"} Schedule and wait for things concurrently.

await wait_for{.interpreted-text role="func"} Run with a timeout.

await shield{.interpreted-text role="func"} Shield from cancellation.

await wait{.interpreted-text role="func"} Monitor for completion.

timeout{.interpreted-text role="func"} Run with a timeout. Useful in cases when wait_for is not suitable.

to_thread{.interpreted-text role="func"} Asynchronously run a function in a separate OS thread.

run_coroutine_threadsafe{.interpreted-text role="func"} Schedule a coroutine from another OS thread.

for in as_completed{.interpreted-text role="func"} Monitor for completion with a for loop.

---

Examples

• Using asyncio.gather() to run things in parallel <asyncio_example_gather>{.interpreted-text role="ref"}.
• Using asyncio.wait_for() to enforce a timeout <asyncio_example_waitfor>{.interpreted-text role="ref"}.
• Cancellation <asyncio_example_task_cancel>{.interpreted-text role="ref"}.
• Using asyncio.sleep() <asyncio_example_sleep>{.interpreted-text role="ref"}.
• See also the main Tasks documentation page <coroutine>{.interpreted-text role="ref"}.

Queues

Queues should be used to distribute work amongst multiple asyncio Tasks, implement connection pools, and pub/sub patterns.

---

Queue{.interpreted-text role="class"} A FIFO queue.

PriorityQueue{.interpreted-text role="class"} A priority queue.

LifoQueue{.interpreted-text role="class"} A LIFO queue.

---

Examples

• Using asyncio.Queue to distribute workload between several Tasks <asyncio_example_queue_dist>{.interpreted-text role="ref"}.
• See also the Queues documentation page <asyncio-queues>{.interpreted-text role="ref"}.

Subprocesses

Utilities to spawn subprocesses and run shell commands.

---

await create_subprocess_exec{.interpreted-text role="func"} Create a subprocess.

await create_subprocess_shell{.interpreted-text role="func"} Run a shell command.

---

Examples

• Executing a shell command <asyncio_example_subprocess_shell>{.interpreted-text role="ref"}.
• See also the subprocess APIs <asyncio-subprocess>{.interpreted-text role="ref"} documentation.

Streams

High-level APIs to work with network IO.

---

await open_connection{.interpreted-text role="func"} Establish a TCP connection.

await open_unix_connection{.interpreted-text role="func"} Establish a Unix socket connection.

await start_server{.interpreted-text role="func"} Start a TCP server.

await start_unix_server{.interpreted-text role="func"} Start a Unix socket server.

StreamReader{.interpreted-text role="class"} High-level async/await object to receive network data.

StreamWriter{.interpreted-text role="class"} High-level async/await object to send network data.

---

Examples

• Example TCP client <asyncio_example_stream>{.interpreted-text role="ref"}.
• See also the streams APIs <asyncio-streams>{.interpreted-text role="ref"} documentation.

Synchronization

Threading-like synchronization primitives that can be used in Tasks.

---

Lock{.interpreted-text role="class"} A mutex lock.

Event{.interpreted-text role="class"} An event object.

Condition{.interpreted-text role="class"} A condition object.

Semaphore{.interpreted-text role="class"} A semaphore.

BoundedSemaphore{.interpreted-text role="class"} A bounded semaphore.

Barrier{.interpreted-text role="class"} A barrier object.

---

Examples

• Using asyncio.Event <asyncio_example_sync_event>{.interpreted-text role="ref"}.
• Using asyncio.Barrier <asyncio_example_barrier>{.interpreted-text role="ref"}.
• See also the documentation of asyncio synchronization primitives <asyncio-sync>{.interpreted-text role="ref"}.

Exceptions

---

asyncio.CancelledError{.interpreted-text role="exc"} Raised when a Task is cancelled. See also Task.cancel{.interpreted-text role="meth"}.

asyncio.BrokenBarrierError{.interpreted-text role="exc"} Raised when a Barrier is broken. See also Barrier.wait{.interpreted-text role="meth"}.

---

Examples

• Handling CancelledError to run code on cancellation request <asyncio_example_task_cancel>{.interpreted-text role="ref"}.
• See also the full list of asyncio-specific exceptions <asyncio-exceptions>{.interpreted-text role="ref"}.