1.. currentmodule:: asyncio
2
3
4====================
5High-level API Index
6====================
7
8This page lists all high-level async/await enabled asyncio APIs.
9
10
11Tasks
12=====
13
14Utilities to run asyncio programs, create Tasks, and
15await on multiple things with timeouts.
16
17.. list-table::
18    :widths: 50 50
19    :class: full-width-table
20
21    * - :func:`run`
22      - Create event loop, run a coroutine, close the loop.
23
24    * - :class:`Runner`
25      - A context manager that simplifies multiple async function calls.
26
27    * - :class:`Task`
28      - Task object.
29
30    * - :class:`TaskGroup`
31      - A context manager that holds a group of tasks. Provides
32        a convenient and reliable way to wait for all tasks in the group to
33        finish.
34
35    * - :func:`create_task`
36      - Start an asyncio Task, then returns it.
37
38    * - :func:`current_task`
39      - Return the current Task.
40
41    * - :func:`all_tasks`
42      - Return all tasks that are not yet finished for an event loop.
43
44    * - ``await`` :func:`sleep`
45      - Sleep for a number of seconds.
46
47    * - ``await`` :func:`gather`
48      - Schedule and wait for things concurrently.
49
50    * - ``await`` :func:`wait_for`
51      - Run with a timeout.
52
53    * - ``await`` :func:`shield`
54      - Shield from cancellation.
55
56    * - ``await`` :func:`wait`
57      - Monitor for completion.
58
59    * - :func:`timeout`
60      - Run with a timeout. Useful in cases when ``wait_for`` is not suitable.
61
62    * - :func:`to_thread`
63      - Asynchronously run a function in a separate OS thread.
64
65    * - :func:`run_coroutine_threadsafe`
66      - Schedule a coroutine from another OS thread.
67
68    * - ``for in`` :func:`as_completed`
69      - Monitor for completion with a ``for`` loop.
70
71
72.. rubric:: Examples
73
74* :ref:`Using asyncio.gather() to run things in parallel
75  <asyncio_example_gather>`.
76
77* :ref:`Using asyncio.wait_for() to enforce a timeout
78  <asyncio_example_waitfor>`.
79
80* :ref:`Cancellation <asyncio_example_task_cancel>`.
81
82* :ref:`Using asyncio.sleep() <asyncio_example_sleep>`.
83
84* See also the main :ref:`Tasks documentation page <coroutine>`.
85
86
87Queues
88======
89
90Queues should be used to distribute work amongst multiple asyncio Tasks,
91implement connection pools, and pub/sub patterns.
92
93
94.. list-table::
95    :widths: 50 50
96    :class: full-width-table
97
98    * - :class:`Queue`
99      - A FIFO queue.
100
101    * - :class:`PriorityQueue`
102      - A priority queue.
103
104    * - :class:`LifoQueue`
105      - A LIFO queue.
106
107
108.. rubric:: Examples
109
110* :ref:`Using asyncio.Queue to distribute workload between several
111  Tasks <asyncio_example_queue_dist>`.
112
113* See also the :ref:`Queues documentation page <asyncio-queues>`.
114
115
116Subprocesses
117============
118
119Utilities to spawn subprocesses and run shell commands.
120
121.. list-table::
122    :widths: 50 50
123    :class: full-width-table
124
125    * - ``await`` :func:`create_subprocess_exec`
126      - Create a subprocess.
127
128    * - ``await`` :func:`create_subprocess_shell`
129      - Run a shell command.
130
131
132.. rubric:: Examples
133
134* :ref:`Executing a shell command <asyncio_example_subprocess_shell>`.
135
136* See also the :ref:`subprocess APIs <asyncio-subprocess>`
137  documentation.
138
139
140Streams
141=======
142
143High-level APIs to work with network IO.
144
145.. list-table::
146    :widths: 50 50
147    :class: full-width-table
148
149    * - ``await`` :func:`open_connection`
150      -  Establish a TCP connection.
151
152    * - ``await`` :func:`open_unix_connection`
153      -  Establish a Unix socket connection.
154
155    * - ``await`` :func:`start_server`
156      - Start a TCP server.
157
158    * - ``await`` :func:`start_unix_server`
159      - Start a Unix socket server.
160
161    * - :class:`StreamReader`
162      - High-level async/await object to receive network data.
163
164    * - :class:`StreamWriter`
165      - High-level async/await object to send network data.
166
167
168.. rubric:: Examples
169
170* :ref:`Example TCP client <asyncio_example_stream>`.
171
172* See also the :ref:`streams APIs <asyncio-streams>`
173  documentation.
174
175
176Synchronization
177===============
178
179Threading-like synchronization primitives that can be used in Tasks.
180
181.. list-table::
182    :widths: 50 50
183    :class: full-width-table
184
185    * - :class:`Lock`
186      - A mutex lock.
187
188    * - :class:`Event`
189      - An event object.
190
191    * - :class:`Condition`
192      - A condition object.
193
194    * - :class:`Semaphore`
195      - A semaphore.
196
197    * - :class:`BoundedSemaphore`
198      - A bounded semaphore.
199
200    * - :class:`Barrier`
201      - A barrier object.
202
203
204.. rubric:: Examples
205
206* :ref:`Using asyncio.Event <asyncio_example_sync_event>`.
207
208* :ref:`Using asyncio.Barrier <asyncio_example_barrier>`.
209
210* See also the documentation of asyncio
211  :ref:`synchronization primitives <asyncio-sync>`.
212
213
214Exceptions
215==========
216
217.. list-table::
218    :widths: 50 50
219    :class: full-width-table
220
221
222    * - :exc:`asyncio.CancelledError`
223      - Raised when a Task is cancelled. See also :meth:`Task.cancel`.
224
225    * - :exc:`asyncio.BrokenBarrierError`
226      - Raised when a Barrier is broken. See also :meth:`Barrier.wait`.
227
228
229.. rubric:: Examples
230
231* :ref:`Handling CancelledError to run code on cancellation request
232  <asyncio_example_task_cancel>`.
233
234* See also the full list of
235  :ref:`asyncio-specific exceptions <asyncio-exceptions>`.
236