Debian Codegraph @

Doc/library/asyncio-llapi-index.rst

raw
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 (running or current via the current 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:`asyncio-event-loop-methods`.
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/Interpreter/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_recvfrom`
193 - Receive a datagram from the :class:`~socket.socket`.
194
195 * - ``await`` :meth:`loop.sock_recvfrom_into`
196 - Receive a datagram from the :class:`~socket.socket` into a buffer.
197
198 * - ``await`` :meth:`loop.sock_sendall`
199 - Send data to the :class:`~socket.socket`.
200
201 * - ``await`` :meth:`loop.sock_sendto`
202 - Send a datagram via the :class:`~socket.socket` to the given address.
203
204 * - ``await`` :meth:`loop.sock_connect`
205 - Connect the :class:`~socket.socket`.
206
207 * - ``await`` :meth:`loop.sock_accept`
208 - Accept a :class:`~socket.socket` connection.
209
210 * - ``await`` :meth:`loop.sock_sendfile`
211 - Send a file over the :class:`~socket.socket`.
212
213 * - :meth:`loop.add_reader`
214 - Start watching a file descriptor for read availability.
215
216 * - :meth:`loop.remove_reader`
217 - Stop watching a file descriptor for read availability.
218
219 * - :meth:`loop.add_writer`
220 - Start watching a file descriptor for write availability.
221
222 * - :meth:`loop.remove_writer`
223 - Stop watching a file descriptor for write availability.
224
225
226 .. rubric:: Unix Signals
227 .. list-table::
228 :widths: 50 50
229 :class: full-width-table
230
231 * - :meth:`loop.add_signal_handler`
232 - Add a handler for a :mod:`signal`.
233
234 * - :meth:`loop.remove_signal_handler`
235 - Remove a handler for a :mod:`signal`.
236
237
238 .. rubric:: Subprocesses
239 .. list-table::
240 :widths: 50 50
241 :class: full-width-table
242
243 * - :meth:`loop.subprocess_exec`
244 - Spawn a subprocess.
245
246 * - :meth:`loop.subprocess_shell`
247 - Spawn a subprocess from a shell command.
248
249
250 .. rubric:: Error Handling
251 .. list-table::
252 :widths: 50 50
253 :class: full-width-table
254
255 * - :meth:`loop.call_exception_handler`
256 - Call the exception handler.
257
258 * - :meth:`loop.set_exception_handler`
259 - Set a new exception handler.
260
261 * - :meth:`loop.get_exception_handler`
262 - Get the current exception handler.
263
264 * - :meth:`loop.default_exception_handler`
265 - The default exception handler implementation.
266
267
268 .. rubric:: Examples
269
270 * :ref:`Using asyncio.new_event_loop() and loop.run_forever()
271 <asyncio_example_lowlevel_helloworld>`.
272
273 * :ref:`Using loop.call_later() <asyncio_example_call_later>`.
274
275 * Using ``loop.create_connection()`` to implement
276 :ref:`an echo-client <asyncio_example_tcp_echo_client_protocol>`.
277
278 * Using ``loop.create_connection()`` to
279 :ref:`connect a socket <asyncio_example_create_connection>`.
280
281 * :ref:`Using add_reader() to watch an FD for read events
282 <asyncio_example_watch_fd>`.
283
284 * :ref:`Using loop.add_signal_handler() <asyncio_example_unix_signals>`.
285
286 * :ref:`Using loop.subprocess_exec() <asyncio_example_subprocess_proto>`.
287
288
289 Transports
290 ==========
291
292 All transports implement the following methods:
293
294 .. list-table::
295 :widths: 50 50
296 :class: full-width-table
297
298 * - :meth:`transport.close() <BaseTransport.close>`
299 - Close the transport.
300
301 * - :meth:`transport.is_closing() <BaseTransport.is_closing>`
302 - Return ``True`` if the transport is closing or is closed.
303
304 * - :meth:`transport.get_extra_info() <BaseTransport.get_extra_info>`
305 - Request for information about the transport.
306
307 * - :meth:`transport.set_protocol() <BaseTransport.set_protocol>`
308 - Set a new protocol.
309
310 * - :meth:`transport.get_protocol() <BaseTransport.get_protocol>`
311 - Return the current protocol.
312
313
314 Transports that can receive data (TCP and Unix connections,
315 pipes, etc). Returned from methods like
316 :meth:`loop.create_connection`, :meth:`loop.create_unix_connection`,
317 :meth:`loop.connect_read_pipe`, etc:
318
319 .. rubric:: Read Transports
320 .. list-table::
321 :widths: 50 50
322 :class: full-width-table
323
324 * - :meth:`transport.is_reading() <ReadTransport.is_reading>`
325 - Return ``True`` if the transport is receiving.
326
327 * - :meth:`transport.pause_reading() <ReadTransport.pause_reading>`
328 - Pause receiving.
329
330 * - :meth:`transport.resume_reading() <ReadTransport.resume_reading>`
331 - Resume receiving.
332
333
334 Transports that can Send data (TCP and Unix connections,
335 pipes, etc). Returned from methods like
336 :meth:`loop.create_connection`, :meth:`loop.create_unix_connection`,
337 :meth:`loop.connect_write_pipe`, etc:
338
339 .. rubric:: Write Transports
340 .. list-table::
341 :widths: 50 50
342 :class: full-width-table
343
344 * - :meth:`transport.write() <WriteTransport.write>`
345 - Write data to the transport.
346
347 * - :meth:`transport.writelines() <WriteTransport.writelines>`
348 - Write buffers to the transport.
349
350 * - :meth:`transport.can_write_eof() <WriteTransport.can_write_eof>`
351 - Return :const:`True` if the transport supports sending EOF.
352
353 * - :meth:`transport.write_eof() <WriteTransport.write_eof>`
354 - Close and send EOF after flushing buffered data.
355
356 * - :meth:`transport.abort() <WriteTransport.abort>`
357 - Close the transport immediately.
358
359 * - :meth:`transport.get_write_buffer_size()
360 <WriteTransport.get_write_buffer_size>`
361 - Return the current size of the output buffer.
362
363 * - :meth:`transport.get_write_buffer_limits()
364 <WriteTransport.get_write_buffer_limits>`
365 - Return high and low water marks for write flow control.
366
367 * - :meth:`transport.set_write_buffer_limits()
368 <WriteTransport.set_write_buffer_limits>`
369 - Set new high and low water marks for write flow control.
370
371
372 Transports returned by :meth:`loop.create_datagram_endpoint`:
373
374 .. rubric:: Datagram Transports
375 .. list-table::
376 :widths: 50 50
377 :class: full-width-table
378
379 * - :meth:`transport.sendto() <DatagramTransport.sendto>`
380 - Send data to the remote peer.
381
382 * - :meth:`transport.abort() <DatagramTransport.abort>`
383 - Close the transport immediately.
384
385
386 Low-level transport abstraction over subprocesses.
387 Returned by :meth:`loop.subprocess_exec` and
388 :meth:`loop.subprocess_shell`:
389
390 .. rubric:: Subprocess Transports
391 .. list-table::
392 :widths: 50 50
393 :class: full-width-table
394
395 * - :meth:`transport.get_pid() <SubprocessTransport.get_pid>`
396 - Return the subprocess process id.
397
398 * - :meth:`transport.get_pipe_transport()
399 <SubprocessTransport.get_pipe_transport>`
400 - Return the transport for the requested communication pipe
401 (*stdin*, *stdout*, or *stderr*).
402
403 * - :meth:`transport.get_returncode() <SubprocessTransport.get_returncode>`
404 - Return the subprocess return code.
405
406 * - :meth:`transport.kill() <SubprocessTransport.kill>`
407 - Kill the subprocess.
408
409 * - :meth:`transport.send_signal() <SubprocessTransport.send_signal>`
410 - Send a signal to the subprocess.
411
412 * - :meth:`transport.terminate() <SubprocessTransport.terminate>`
413 - Stop the subprocess.
414
415 * - :meth:`transport.close() <SubprocessTransport.close>`
416 - Kill the subprocess and close all pipes.
417
418
419 Protocols
420 =========
421
422 Protocol classes can implement the following **callback methods**:
423
424 .. list-table::
425 :widths: 50 50
426 :class: full-width-table
427
428 * - ``callback`` :meth:`connection_made() <BaseProtocol.connection_made>`
429 - Called when a connection is made.
430
431 * - ``callback`` :meth:`connection_lost() <BaseProtocol.connection_lost>`
432 - Called when the connection is lost or closed.
433
434 * - ``callback`` :meth:`pause_writing() <BaseProtocol.pause_writing>`
435 - Called when the transport's buffer goes over the high water mark.
436
437 * - ``callback`` :meth:`resume_writing() <BaseProtocol.resume_writing>`
438 - Called when the transport's buffer drains below the low water mark.
439
440
441 .. rubric:: Streaming Protocols (TCP, Unix Sockets, Pipes)
442 .. list-table::
443 :widths: 50 50
444 :class: full-width-table
445
446 * - ``callback`` :meth:`data_received() <Protocol.data_received>`
447 - Called when some data is received.
448
449 * - ``callback`` :meth:`eof_received() <Protocol.eof_received>`
450 - Called when an EOF is received.
451
452
453 .. rubric:: Buffered Streaming Protocols
454 .. list-table::
455 :widths: 50 50
456 :class: full-width-table
457
458 * - ``callback`` :meth:`get_buffer() <BufferedProtocol.get_buffer>`
459 - Called to allocate a new receive buffer.
460
461 * - ``callback`` :meth:`buffer_updated() <BufferedProtocol.buffer_updated>`
462 - Called when the buffer was updated with the received data.
463
464 * - ``callback`` :meth:`eof_received() <BufferedProtocol.eof_received>`
465 - Called when an EOF is received.
466
467
468 .. rubric:: Datagram Protocols
469 .. list-table::
470 :widths: 50 50
471 :class: full-width-table
472
473 * - ``callback`` :meth:`datagram_received()
474 <DatagramProtocol.datagram_received>`
475 - Called when a datagram is received.
476
477 * - ``callback`` :meth:`error_received() <DatagramProtocol.error_received>`
478 - Called when a previous send or receive operation raises an
479 :class:`OSError`.
480
481
482 .. rubric:: Subprocess Protocols
483 .. list-table::
484 :widths: 50 50
485 :class: full-width-table
486
487 * - ``callback`` :meth:`~SubprocessProtocol.pipe_data_received`
488 - Called when the child process writes data into its
489 *stdout* or *stderr* pipe.
490
491 * - ``callback`` :meth:`~SubprocessProtocol.pipe_connection_lost`
492 - Called when one of the pipes communicating with
493 the child process is closed.
494
495 * - ``callback`` :meth:`process_exited()
496 <SubprocessProtocol.process_exited>`
497 - Called when the child process has exited. It can be called before
498 :meth:`~SubprocessProtocol.pipe_data_received` and
499 :meth:`~SubprocessProtocol.pipe_connection_lost` methods.
500
501
502 Event Loop Policies
503 ===================
504
505 Policies is a low-level mechanism to alter the behavior of
506 functions like :func:`asyncio.get_event_loop`. See also
507 the main :ref:`policies section <asyncio-policies>` for more
508 details.
509
510
511 .. rubric:: Accessing Policies
512 .. list-table::
513 :widths: 50 50
514 :class: full-width-table
515
516 * - :meth:`asyncio.get_event_loop_policy`
517 - Return the current process-wide policy.
518
519 * - :meth:`asyncio.set_event_loop_policy`
520 - Set a new process-wide policy.
521
522 * - :class:`AbstractEventLoopPolicy`
523 - Base class for policy objects.