1.. currentmodule:: asyncio
2
3
4===================
5Low-level API Index
6===================
7
8This page lists all low-level asyncio APIs.
9
10
11Obtaining 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
36Event Loop Methods
37==================
38
39See 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/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
289Transports
290==========
291
292All 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
314Transports that can receive data (TCP and Unix connections,
315pipes, 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
334Transports that can Send data (TCP and Unix connections,
335pipes, 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
372Transports 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
386Low-level transport abstraction over subprocesses.
387Returned 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
419Protocols
420=========
421
422Protocol 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:`pipe_data_received()
488        <SubprocessProtocol.pipe_data_received>`
489      - Called when the child process writes data into its
490        *stdout* or *stderr* pipe.
491
492    * - ``callback`` :meth:`pipe_connection_lost()
493        <SubprocessProtocol.pipe_connection_lost>`
494      - Called when one of the pipes communicating with
495        the child process is closed.
496
497    * - ``callback`` :meth:`process_exited()
498        <SubprocessProtocol.process_exited>`
499      - Called when the child process has exited.
500
501
502Event Loop Policies
503===================
504
505Policies is a low-level mechanism to alter the behavior of
506functions like :func:`asyncio.get_event_loop`.  See also
507the main :ref:`policies section <asyncio-policies>` for more
508details.
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.
524