• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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 (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
36Event Loop Methods
37==================
38
39See 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
280Transports
281==========
282
283All 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
305Transports that can receive data (TCP and Unix connections,
306pipes, 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
325Transports that can Send data (TCP and Unix connections,
326pipes, 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
359Transports 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
373Low-level transport abstraction over subprocesses.
374Returned 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
406Protocols
407=========
408
409Protocol 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
489Event Loop Policies
490===================
491
492Policies is a low-level mechanism to alter the behavior of
493functions like :func:`asyncio.get_event_loop`.  See also
494the main :ref:`policies section <asyncio-policies>` for more
495details.
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