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