Low-level API Index

This page lists all low-level asyncio APIs.

Obtaining the Event Loop

asyncio.get_running_loop()	The preferred function to get the running event loop.
asyncio.get_event_loop()	Get an event loop instance (running or current via the current policy).
asyncio.set_event_loop()	Set the event loop as current via the current policy.
asyncio.new_event_loop()	Create a new event loop.

Examples

• Using asyncio.get_running_loop().

Event Loop Methods

See also the main documentation section about the Event Loop Methods.

Lifecycle

loop.run_until_complete()	Run a Future/Task/awaitable until complete.
loop.run_forever()	Run the event loop forever.
loop.stop()	Stop the event loop.
loop.close()	Close the event loop.
loop.is_running()	Return True if the event loop is running.
loop.is_closed()	Return True if the event loop is closed.
await loop.shutdown_asyncgens()	Close asynchronous generators.

Debugging

loop.set_debug()	Enable or disable the debug mode.
loop.get_debug()	Get the current debug mode.

Scheduling Callbacks

loop.call_soon()	Invoke a callback soon.
loop.call_soon_threadsafe()	A thread-safe variant of loop.call_soon().
loop.call_later()	Invoke a callback after the given time.
loop.call_at()	Invoke a callback at the given time.

Thread/Interpreter/Process Pool

await loop.run_in_executor()	Run a CPU-bound or other blocking function in a concurrent.futures executor.
loop.set_default_executor()	Set the default executor for loop.run_in_executor().

Tasks and Futures

loop.create_future()	Create a Future object.
loop.create_task()	Schedule coroutine as a Task.
loop.set_task_factory()	Set a factory used by loop.create_task() to create Tasks.
loop.get_task_factory()	Get the factory loop.create_task() uses to create Tasks.

DNS

await loop.getaddrinfo()	Asynchronous version of socket.getaddrinfo().
await loop.getnameinfo()	Asynchronous version of socket.getnameinfo().

Networking and IPC

await loop.create_connection()	Open a TCP connection.
await loop.create_server()	Create a TCP server.
await loop.create_unix_connection()	Open a Unix socket connection.
await loop.create_unix_server()	Create a Unix socket server.
await loop.connect_accepted_socket()	Wrap a socket into a (transport, protocol) pair.
await loop.create_datagram_endpoint()	Open a datagram (UDP) connection.
await loop.sendfile()	Send a file over a transport.
await loop.start_tls()	Upgrade an existing connection to TLS.
await loop.connect_read_pipe()	Wrap a read end of a pipe into a (transport, protocol) pair.
await loop.connect_write_pipe()	Wrap a write end of a pipe into a (transport, protocol) pair.

Sockets

await loop.sock_recv()	Receive data from the socket.
await loop.sock_recv_into()	Receive data from the socket into a buffer.
await loop.sock_recvfrom()	Receive a datagram from the socket.
await loop.sock_recvfrom_into()	Receive a datagram from the socket into a buffer.
await loop.sock_sendall()	Send data to the socket.
await loop.sock_sendto()	Send a datagram via the socket to the given address.
await loop.sock_connect()	Connect the socket.
await loop.sock_accept()	Accept a socket connection.
await loop.sock_sendfile()	Send a file over the socket.
loop.add_reader()	Start watching a file descriptor for read availability.
loop.remove_reader()	Stop watching a file descriptor for read availability.
loop.add_writer()	Start watching a file descriptor for write availability.
loop.remove_writer()	Stop watching a file descriptor for write availability.

Unix Signals

loop.add_signal_handler()	Add a handler for a signal.
loop.remove_signal_handler()	Remove a handler for a signal.

Subprocesses

loop.subprocess_exec()	Spawn a subprocess.
loop.subprocess_shell()	Spawn a subprocess from a shell command.

Error Handling

loop.call_exception_handler()	Call the exception handler.
loop.set_exception_handler()	Set a new exception handler.
loop.get_exception_handler()	Get the current exception handler.
loop.default_exception_handler()	The default exception handler implementation.

Examples

• Using asyncio.new_event_loop() and loop.run_forever().

• Using loop.call_later().

• Using loop.create_connection() to implement an echo-client.

• Using loop.create_connection() to connect a socket.

• Using add_reader() to watch an FD for read events.

• Using loop.add_signal_handler().

• Using loop.subprocess_exec().

Transports

All transports implement the following methods:

transport.close()	Close the transport.
transport.is_closing()	Return True if the transport is closing or is closed.
transport.get_extra_info()	Request for information about the transport.
transport.set_protocol()	Set a new protocol.
transport.get_protocol()	Return the current protocol.

Transports that can receive data (TCP and Unix connections, pipes, etc). Returned from methods like loop.create_connection(), loop.create_unix_connection(), loop.connect_read_pipe(), etc:

Read Transports

transport.is_reading()	Return True if the transport is receiving.
transport.pause_reading()	Pause receiving.
transport.resume_reading()	Resume receiving.

Transports that can Send data (TCP and Unix connections, pipes, etc). Returned from methods like loop.create_connection(), loop.create_unix_connection(), loop.connect_write_pipe(), etc:

Write Transports

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

Transports returned by loop.create_datagram_endpoint():

Datagram Transports

transport.sendto()	Send data to the remote peer.
transport.abort()	Close the transport immediately.

Low-level transport abstraction over subprocesses. Returned by loop.subprocess_exec() and loop.subprocess_shell():

Subprocess Transports

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

Protocols

Protocol classes can implement the following callback methods:

callback connection_made()	Called when a connection is made.
callback connection_lost()	Called when the connection is lost or closed.
callback pause_writing()	Called when the transport’s buffer goes over the high water mark.
callback resume_writing()	Called when the transport’s buffer drains below the low water mark.

Streaming Protocols (TCP, Unix Sockets, Pipes)

callback data_received()	Called when some data is received.
callback eof_received()	Called when an EOF is received.

Buffered Streaming Protocols

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

Datagram Protocols

callback datagram_received()	Called when a datagram is received.
callback error_received()	Called when a previous send or receive operation raises an OSError.

Subprocess Protocols

callback pipe_data_received()	Called when the child process writes data into its stdout or stderr pipe.
callback pipe_connection_lost()	Called when one of the pipes communicating with the child process is closed.
callback process_exited()	Called when the child process has exited. It can be called before pipe_data_received() and pipe_connection_lost() methods.

Event Loop Policies

Policies is a low-level mechanism to alter the behavior of functions like asyncio.get_event_loop(). See also the main policies section for more details.

Accessing Policies

asyncio.get_event_loop_policy()	Return the current process-wide policy.
asyncio.set_event_loop_policy()	Set a new process-wide policy.
AbstractEventLoopPolicy	Base class for policy objects.