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.

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: Optional[int] = 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: Optional[int] = 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.