asyncio API

The asyncio API provides a high-level QUIC API built on top of asyncio, Python’s standard asynchronous I/O framework.

aioquic comes with a selection of examples, including:

  • an HTTP/3 client

  • an HTTP/3 server

The examples can be browsed on GitHub:

https://github.com/aiortc/aioquic/tree/main/examples

Client

async with aioquic.asyncio.connect(host, port, *, configuration=None, create_protocol=<class 'aioquic.asyncio.protocol.QuicConnectionProtocol'>, session_ticket_handler=None, stream_handler=None, token_handler=None, wait_connected=True, local_port=0)

Connect to a QUIC server at the given host and port.

connect() returns an awaitable. Awaiting it yields a QuicConnectionProtocol which can be used to create streams.

connect() also accepts the following optional arguments: :rtype: AsyncGenerator[QuicConnectionProtocol, None]

  • configuration is a QuicConfiguration configuration object.

  • create_protocol allows customizing the Protocol that manages the connection. It should be a callable or class accepting the same arguments as QuicConnectionProtocol and returning an instance of QuicConnectionProtocol or a subclass.

  • session_ticket_handler is a callback which is invoked by the TLS engine when a new session ticket is received.

  • stream_handler is a callback which is invoked whenever a stream is created. It must accept two arguments: a asyncio.StreamReader and a asyncio.StreamWriter.

  • local_port is the UDP port number that this client wants to bind.

Server

await aioquic.asyncio.serve(host, port, *, configuration, create_protocol=<class 'aioquic.asyncio.protocol.QuicConnectionProtocol'>, session_ticket_fetcher=None, session_ticket_handler=None, retry=False, stream_handler=None)

Start a QUIC server at the given host and port.

serve() requires a QuicConfiguration containing TLS certificate and private key as the configuration argument.

serve() also accepts the following optional arguments: :rtype: QuicServer

  • create_protocol allows customizing the Protocol that manages the connection. It should be a callable or class accepting the same arguments as QuicConnectionProtocol and returning an instance of QuicConnectionProtocol or a subclass.

  • session_ticket_fetcher is a callback which is invoked by the TLS engine when a session ticket is presented by the peer. It should return the session ticket with the specified ID or None if it is not found.

  • session_ticket_handler is a callback which is invoked by the TLS engine when a new session ticket is issued. It should store the session ticket for future lookup.

  • retry specifies whether client addresses should be validated prior to the cryptographic handshake using a retry packet.

  • stream_handler is a callback which is invoked whenever a stream is created. It must accept two arguments: a asyncio.StreamReader and a asyncio.StreamWriter.

Common

class aioquic.asyncio.QuicConnectionProtocol(quic, stream_handler=None)
change_connection_id()

Change the connection ID used to communicate with the peer.

The previous connection ID will be retired.

Return type:

None

close()

Close the connection.

Return type:

None

connect(addr)

Initiate the TLS handshake.

This method can only be called for clients and a single time.

Return type:

None

await create_stream(is_unidirectional=False)

Create a QUIC stream and return a pair of (reader, writer) objects.

The returned reader and writer objects are instances of asyncio.StreamReader and asyncio.StreamWriter classes.

Return type:

Tuple[StreamReader, StreamWriter]

await ping()

Ping the peer and wait for the response.

Return type:

None

quic_event_received(event)

Called when a QUIC event is received.

Reimplement this in your subclass to handle the events.

Return type:

None

request_key_update()

Request an update of the encryption keys.

Return type:

None

transmit()

Send pending datagrams to the peer and arm the timer if needed.

This method is called automatically when data is received from the peer or when a timer goes off. If you interact directly with the underlying QuicConnection, make sure you call this method whenever data needs to be sent out to the network.

Return type:

None

await wait_closed()

Wait for the connection to be closed.

Return type:

None

await wait_connected()

Wait for the TLS handshake to complete.

Return type:

None