.. currentmodule:: asyncio =================== Low-level API Index =================== This page lists all low-level asyncio APIs. Obtaining the Event Loop ======================== .. list-table:: :widths: 50 50 :class: full-width-table * - :func:`asyncio.get_running_loop` - The **preferred** function to get the running event loop. * - :func:`asyncio.get_event_loop` - Get an event loop instance (running or current via the current policy). * - :func:`asyncio.set_event_loop` - Set the event loop as current via the current policy. * - :func:`asyncio.new_event_loop` - Create a new event loop. .. rubric:: Examples * :ref:`Using asyncio.get_running_loop() `. Event Loop Methods ================== See also the main documentation section about the :ref:`asyncio-event-loop-methods`. .. rubric:: Lifecycle .. list-table:: :widths: 50 50 :class: full-width-table * - :meth:`loop.run_until_complete` - Run a Future/Task/awaitable until complete. * - :meth:`loop.run_forever` - Run the event loop forever. * - :meth:`loop.stop` - Stop the event loop. * - :meth:`loop.close` - Close the event loop. * - :meth:`loop.is_running` - Return ``True`` if the event loop is running. * - :meth:`loop.is_closed` - Return ``True`` if the event loop is closed. * - ``await`` :meth:`loop.shutdown_asyncgens` - Close asynchronous generators. .. rubric:: Debugging .. list-table:: :widths: 50 50 :class: full-width-table * - :meth:`loop.set_debug` - Enable or disable the debug mode. * - :meth:`loop.get_debug` - Get the current debug mode. .. rubric:: Scheduling Callbacks .. list-table:: :widths: 50 50 :class: full-width-table * - :meth:`loop.call_soon` - Invoke a callback soon. * - :meth:`loop.call_soon_threadsafe` - A thread-safe variant of :meth:`loop.call_soon`. * - :meth:`loop.call_later` - Invoke a callback *after* the given time. * - :meth:`loop.call_at` - Invoke a callback *at* the given time. .. rubric:: Thread/Process Pool .. list-table:: :widths: 50 50 :class: full-width-table * - ``await`` :meth:`loop.run_in_executor` - Run a CPU-bound or other blocking function in a :mod:`concurrent.futures` executor. * - :meth:`loop.set_default_executor` - Set the default executor for :meth:`loop.run_in_executor`. .. rubric:: Tasks and Futures .. list-table:: :widths: 50 50 :class: full-width-table * - :meth:`loop.create_future` - Create a :class:`Future` object. * - :meth:`loop.create_task` - Schedule coroutine as a :class:`Task`. * - :meth:`loop.set_task_factory` - Set a factory used by :meth:`loop.create_task` to create :class:`Tasks `. * - :meth:`loop.get_task_factory` - Get the factory :meth:`loop.create_task` uses to create :class:`Tasks `. .. rubric:: DNS .. list-table:: :widths: 50 50 :class: full-width-table * - ``await`` :meth:`loop.getaddrinfo` - Asynchronous version of :meth:`socket.getaddrinfo`. * - ``await`` :meth:`loop.getnameinfo` - Asynchronous version of :meth:`socket.getnameinfo`. .. rubric:: Networking and IPC .. list-table:: :widths: 50 50 :class: full-width-table * - ``await`` :meth:`loop.create_connection` - Open a TCP connection. * - ``await`` :meth:`loop.create_server` - Create a TCP server. * - ``await`` :meth:`loop.create_unix_connection` - Open a Unix socket connection. * - ``await`` :meth:`loop.create_unix_server` - Create a Unix socket server. * - ``await`` :meth:`loop.connect_accepted_socket` - Wrap a :class:`~socket.socket` into a ``(transport, protocol)`` pair. * - ``await`` :meth:`loop.create_datagram_endpoint` - Open a datagram (UDP) connection. * - ``await`` :meth:`loop.sendfile` - Send a file over a transport. * - ``await`` :meth:`loop.start_tls` - Upgrade an existing connection to TLS. * - ``await`` :meth:`loop.connect_read_pipe` - Wrap a read end of a pipe into a ``(transport, protocol)`` pair. * - ``await`` :meth:`loop.connect_write_pipe` - Wrap a write end of a pipe into a ``(transport, protocol)`` pair. .. rubric:: Sockets .. list-table:: :widths: 50 50 :class: full-width-table * - ``await`` :meth:`loop.sock_recv` - Receive data from the :class:`~socket.socket`. * - ``await`` :meth:`loop.sock_recv_into` - Receive data from the :class:`~socket.socket` into a buffer. * - ``await`` :meth:`loop.sock_recvfrom` - Receive a datagram from the :class:`~socket.socket`. * - ``await`` :meth:`loop.sock_recvfrom_into` - Receive a datagram from the :class:`~socket.socket` into a buffer. * - ``await`` :meth:`loop.sock_sendall` - Send data to the :class:`~socket.socket`. * - ``await`` :meth:`loop.sock_sendto` - Send a datagram via the :class:`~socket.socket` to the given address. * - ``await`` :meth:`loop.sock_connect` - Connect the :class:`~socket.socket`. * - ``await`` :meth:`loop.sock_accept` - Accept a :class:`~socket.socket` connection. * - ``await`` :meth:`loop.sock_sendfile` - Send a file over the :class:`~socket.socket`. * - :meth:`loop.add_reader` - Start watching a file descriptor for read availability. * - :meth:`loop.remove_reader` - Stop watching a file descriptor for read availability. * - :meth:`loop.add_writer` - Start watching a file descriptor for write availability. * - :meth:`loop.remove_writer` - Stop watching a file descriptor for write availability. .. rubric:: Unix Signals .. list-table:: :widths: 50 50 :class: full-width-table * - :meth:`loop.add_signal_handler` - Add a handler for a :mod:`signal`. * - :meth:`loop.remove_signal_handler` - Remove a handler for a :mod:`signal`. .. rubric:: Subprocesses .. list-table:: :widths: 50 50 :class: full-width-table * - :meth:`loop.subprocess_exec` - Spawn a subprocess. * - :meth:`loop.subprocess_shell` - Spawn a subprocess from a shell command. .. rubric:: Error Handling .. list-table:: :widths: 50 50 :class: full-width-table * - :meth:`loop.call_exception_handler` - Call the exception handler. * - :meth:`loop.set_exception_handler` - Set a new exception handler. * - :meth:`loop.get_exception_handler` - Get the current exception handler. * - :meth:`loop.default_exception_handler` - The default exception handler implementation. .. rubric:: Examples * :ref:`Using asyncio.new_event_loop() and loop.run_forever() `. * :ref:`Using loop.call_later() `. * Using ``loop.create_connection()`` to implement :ref:`an echo-client `. * Using ``loop.create_connection()`` to :ref:`connect a socket `. * :ref:`Using add_reader() to watch an FD for read events `. * :ref:`Using loop.add_signal_handler() `. * :ref:`Using loop.subprocess_exec() `. Transports ========== All transports implement the following methods: .. list-table:: :widths: 50 50 :class: full-width-table * - :meth:`transport.close() ` - Close the transport. * - :meth:`transport.is_closing() ` - Return ``True`` if the transport is closing or is closed. * - :meth:`transport.get_extra_info() ` - Request for information about the transport. * - :meth:`transport.set_protocol() ` - Set a new protocol. * - :meth:`transport.get_protocol() ` - Return the current protocol. Transports that can receive data (TCP and Unix connections, pipes, etc). Returned from methods like :meth:`loop.create_connection`, :meth:`loop.create_unix_connection`, :meth:`loop.connect_read_pipe`, etc: .. rubric:: Read Transports .. list-table:: :widths: 50 50 :class: full-width-table * - :meth:`transport.is_reading() ` - Return ``True`` if the transport is receiving. * - :meth:`transport.pause_reading() ` - Pause receiving. * - :meth:`transport.resume_reading() ` - Resume receiving. Transports that can Send data (TCP and Unix connections, pipes, etc). Returned from methods like :meth:`loop.create_connection`, :meth:`loop.create_unix_connection`, :meth:`loop.connect_write_pipe`, etc: .. rubric:: Write Transports .. list-table:: :widths: 50 50 :class: full-width-table * - :meth:`transport.write() ` - Write data to the transport. * - :meth:`transport.writelines() ` - Write buffers to the transport. * - :meth:`transport.can_write_eof() ` - Return :const:`True` if the transport supports sending EOF. * - :meth:`transport.write_eof() ` - Close and send EOF after flushing buffered data. * - :meth:`transport.abort() ` - Close the transport immediately. * - :meth:`transport.get_write_buffer_size() ` - Return the current size of the output buffer. * - :meth:`transport.get_write_buffer_limits() ` - Return high and low water marks for write flow control. * - :meth:`transport.set_write_buffer_limits() ` - Set new high and low water marks for write flow control. Transports returned by :meth:`loop.create_datagram_endpoint`: .. rubric:: Datagram Transports .. list-table:: :widths: 50 50 :class: full-width-table * - :meth:`transport.sendto() ` - Send data to the remote peer. * - :meth:`transport.abort() ` - Close the transport immediately. Low-level transport abstraction over subprocesses. Returned by :meth:`loop.subprocess_exec` and :meth:`loop.subprocess_shell`: .. rubric:: Subprocess Transports .. list-table:: :widths: 50 50 :class: full-width-table * - :meth:`transport.get_pid() ` - Return the subprocess process id. * - :meth:`transport.get_pipe_transport() ` - Return the transport for the requested communication pipe (*stdin*, *stdout*, or *stderr*). * - :meth:`transport.get_returncode() ` - Return the subprocess return code. * - :meth:`transport.kill() ` - Kill the subprocess. * - :meth:`transport.send_signal() ` - Send a signal to the subprocess. * - :meth:`transport.terminate() ` - Stop the subprocess. * - :meth:`transport.close() ` - Kill the subprocess and close all pipes. Protocols ========= Protocol classes can implement the following **callback methods**: .. list-table:: :widths: 50 50 :class: full-width-table * - ``callback`` :meth:`connection_made() ` - Called when a connection is made. * - ``callback`` :meth:`connection_lost() ` - Called when the connection is lost or closed. * - ``callback`` :meth:`pause_writing() ` - Called when the transport's buffer goes over the high water mark. * - ``callback`` :meth:`resume_writing() ` - Called when the transport's buffer drains below the low water mark. .. rubric:: Streaming Protocols (TCP, Unix Sockets, Pipes) .. list-table:: :widths: 50 50 :class: full-width-table * - ``callback`` :meth:`data_received() ` - Called when some data is received. * - ``callback`` :meth:`eof_received() ` - Called when an EOF is received. .. rubric:: Buffered Streaming Protocols .. list-table:: :widths: 50 50 :class: full-width-table * - ``callback`` :meth:`get_buffer() ` - Called to allocate a new receive buffer. * - ``callback`` :meth:`buffer_updated() ` - Called when the buffer was updated with the received data. * - ``callback`` :meth:`eof_received() ` - Called when an EOF is received. .. rubric:: Datagram Protocols .. list-table:: :widths: 50 50 :class: full-width-table * - ``callback`` :meth:`datagram_received() ` - Called when a datagram is received. * - ``callback`` :meth:`error_received() ` - Called when a previous send or receive operation raises an :class:`OSError`. .. rubric:: Subprocess Protocols .. list-table:: :widths: 50 50 :class: full-width-table * - ``callback`` :meth:`~SubprocessProtocol.pipe_data_received` - Called when the child process writes data into its *stdout* or *stderr* pipe. * - ``callback`` :meth:`~SubprocessProtocol.pipe_connection_lost` - Called when one of the pipes communicating with the child process is closed. * - ``callback`` :meth:`process_exited() ` - Called when the child process has exited. It can be called before :meth:`~SubprocessProtocol.pipe_data_received` and :meth:`~SubprocessProtocol.pipe_connection_lost` methods. Event Loop Policies =================== Policies is a low-level mechanism to alter the behavior of functions like :func:`asyncio.get_event_loop`. See also the main :ref:`policies section ` for more details. .. rubric:: Accessing Policies .. list-table:: :widths: 50 50 :class: full-width-table * - :meth:`asyncio.get_event_loop_policy` - Return the current process-wide policy. * - :meth:`asyncio.set_event_loop_policy` - Set a new process-wide policy. * - :class:`AbstractEventLoopPolicy` - Base class for policy objects.