1 .. currentmodule:: asyncio 2 3 4 =================== 5 Low-level API Index 6 =================== 7 8 This page lists all low-level asyncio APIs. 9 10 11 Obtaining the Event Loop 12 ======================== 13 14 .. list-table:: 15 :widths: 50 50 16 :class: full-width-table 17 18 * - :func:`asyncio.get_running_loop` 19 - The **preferred** function to get the running event loop. 20 21 * - :func:`asyncio.get_event_loop` 22 - Get an event loop instance (current or via the policy). 23 24 * - :func:`asyncio.set_event_loop` 25 - Set the event loop as current via the current policy. 26 27 * - :func:`asyncio.new_event_loop` 28 - Create a new event loop. 29 30 31 .. rubric:: Examples 32 33 * :ref:`Using asyncio.get_running_loop() <asyncio_example_future>`. 34 35 36 Event Loop Methods 37 ================== 38 39 See also the main documentation section about the 40 :ref:`event loop methods <asyncio-event-loop>`. 41 42 .. rubric:: Lifecycle 43 .. list-table:: 44 :widths: 50 50 45 :class: full-width-table 46 47 * - :meth:`loop.run_until_complete` 48 - Run a Future/Task/awaitable until complete. 49 50 * - :meth:`loop.run_forever` 51 - Run the event loop forever. 52 53 * - :meth:`loop.stop` 54 - Stop the event loop. 55 56 * - :meth:`loop.close` 57 - Close the event loop. 58 59 * - :meth:`loop.is_running()` 60 - Return ``True`` if the event loop is running. 61 62 * - :meth:`loop.is_closed()` 63 - Return ``True`` if the event loop is closed. 64 65 * - ``await`` :meth:`loop.shutdown_asyncgens` 66 - Close asynchronous generators. 67 68 69 .. rubric:: Debugging 70 .. list-table:: 71 :widths: 50 50 72 :class: full-width-table 73 74 * - :meth:`loop.set_debug` 75 - Enable or disable the debug mode. 76 77 * - :meth:`loop.get_debug` 78 - Get the current debug mode. 79 80 81 .. rubric:: Scheduling Callbacks 82 .. list-table:: 83 :widths: 50 50 84 :class: full-width-table 85 86 * - :meth:`loop.call_soon` 87 - Invoke a callback soon. 88 89 * - :meth:`loop.call_soon_threadsafe` 90 - A thread-safe variant of :meth:`loop.call_soon`. 91 92 * - :meth:`loop.call_later` 93 - Invoke a callback *after* the given time. 94 95 * - :meth:`loop.call_at` 96 - Invoke a callback *at* the given time. 97 98 99 .. rubric:: Thread/Process Pool 100 .. list-table:: 101 :widths: 50 50 102 :class: full-width-table 103 104 * - ``await`` :meth:`loop.run_in_executor` 105 - Run a CPU-bound or other blocking function in 106 a :mod:`concurrent.futures` executor. 107 108 * - :meth:`loop.set_default_executor` 109 - Set the default executor for :meth:`loop.run_in_executor`. 110 111 112 .. rubric:: Tasks and Futures 113 .. list-table:: 114 :widths: 50 50 115 :class: full-width-table 116 117 * - :meth:`loop.create_future` 118 - Create a :class:`Future` object. 119 120 * - :meth:`loop.create_task` 121 - Schedule coroutine as a :class:`Task`. 122 123 * - :meth:`loop.set_task_factory` 124 - Set a factory used by :meth:`loop.create_task` to 125 create :class:`Tasks <Task>`. 126 127 * - :meth:`loop.get_task_factory` 128 - Get the factory :meth:`loop.create_task` uses 129 to create :class:`Tasks <Task>`. 130 131 132 .. rubric:: DNS 133 .. list-table:: 134 :widths: 50 50 135 :class: full-width-table 136 137 * - ``await`` :meth:`loop.getaddrinfo` 138 - Asynchronous version of :meth:`socket.getaddrinfo`. 139 140 * - ``await`` :meth:`loop.getnameinfo` 141 - Asynchronous version of :meth:`socket.getnameinfo`. 142 143 144 .. rubric:: Networking and IPC 145 .. list-table:: 146 :widths: 50 50 147 :class: full-width-table 148 149 * - ``await`` :meth:`loop.create_connection` 150 - Open a TCP connection. 151 152 * - ``await`` :meth:`loop.create_server` 153 - Create a TCP server. 154 155 * - ``await`` :meth:`loop.create_unix_connection` 156 - Open a Unix socket connection. 157 158 * - ``await`` :meth:`loop.create_unix_server` 159 - Create a Unix socket server. 160 161 * - ``await`` :meth:`loop.connect_accepted_socket` 162 - Wrap a :class:`~socket.socket` into a ``(transport, protocol)`` 163 pair. 164 165 * - ``await`` :meth:`loop.create_datagram_endpoint` 166 - Open a datagram (UDP) connection. 167 168 * - ``await`` :meth:`loop.sendfile` 169 - Send a file over a transport. 170 171 * - ``await`` :meth:`loop.start_tls` 172 - Upgrade an existing connection to TLS. 173 174 * - ``await`` :meth:`loop.connect_read_pipe` 175 - Wrap a read end of a pipe into a ``(transport, protocol)`` pair. 176 177 * - ``await`` :meth:`loop.connect_write_pipe` 178 - Wrap a write end of a pipe into a ``(transport, protocol)`` pair. 179 180 181 .. rubric:: Sockets 182 .. list-table:: 183 :widths: 50 50 184 :class: full-width-table 185 186 * - ``await`` :meth:`loop.sock_recv` 187 - Receive data from the :class:`~socket.socket`. 188 189 * - ``await`` :meth:`loop.sock_recv_into` 190 - Receive data from the :class:`~socket.socket` into a buffer. 191 192 * - ``await`` :meth:`loop.sock_sendall` 193 - Send data to the :class:`~socket.socket`. 194 195 * - ``await`` :meth:`loop.sock_connect` 196 - Connect the :class:`~socket.socket`. 197 198 * - ``await`` :meth:`loop.sock_accept` 199 - Accept a :class:`~socket.socket` connection. 200 201 * - ``await`` :meth:`loop.sock_sendfile` 202 - Send a file over the :class:`~socket.socket`. 203 204 * - :meth:`loop.add_reader` 205 - Start watching a file descriptor for read availability. 206 207 * - :meth:`loop.remove_reader` 208 - Stop watching a file descriptor for read availability. 209 210 * - :meth:`loop.add_writer` 211 - Start watching a file descriptor for write availability. 212 213 * - :meth:`loop.remove_writer` 214 - Stop watching a file descriptor for write availability. 215 216 217 .. rubric:: Unix Signals 218 .. list-table:: 219 :widths: 50 50 220 :class: full-width-table 221 222 * - :meth:`loop.add_signal_handler` 223 - Add a handler for a :mod:`signal`. 224 225 * - :meth:`loop.remove_signal_handler` 226 - Remove a handler for a :mod:`signal`. 227 228 229 .. rubric:: Subprocesses 230 .. list-table:: 231 :widths: 50 50 232 :class: full-width-table 233 234 * - :meth:`loop.subprocess_exec` 235 - Spawn a subprocess. 236 237 * - :meth:`loop.subprocess_shell` 238 - Spawn a subprocess from a shell command. 239 240 241 .. rubric:: Error Handling 242 .. list-table:: 243 :widths: 50 50 244 :class: full-width-table 245 246 * - :meth:`loop.call_exception_handler` 247 - Call the exception handler. 248 249 * - :meth:`loop.set_exception_handler` 250 - Set a new exception handler. 251 252 * - :meth:`loop.get_exception_handler` 253 - Get the current exception handler. 254 255 * - :meth:`loop.default_exception_handler` 256 - The default exception handler implementation. 257 258 259 .. rubric:: Examples 260 261 * :ref:`Using asyncio.get_event_loop() and loop.run_forever() 262 <asyncio_example_lowlevel_helloworld>`. 263 264 * :ref:`Using loop.call_later() <asyncio_example_call_later>`. 265 266 * Using ``loop.create_connection()`` to implement 267 :ref:`an echo-client <asyncio_example_tcp_echo_client_protocol>`. 268 269 * Using ``loop.create_connection()`` to 270 :ref:`connect a socket <asyncio_example_create_connection>`. 271 272 * :ref:`Using add_reader() to watch an FD for read events 273 <asyncio_example_watch_fd>`. 274 275 * :ref:`Using loop.add_signal_handler() <asyncio_example_unix_signals>`. 276 277 * :ref:`Using loop.subprocess_exec() <asyncio_example_subprocess_proto>`. 278 279 280 Transports 281 ========== 282 283 All transports implement the following methods: 284 285 .. list-table:: 286 :widths: 50 50 287 :class: full-width-table 288 289 * - :meth:`transport.close() <BaseTransport.close>` 290 - Close the transport. 291 292 * - :meth:`transport.is_closing() <BaseTransport.is_closing>` 293 - Return ``True`` if the transport is closing or is closed. 294 295 * - :meth:`transport.get_extra_info() <BaseTransport.get_extra_info>` 296 - Request for information about the transport. 297 298 * - :meth:`transport.set_protocol() <BaseTransport.set_protocol>` 299 - Set a new protocol. 300 301 * - :meth:`transport.get_protocol() <BaseTransport.get_protocol>` 302 - Return the current protocol. 303 304 305 Transports that can receive data (TCP and Unix connections, 306 pipes, etc). Returned from methods like 307 :meth:`loop.create_connection`, :meth:`loop.create_unix_connection`, 308 :meth:`loop.connect_read_pipe`, etc: 309 310 .. rubric:: Read Transports 311 .. list-table:: 312 :widths: 50 50 313 :class: full-width-table 314 315 * - :meth:`transport.is_reading() <ReadTransport.is_reading>` 316 - Return ``True`` if the transport is receiving. 317 318 * - :meth:`transport.pause_reading() <ReadTransport.pause_reading>` 319 - Pause receiving. 320 321 * - :meth:`transport.resume_reading() <ReadTransport.resume_reading>` 322 - Resume receiving. 323 324 325 Transports that can Send data (TCP and Unix connections, 326 pipes, etc). Returned from methods like 327 :meth:`loop.create_connection`, :meth:`loop.create_unix_connection`, 328 :meth:`loop.connect_write_pipe`, etc: 329 330 .. rubric:: Write Transports 331 .. list-table:: 332 :widths: 50 50 333 :class: full-width-table 334 335 * - :meth:`transport.write() <WriteTransport.write>` 336 - Write data to the transport. 337 338 * - :meth:`transport.writelines() <WriteTransport.writelines>` 339 - Write buffers to the transport. 340 341 * - :meth:`transport.can_write_eof() <WriteTransport.can_write_eof>` 342 - Return :const:`True` if the transport supports sending EOF. 343 344 * - :meth:`transport.write_eof() <WriteTransport.write_eof>` 345 - Close and send EOF after flushing buffered data. 346 347 * - :meth:`transport.abort() <WriteTransport.abort>` 348 - Close the transport immediately. 349 350 * - :meth:`transport.get_write_buffer_size() 351 <WriteTransport.get_write_buffer_size>` 352 - Return high and low water marks for write flow control. 353 354 * - :meth:`transport.set_write_buffer_limits() 355 <WriteTransport.set_write_buffer_limits>` 356 - Set new high and low water marks for write flow control. 357 358 359 Transports returned by :meth:`loop.create_datagram_endpoint`: 360 361 .. rubric:: Datagram Transports 362 .. list-table:: 363 :widths: 50 50 364 :class: full-width-table 365 366 * - :meth:`transport.sendto() <DatagramTransport.sendto>` 367 - Send data to the remote peer. 368 369 * - :meth:`transport.abort() <DatagramTransport.abort>` 370 - Close the transport immediately. 371 372 373 Low-level transport abstraction over subprocesses. 374 Returned by :meth:`loop.subprocess_exec` and 375 :meth:`loop.subprocess_shell`: 376 377 .. rubric:: Subprocess Transports 378 .. list-table:: 379 :widths: 50 50 380 :class: full-width-table 381 382 * - :meth:`transport.get_pid() <SubprocessTransport.get_pid>` 383 - Return the subprocess process id. 384 385 * - :meth:`transport.get_pipe_transport() 386 <SubprocessTransport.get_pipe_transport>` 387 - Return the transport for the requested communication pipe 388 (*stdin*, *stdout*, or *stderr*). 389 390 * - :meth:`transport.get_returncode() <SubprocessTransport.get_returncode>` 391 - Return the subprocess return code. 392 393 * - :meth:`transport.kill() <SubprocessTransport.kill>` 394 - Kill the subprocess. 395 396 * - :meth:`transport.send_signal() <SubprocessTransport.send_signal>` 397 - Send a signal to the subprocess. 398 399 * - :meth:`transport.terminate() <SubprocessTransport.terminate>` 400 - Stop the subprocess. 401 402 * - :meth:`transport.close() <SubprocessTransport.close>` 403 - Kill the subprocess and close all pipes. 404 405 406 Protocols 407 ========= 408 409 Protocol classes can implement the following **callback methods**: 410 411 .. list-table:: 412 :widths: 50 50 413 :class: full-width-table 414 415 * - ``callback`` :meth:`connection_made() <BaseProtocol.connection_made>` 416 - Called when a connection is made. 417 418 * - ``callback`` :meth:`connection_lost() <BaseProtocol.connection_lost>` 419 - Called when the connection is lost or closed. 420 421 * - ``callback`` :meth:`pause_writing() <BaseProtocol.pause_writing>` 422 - Called when the transport's buffer goes over the high water mark. 423 424 * - ``callback`` :meth:`resume_writing() <BaseProtocol.resume_writing>` 425 - Called when the transport's buffer drains below the low water mark. 426 427 428 .. rubric:: Streaming Protocols (TCP, Unix Sockets, Pipes) 429 .. list-table:: 430 :widths: 50 50 431 :class: full-width-table 432 433 * - ``callback`` :meth:`data_received() <Protocol.data_received>` 434 - Called when some data is received. 435 436 * - ``callback`` :meth:`eof_received() <Protocol.eof_received>` 437 - Called when an EOF is received. 438 439 440 .. rubric:: Buffered Streaming Protocols 441 .. list-table:: 442 :widths: 50 50 443 :class: full-width-table 444 445 * - ``callback`` :meth:`get_buffer() <BufferedProtocol.get_buffer>` 446 - Called to allocate a new receive buffer. 447 448 * - ``callback`` :meth:`buffer_updated() <BufferedProtocol.buffer_updated>` 449 - Called when the buffer was updated with the received data. 450 451 * - ``callback`` :meth:`eof_received() <BufferedProtocol.eof_received>` 452 - Called when an EOF is received. 453 454 455 .. rubric:: Datagram Protocols 456 .. list-table:: 457 :widths: 50 50 458 :class: full-width-table 459 460 * - ``callback`` :meth:`datagram_received() 461 <DatagramProtocol.datagram_received>` 462 - Called when a datagram is received. 463 464 * - ``callback`` :meth:`error_received() <DatagramProtocol.error_received>` 465 - Called when a previous send or receive operation raises an 466 :class:`OSError`. 467 468 469 .. rubric:: Subprocess Protocols 470 .. list-table:: 471 :widths: 50 50 472 :class: full-width-table 473 474 * - ``callback`` :meth:`pipe_data_received() 475 <SubprocessProtocol.pipe_data_received>` 476 - Called when the child process writes data into its 477 *stdout* or *stderr* pipe. 478 479 * - ``callback`` :meth:`pipe_connection_lost() 480 <SubprocessProtocol.pipe_connection_lost>` 481 - Called when one of the pipes communicating with 482 the child process is closed. 483 484 * - ``callback`` :meth:`process_exited() 485 <SubprocessProtocol.process_exited>` 486 - Called when the child process has exited. 487 488 489 Event Loop Policies 490 =================== 491 492 Policies is a low-level mechanism to alter the behavior of 493 functions like :func:`asyncio.get_event_loop`. See also 494 the main :ref:`policies section <asyncio-policies>` for more 495 details. 496 497 498 .. rubric:: Accessing Policies 499 .. list-table:: 500 :widths: 50 50 501 :class: full-width-table 502 503 * - :meth:`asyncio.get_event_loop_policy` 504 - Return the current process-wide policy. 505 506 * - :meth:`asyncio.set_event_loop_policy` 507 - Set a new process-wide policy. 508 509 * - :class:`AbstractEventLoopPolicy` 510 - Base class for policy objects. 511
