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 * - :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 73 Queues 74 ====== 75 76 Queues should be used to distribute work amongst multiple asyncio Tasks, 77 implement 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 102 Subprocesses 103 ============ 104 105 Utilities 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 126 Streams 127 ======= 128 129 High-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 162 Synchronization 163 =============== 164 165 Threading-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 195 Exceptions 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
