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