asyncio-llapi-index.rst

.. currentmodule:: asyncio

Low-level API Index

This page lists all low-level asyncio APIs.

Obtaining the Event Loop

: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.

Examples

• :ref:`Using asyncio.get_running_loop() <asyncio_example_future>`.

Event Loop Methods

See also the main documentation section about the :ref:`asyncio-event-loop-methods`.

Lifecycle

: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.

Debugging

:meth:`loop.set_debug`	Enable or disable the debug mode.
:meth:`loop.get_debug`	Get the current debug mode.

Scheduling Callbacks

: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.

Thread/Interpreter/Process Pool

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`.

Tasks and Futures

: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 <Task>`.
:meth:`loop.get_task_factory`	Get the factory :meth:`loop.create_task` uses to create :class:`Tasks <Task>`.

DNS

await :meth:`loop.getaddrinfo`	Asynchronous version of :meth:`socket.getaddrinfo`.
await :meth:`loop.getnameinfo`	Asynchronous version of :meth:`socket.getnameinfo`.

Networking and IPC

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.

Sockets

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.

Unix Signals

:meth:`loop.add_signal_handler`	Add a handler for a :mod:`signal`.
:meth:`loop.remove_signal_handler`	Remove a handler for a :mod:`signal`.

Subprocesses

:meth:`loop.subprocess_exec`	Spawn a subprocess.
:meth:`loop.subprocess_shell`	Spawn a subprocess from a shell command.

Error Handling

: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.

Examples

• :ref:`Using asyncio.new_event_loop() and loop.run_forever() <asyncio_example_lowlevel_helloworld>`.
• :ref:`Using loop.call_later() <asyncio_example_call_later>`.
• Using loop.create_connection() to implement :ref:`an echo-client <asyncio_example_tcp_echo_client_protocol>`.
• Using loop.create_connection() to :ref:`connect a socket <asyncio_example_create_connection>`.
• :ref:`Using add_reader() to watch an FD for read events <asyncio_example_watch_fd>`.
• :ref:`Using loop.add_signal_handler() <asyncio_example_unix_signals>`.
• :ref:`Using loop.subprocess_exec() <asyncio_example_subprocess_proto>`.

Transports

All transports implement the following methods:

:meth:`transport.close() <BaseTransport.close>`	Close the transport.
:meth:`transport.is_closing() <BaseTransport.is_closing>`	Return True if the transport is closing or is closed.
:meth:`transport.get_extra_info() <BaseTransport.get_extra_info>`	Request for information about the transport.
:meth:`transport.set_protocol() <BaseTransport.set_protocol>`	Set a new protocol.
:meth:`transport.get_protocol() <BaseTransport.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:

Read Transports

:meth:`transport.is_reading() <ReadTransport.is_reading>`	Return True if the transport is receiving.
:meth:`transport.pause_reading() <ReadTransport.pause_reading>`	Pause receiving.
:meth:`transport.resume_reading() <ReadTransport.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:

Write Transports

:meth:`transport.write() <WriteTransport.write>`	Write data to the transport.
:meth:`transport.writelines() <WriteTransport.writelines>`	Write buffers to the transport.
:meth:`transport.can_write_eof() <WriteTransport.can_write_eof>`	Return :const:`True` if the transport supports sending EOF.
:meth:`transport.write_eof() <WriteTransport.write_eof>`	Close and send EOF after flushing buffered data.
:meth:`transport.abort() <WriteTransport.abort>`	Close the transport immediately.
:meth:`transport.get_write_buffer_size() <WriteTransport.get_write_buffer_size>`	Return the current size of the output buffer.
:meth:`transport.get_write_buffer_limits() <WriteTransport.get_write_buffer_limits>`	Return high and low water marks for write flow control.
:meth:`transport.set_write_buffer_limits() <WriteTransport.set_write_buffer_limits>`	Set new high and low water marks for write flow control.

Transports returned by :meth:`loop.create_datagram_endpoint`:

Datagram Transports

:meth:`transport.sendto() <DatagramTransport.sendto>`	Send data to the remote peer.
:meth:`transport.abort() <DatagramTransport.abort>`	Close the transport immediately.

Low-level transport abstraction over subprocesses. Returned by :meth:`loop.subprocess_exec` and :meth:`loop.subprocess_shell`:

Subprocess Transports

:meth:`transport.get_pid() <SubprocessTransport.get_pid>`	Return the subprocess process id.
:meth:`transport.get_pipe_transport() <SubprocessTransport.get_pipe_transport>`	Return the transport for the requested communication pipe (stdin, stdout, or stderr).
:meth:`transport.get_returncode() <SubprocessTransport.get_returncode>`	Return the subprocess return code.
:meth:`transport.kill() <SubprocessTransport.kill>`	Kill the subprocess.
:meth:`transport.send_signal() <SubprocessTransport.send_signal>`	Send a signal to the subprocess.
:meth:`transport.terminate() <SubprocessTransport.terminate>`	Stop the subprocess.
:meth:`transport.close() <SubprocessTransport.close>`	Kill the subprocess and close all pipes.

Protocols

Protocol classes can implement the following callback methods:

callback :meth:`connection_made() <BaseProtocol.connection_made>`	Called when a connection is made.
callback :meth:`connection_lost() <BaseProtocol.connection_lost>`	Called when the connection is lost or closed.
callback :meth:`pause_writing() <BaseProtocol.pause_writing>`	Called when the transport's buffer goes over the high water mark.
callback :meth:`resume_writing() <BaseProtocol.resume_writing>`	Called when the transport's buffer drains below the low water mark.

Streaming Protocols (TCP, Unix Sockets, Pipes)

callback :meth:`data_received() <Protocol.data_received>`	Called when some data is received.
callback :meth:`eof_received() <Protocol.eof_received>`	Called when an EOF is received.

Buffered Streaming Protocols

callback :meth:`get_buffer() <BufferedProtocol.get_buffer>`	Called to allocate a new receive buffer.
callback :meth:`buffer_updated() <BufferedProtocol.buffer_updated>`	Called when the buffer was updated with the received data.
callback :meth:`eof_received() <BufferedProtocol.eof_received>`	Called when an EOF is received.

Datagram Protocols

callback :meth:`datagram_received() <DatagramProtocol.datagram_received>`	Called when a datagram is received.
callback :meth:`error_received() <DatagramProtocol.error_received>`	Called when a previous send or receive operation raises an :class:`OSError`.

Subprocess Protocols

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() <SubprocessProtocol.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 <asyncio-policies>` for more details.

Accessing Policies

: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.