HTTP/3 API

The HTTP/3 API performs no I/O on its own, leaving this to the API user. This allows you to integrate HTTP/3 in any Python application, regardless of the concurrency model you are using.

Connection

class aioquic.h3.connection.H3Connection(quic, enable_webtransport=False)

A low-level HTTP/3 connection object.

Parameters:

quic (QuicConnection) – A QuicConnection instance.

create_webtransport_stream(session_id, is_unidirectional=False)

Create a WebTransport stream and return the stream ID.

Note

After calling this method you need to call the QUIC connection datagrams_to_send() method to retrieve data which needs to be sent over the network. If you are using the asyncio API, calling the transmit() method will do it for you.

Parameters:

• session_id (int) – The WebTransport session identifier.

• is_unidirectional (bool) – Whether to create a unidirectional stream.

Return type:

int

handle_event(event)

Handle a QUIC event and return a list of HTTP events.

Parameters:

event (QuicEvent) – The QUIC event to handle.

Return type:

list[H3Event]

property received_settings: dict[int, int] | None

Return the received SETTINGS frame, or None.

send_data(stream_id, data, end_stream)

Send data on the given stream.

Note

After calling this method you need to call the QUIC connection datagrams_to_send() method to retrieve data which needs to be sent over the network. If you are using the asyncio API, calling the transmit() method will do it for you.

Parameters:

• stream_id (int) – The stream ID on which to send the data.

• data (bytes) – The data to send.

• end_stream (bool) – Whether to end the stream.

Return type:

None

send_datagram(stream_id, data)

Send a datagram for the specified stream.

If the stream ID is not a client-initiated bidirectional stream, an InvalidStreamTypeError exception is raised.

Note

After calling this method you need to call the QUIC connection datagrams_to_send() method to retrieve data which needs to be sent over the network. If you are using the asyncio API, calling the transmit() method will do it for you.

Parameters:

• stream_id (int) – The stream ID.

• data (bytes) – The HTTP/3 datagram payload.

Return type:

None

send_headers(stream_id, headers, end_stream=False)

Send headers on the given stream.

Note

After calling this method you need to call the QUIC connection datagrams_to_send() method to retrieve data which needs to be sent over the network. If you are using the asyncio API, calling the transmit() method will do it for you.

Parameters:

• stream_id (int) – The stream ID on which to send the headers.

• headers (list[tuple[bytes, bytes]]) – The HTTP headers to send.

• end_stream (bool) – Whether to end the stream.

Return type:

None

send_push_promise(stream_id, headers)

Send a push promise related to the specified stream.

Returns the stream ID on which headers and data can be sent.

If the stream ID is not a client-initiated bidirectional stream, an InvalidStreamTypeError exception is raised.

If there are not available push IDs, an NoAvailablePushIDError exception is raised.

If called by a client, a RuntimeError exception is raised.

Note

After calling this method you need to call the QUIC connection datagrams_to_send() method to retrieve data which needs to be sent over the network. If you are using the asyncio API, calling the transmit() method will do it for you.

Parameters:

• stream_id (int) – The stream ID on which to send the data.

• headers (list[tuple[bytes, bytes]]) – The HTTP request headers for this push.

Return type:

int

property sent_settings: dict[int, int] | None

Return the sent SETTINGS frame, or None.

Events

class aioquic.h3.events.H3Event

Base class for HTTP/3 events.

class aioquic.h3.events.DatagramReceived(data, stream_id)

The DatagramReceived is fired whenever a datagram is received from the the remote peer.

data: bytes

The data which was received.

stream_id: int

The ID of the stream the data was received for.

class aioquic.h3.events.DataReceived(data, stream_id, stream_ended, push_id=None)

The DataReceived event is fired whenever data is received on a stream from the remote peer.

data: bytes

The data which was received.

push_id: int | None = None

The Push ID or None if this is not a push.

stream_ended: bool

Whether the STREAM frame had the FIN bit set.

stream_id: int

The ID of the stream the data was received for.

class aioquic.h3.events.HeadersReceived(headers, stream_id, stream_ended, push_id=None)

The HeadersReceived event is fired whenever headers are received.

headers: list[tuple[bytes, bytes]]

The headers.

push_id: int | None = None

The Push ID or None if this is not a push.

stream_ended: bool

Whether the STREAM frame had the FIN bit set.

stream_id: int

The ID of the stream the headers were received for.

class aioquic.h3.events.PushPromiseReceived(headers, push_id, stream_id)

The PushedStreamReceived event is fired whenever a pushed stream has been received from the remote peer.

headers: list[tuple[bytes, bytes]]

The request headers.

push_id: int

The Push ID of the push promise.

stream_id: int

The Stream ID of the stream that the push is related to.

class aioquic.h3.events.WebTransportStreamDataReceived(data, stream_id, stream_ended, session_id)

The WebTransportStreamDataReceived is fired whenever data is received for a WebTransport stream.

data: bytes

The data which was received.

session_id: int

The ID of the session the data was received for.

stream_ended: bool

Whether the STREAM frame had the FIN bit set.

stream_id: int

The ID of the stream the data was received for.

Exceptions

class aioquic.h3.exceptions.H3Error

Base class for HTTP/3 exceptions.

class aioquic.h3.exceptions.InvalidStreamTypeError

An action was attempted on an invalid stream type.

class aioquic.h3.exceptions.NoAvailablePushIDError

There are no available push IDs left, or push is not supported by the remote party.