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

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/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

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.