Spaces:
Running on Zero
Running on Zero
File size: 23,389 Bytes
9273228 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 | ::: currentmodule
asyncio
:::
# Low-level API Index
This page lists all low-level asyncio APIs.
## Obtaining the Event Loop
----------------------------------------------------------- -------------------------------------------------------------------------
`asyncio.get_running_loop`{.interpreted-text role="func"} The **preferred** function to get the running event loop.
`asyncio.get_event_loop`{.interpreted-text role="func"} Get an event loop instance (running or current via the current policy).
`asyncio.set_event_loop`{.interpreted-text role="func"} Set the event loop as current via the current policy.
`asyncio.new_event_loop`{.interpreted-text role="func"} Create a new event loop.
----------------------------------------------------------- -------------------------------------------------------------------------
**Examples**
- `Using asyncio.get_running_loop() <asyncio_example_future>`{.interpreted-text role="ref"}.
## Event Loop Methods
See also the main documentation section about the `asyncio-event-loop-methods`{.interpreted-text role="ref"}.
**Lifecycle**
------------------------------------------------------------------ ---------------------------------------------
`loop.run_until_complete`{.interpreted-text role="meth"} Run a Future/Task/awaitable until complete.
`loop.run_forever`{.interpreted-text role="meth"} Run the event loop forever.
`loop.stop`{.interpreted-text role="meth"} Stop the event loop.
`loop.close`{.interpreted-text role="meth"} Close the event loop.
`loop.is_running`{.interpreted-text role="meth"} Return `True` if the event loop is running.
`loop.is_closed`{.interpreted-text role="meth"} Return `True` if the event loop is closed.
`await` `loop.shutdown_asyncgens`{.interpreted-text role="meth"} Close asynchronous generators.
------------------------------------------------------------------ ---------------------------------------------
**Debugging**
------------------------------------------------- -----------------------------------
`loop.set_debug`{.interpreted-text role="meth"} Enable or disable the debug mode.
`loop.get_debug`{.interpreted-text role="meth"} Get the current debug mode.
------------------------------------------------- -----------------------------------
**Scheduling Callbacks**
------------------------------------------------------------ ---------------------------------------------------------------------------
`loop.call_soon`{.interpreted-text role="meth"} Invoke a callback soon.
`loop.call_soon_threadsafe`{.interpreted-text role="meth"} A thread-safe variant of `loop.call_soon`{.interpreted-text role="meth"}.
`loop.call_later`{.interpreted-text role="meth"} Invoke a callback *after* the given time.
`loop.call_at`{.interpreted-text role="meth"} Invoke a callback *at* the given time.
------------------------------------------------------------ ---------------------------------------------------------------------------
**Thread/Interpreter/Process Pool**
--------------------------------------------------------------- --------------------------------------------------------------------------------------------------------------
`await` `loop.run_in_executor`{.interpreted-text role="meth"} Run a CPU-bound or other blocking function in a `concurrent.futures`{.interpreted-text role="mod"} executor.
`loop.set_default_executor`{.interpreted-text role="meth"} Set the default executor for `loop.run_in_executor`{.interpreted-text role="meth"}.
--------------------------------------------------------------- --------------------------------------------------------------------------------------------------------------
**Tasks and Futures**
-------------------------------------------------------- -----------------------------------------------------------------------------------------------------------------------------------
`loop.create_future`{.interpreted-text role="meth"} Create a `Future`{.interpreted-text role="class"} object.
`loop.create_task`{.interpreted-text role="meth"} Schedule coroutine as a `Task`{.interpreted-text role="class"}.
`loop.set_task_factory`{.interpreted-text role="meth"} Set a factory used by `loop.create_task`{.interpreted-text role="meth"} to create `Tasks <Task>`{.interpreted-text role="class"}.
`loop.get_task_factory`{.interpreted-text role="meth"} Get the factory `loop.create_task`{.interpreted-text role="meth"} uses to create `Tasks <Task>`{.interpreted-text role="class"}.
-------------------------------------------------------- -----------------------------------------------------------------------------------------------------------------------------------
**DNS**
----------------------------------------------------------- ------------------------------------------------------------------------------
`await` `loop.getaddrinfo`{.interpreted-text role="meth"} Asynchronous version of `socket.getaddrinfo`{.interpreted-text role="meth"}.
`await` `loop.getnameinfo`{.interpreted-text role="meth"} Asynchronous version of `socket.getnameinfo`{.interpreted-text role="meth"}.
----------------------------------------------------------- ------------------------------------------------------------------------------
**Networking and IPC**
------------------------------------------------------------------------ ----------------------------------------------------------------------------------------------
`await` `loop.create_connection`{.interpreted-text role="meth"} Open a TCP connection.
`await` `loop.create_server`{.interpreted-text role="meth"} Create a TCP server.
`await` `loop.create_unix_connection`{.interpreted-text role="meth"} Open a Unix socket connection.
`await` `loop.create_unix_server`{.interpreted-text role="meth"} Create a Unix socket server.
`await` `loop.connect_accepted_socket`{.interpreted-text role="meth"} Wrap a `~socket.socket`{.interpreted-text role="class"} into a `(transport, protocol)` pair.
`await` `loop.create_datagram_endpoint`{.interpreted-text role="meth"} Open a datagram (UDP) connection.
`await` `loop.sendfile`{.interpreted-text role="meth"} Send a file over a transport.
`await` `loop.start_tls`{.interpreted-text role="meth"} Upgrade an existing connection to TLS.
`await` `loop.connect_read_pipe`{.interpreted-text role="meth"} Wrap a read end of a pipe into a `(transport, protocol)` pair.
`await` `loop.connect_write_pipe`{.interpreted-text role="meth"} Wrap a write end of a pipe into a `(transport, protocol)` pair.
------------------------------------------------------------------------ ----------------------------------------------------------------------------------------------
**Sockets**
------------------------------------------------------------------ ------------------------------------------------------------------------------------------------
`await` `loop.sock_recv`{.interpreted-text role="meth"} Receive data from the `~socket.socket`{.interpreted-text role="class"}.
`await` `loop.sock_recv_into`{.interpreted-text role="meth"} Receive data from the `~socket.socket`{.interpreted-text role="class"} into a buffer.
`await` `loop.sock_recvfrom`{.interpreted-text role="meth"} Receive a datagram from the `~socket.socket`{.interpreted-text role="class"}.
`await` `loop.sock_recvfrom_into`{.interpreted-text role="meth"} Receive a datagram from the `~socket.socket`{.interpreted-text role="class"} into a buffer.
`await` `loop.sock_sendall`{.interpreted-text role="meth"} Send data to the `~socket.socket`{.interpreted-text role="class"}.
`await` `loop.sock_sendto`{.interpreted-text role="meth"} Send a datagram via the `~socket.socket`{.interpreted-text role="class"} to the given address.
`await` `loop.sock_connect`{.interpreted-text role="meth"} Connect the `~socket.socket`{.interpreted-text role="class"}.
`await` `loop.sock_accept`{.interpreted-text role="meth"} Accept a `~socket.socket`{.interpreted-text role="class"} connection.
`await` `loop.sock_sendfile`{.interpreted-text role="meth"} Send a file over the `~socket.socket`{.interpreted-text role="class"}.
`loop.add_reader`{.interpreted-text role="meth"} Start watching a file descriptor for read availability.
`loop.remove_reader`{.interpreted-text role="meth"} Stop watching a file descriptor for read availability.
`loop.add_writer`{.interpreted-text role="meth"} Start watching a file descriptor for write availability.
`loop.remove_writer`{.interpreted-text role="meth"} Stop watching a file descriptor for write availability.
------------------------------------------------------------------ ------------------------------------------------------------------------------------------------
**Unix Signals**
------------------------------------------------------------- ----------------------------------------------------------------
`loop.add_signal_handler`{.interpreted-text role="meth"} Add a handler for a `signal`{.interpreted-text role="mod"}.
`loop.remove_signal_handler`{.interpreted-text role="meth"} Remove a handler for a `signal`{.interpreted-text role="mod"}.
------------------------------------------------------------- ----------------------------------------------------------------
**Subprocesses**
-------------------------------------------------------- ------------------------------------------
`loop.subprocess_exec`{.interpreted-text role="meth"} Spawn a subprocess.
`loop.subprocess_shell`{.interpreted-text role="meth"} Spawn a subprocess from a shell command.
-------------------------------------------------------- ------------------------------------------
**Error Handling**
----------------------------------------------------------------- -----------------------------------------------
`loop.call_exception_handler`{.interpreted-text role="meth"} Call the exception handler.
`loop.set_exception_handler`{.interpreted-text role="meth"} Set a new exception handler.
`loop.get_exception_handler`{.interpreted-text role="meth"} Get the current exception handler.
`loop.default_exception_handler`{.interpreted-text role="meth"} The default exception handler implementation.
----------------------------------------------------------------- -----------------------------------------------
**Examples**
- `Using asyncio.new_event_loop() and loop.run_forever()
<asyncio_example_lowlevel_helloworld>`{.interpreted-text role="ref"}.
- `Using loop.call_later() <asyncio_example_call_later>`{.interpreted-text role="ref"}.
- Using `loop.create_connection()` to implement `an echo-client <asyncio_example_tcp_echo_client_protocol>`{.interpreted-text role="ref"}.
- Using `loop.create_connection()` to `connect a socket <asyncio_example_create_connection>`{.interpreted-text role="ref"}.
- `Using add_reader() to watch an FD for read events
<asyncio_example_watch_fd>`{.interpreted-text role="ref"}.
- `Using loop.add_signal_handler() <asyncio_example_unix_signals>`{.interpreted-text role="ref"}.
- `Using loop.subprocess_exec() <asyncio_example_subprocess_proto>`{.interpreted-text role="ref"}.
## Transports
All transports implement the following methods:
-------------------------------------------------------------------------------------------- ---------------------------------------------------------
`transport.close() <BaseTransport.close>`{.interpreted-text role="meth"} Close the transport.
`transport.is_closing() <BaseTransport.is_closing>`{.interpreted-text role="meth"} Return `True` if the transport is closing or is closed.
`transport.get_extra_info() <BaseTransport.get_extra_info>`{.interpreted-text role="meth"} Request for information about the transport.
`transport.set_protocol() <BaseTransport.set_protocol>`{.interpreted-text role="meth"} Set a new protocol.
`transport.get_protocol() <BaseTransport.get_protocol>`{.interpreted-text role="meth"} Return the current protocol.
-------------------------------------------------------------------------------------------- ---------------------------------------------------------
Transports that can receive data (TCP and Unix connections, pipes, etc). Returned from methods like `loop.create_connection`{.interpreted-text role="meth"}, `loop.create_unix_connection`{.interpreted-text role="meth"}, `loop.connect_read_pipe`{.interpreted-text role="meth"}, etc:
**Read Transports**
-------------------------------------------------------------------------------------------- ----------------------------------------------
`transport.is_reading() <ReadTransport.is_reading>`{.interpreted-text role="meth"} Return `True` if the transport is receiving.
`transport.pause_reading() <ReadTransport.pause_reading>`{.interpreted-text role="meth"} Pause receiving.
`transport.resume_reading() <ReadTransport.resume_reading>`{.interpreted-text role="meth"} Resume receiving.
-------------------------------------------------------------------------------------------- ----------------------------------------------
Transports that can Send data (TCP and Unix connections, pipes, etc). Returned from methods like `loop.create_connection`{.interpreted-text role="meth"}, `loop.create_unix_connection`{.interpreted-text role="meth"}, `loop.connect_write_pipe`{.interpreted-text role="meth"}, etc:
**Write Transports**
------------------------------------------------------------------------------------------- --------------------------------------------------------------------------------------
`transport.write() <WriteTransport.write>`{.interpreted-text role="meth"} Write data to the transport.
`transport.writelines() <WriteTransport.writelines>`{.interpreted-text role="meth"} Write buffers to the transport.
`transport.can_write_eof() <WriteTransport.can_write_eof>`{.interpreted-text role="meth"} Return `True`{.interpreted-text role="const"} if the transport supports sending EOF.
`transport.write_eof() <WriteTransport.write_eof>`{.interpreted-text role="meth"} Close and send EOF after flushing buffered data.
`transport.abort() <WriteTransport.abort>`{.interpreted-text role="meth"} Close the transport immediately.
`transport.get_write_buffer_size() Return the current size of the output buffer.
<WriteTransport.get_write_buffer_size>`{.interpreted-text role="meth"}
`transport.get_write_buffer_limits() Return high and low water marks for write flow control.
<WriteTransport.get_write_buffer_limits>`{.interpreted-text role="meth"}
`transport.set_write_buffer_limits() Set new high and low water marks for write flow control.
<WriteTransport.set_write_buffer_limits>`{.interpreted-text role="meth"}
------------------------------------------------------------------------------------------- --------------------------------------------------------------------------------------
Transports returned by `loop.create_datagram_endpoint`{.interpreted-text role="meth"}:
**Datagram Transports**
-------------------------------------------------------------------------------- -----------------------------------
`transport.sendto() <DatagramTransport.sendto>`{.interpreted-text role="meth"} Send data to the remote peer.
`transport.abort() <DatagramTransport.abort>`{.interpreted-text role="meth"} Close the transport immediately.
-------------------------------------------------------------------------------- -----------------------------------
Low-level transport abstraction over subprocesses. Returned by `loop.subprocess_exec`{.interpreted-text role="meth"} and `loop.subprocess_shell`{.interpreted-text role="meth"}:
**Subprocess Transports**
-------------------------------------------------------------------------------------------------- ---------------------------------------------------------------------------------------------
`transport.get_pid() <SubprocessTransport.get_pid>`{.interpreted-text role="meth"} Return the subprocess process id.
`transport.get_pipe_transport() Return the transport for the requested communication pipe (*stdin*, *stdout*, or *stderr*).
<SubprocessTransport.get_pipe_transport>`{.interpreted-text role="meth"}
`transport.get_returncode() <SubprocessTransport.get_returncode>`{.interpreted-text role="meth"} Return the subprocess return code.
`transport.kill() <SubprocessTransport.kill>`{.interpreted-text role="meth"} Kill the subprocess.
`transport.send_signal() <SubprocessTransport.send_signal>`{.interpreted-text role="meth"} Send a signal to the subprocess.
`transport.terminate() <SubprocessTransport.terminate>`{.interpreted-text role="meth"} Stop the subprocess.
`transport.close() <SubprocessTransport.close>`{.interpreted-text role="meth"} Kill the subprocess and close all pipes.
-------------------------------------------------------------------------------------------------- ---------------------------------------------------------------------------------------------
## Protocols
Protocol classes can implement the following **callback methods**:
---------------------------------------------------------------------------------------------- ----------------------------------------------------------------------
`callback` `connection_made() <BaseProtocol.connection_made>`{.interpreted-text role="meth"} Called when a connection is made.
`callback` `connection_lost() <BaseProtocol.connection_lost>`{.interpreted-text role="meth"} Called when the connection is lost or closed.
`callback` `pause_writing() <BaseProtocol.pause_writing>`{.interpreted-text role="meth"} Called when the transport\'s buffer goes over the high water mark.
`callback` `resume_writing() <BaseProtocol.resume_writing>`{.interpreted-text role="meth"} Called when the transport\'s buffer drains below the low water mark.
---------------------------------------------------------------------------------------------- ----------------------------------------------------------------------
**Streaming Protocols (TCP, Unix Sockets, Pipes)**
-------------------------------------------------------------------------------------- ------------------------------------
`callback` `data_received() <Protocol.data_received>`{.interpreted-text role="meth"} Called when some data is received.
`callback` `eof_received() <Protocol.eof_received>`{.interpreted-text role="meth"} Called when an EOF is received.
-------------------------------------------------------------------------------------- ------------------------------------
**Buffered Streaming Protocols**
------------------------------------------------------------------------------------------------ ------------------------------------------------------------
`callback` `get_buffer() <BufferedProtocol.get_buffer>`{.interpreted-text role="meth"} Called to allocate a new receive buffer.
`callback` `buffer_updated() <BufferedProtocol.buffer_updated>`{.interpreted-text role="meth"} Called when the buffer was updated with the received data.
`callback` `eof_received() <BufferedProtocol.eof_received>`{.interpreted-text role="meth"} Called when an EOF is received.
------------------------------------------------------------------------------------------------ ------------------------------------------------------------
**Datagram Protocols**
------------------------------------------------------------------------------------------------ -------------------------------------------------------------------------------------------------------
`callback` `datagram_received() Called when a datagram is received.
<DatagramProtocol.datagram_received>`{.interpreted-text role="meth"}
`callback` `error_received() <DatagramProtocol.error_received>`{.interpreted-text role="meth"} Called when a previous send or receive operation raises an `OSError`{.interpreted-text role="class"}.
------------------------------------------------------------------------------------------------ -------------------------------------------------------------------------------------------------------
**Subprocess Protocols**
-------------------------------------------------------------------------------------- ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
`callback` `~SubprocessProtocol.pipe_data_received`{.interpreted-text role="meth"} Called when the child process writes data into its *stdout* or *stderr* pipe.
`callback` `~SubprocessProtocol.pipe_connection_lost`{.interpreted-text role="meth"} Called when one of the pipes communicating with the child process is closed.
`callback` `process_exited() Called when the child process has exited. It can be called before `~SubprocessProtocol.pipe_data_received`{.interpreted-text role="meth"} and `~SubprocessProtocol.pipe_connection_lost`{.interpreted-text role="meth"} methods.
<SubprocessProtocol.process_exited>`{.interpreted-text role="meth"}
-------------------------------------------------------------------------------------- ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
## Event Loop Policies
Policies is a low-level mechanism to alter the behavior of functions like `asyncio.get_event_loop`{.interpreted-text role="func"}. See also the main `policies section <asyncio-policies>`{.interpreted-text role="ref"} for more details.
**Accessing Policies**
---------------------------------------------------------------- -----------------------------------------
`asyncio.get_event_loop_policy`{.interpreted-text role="meth"} Return the current process-wide policy.
`asyncio.set_event_loop_policy`{.interpreted-text role="meth"} Set a new process-wide policy.
`AbstractEventLoopPolicy`{.interpreted-text role="class"} Base class for policy objects.
---------------------------------------------------------------- -----------------------------------------
|