Debian Codegraph @

Doc/library/asyncio-api-index.rst

raw
1 .. currentmodule:: asyncio
2
3
4 ====================
5 High-level API Index
6 ====================
7
8 This page lists all high-level async/await enabled asyncio APIs.
9
10
11 Tasks
12 =====
13
14 Utilities to run asyncio programs, create Tasks, and
15 await 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
87 Queues
88 ======
89
90 Queues should be used to distribute work amongst multiple asyncio Tasks,
91 implement 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
116 Subprocesses
117 ============
118
119 Utilities 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
140 Streams
141 =======
142
143 High-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
176 Synchronization
177 ===============
178
179 Threading-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
214 Exceptions
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>`.