AIOQUIC(1)

📦
version 1.3.0 · 2 versions
, in fedora 44

🎀 AIOQUIC(1) 🎀

Okay bestie, this is the page for aioquic 💖, a library for the QUIC network protocol in Python and it is ✨ so good ✨.

✨ NAME ✨

aioquic - aioquic 🦋 The badges are lowkey iconic, and each one has an unlabelled image beside it:

So, aioquic is a library for the QUIC network protocol in Python 🌸, and it comes with several APIs:

  • a QUIC API following the "bring your own I/O" pattern, suitable for embedding in any framework, 💅
  • an HTTP/3 API which also follows the "bring your own I/O" pattern, 🧚
  • a QUIC convenience API built on top of asyncio (https://docs.python.org/3/library/asyncio.html#module-asyncio), Python's standard asynchronous I/O framework. 👑

💖 DESIGN 💖

Sans-IO APIs

Both the QUIC and the HTTP/3 APIs follow the sans I/O pattern (https://sans-io.readthedocs.io/) 🫶, which means they leave the actual I/O operations to the API user. This approach has a number of advantages, including making the code testable and allowing integration with different concurrency models. It's giving clean architecture, no cap ✨.

TLS and encryption

TLS 1.3

aioquic features a minimal TLS 1.3 implementation built upon the cryptography library (https://cryptography.io/) 🔐. Why not just use the normal stuff? Because QUIC needs some APIs that are currently unavailable in mainstream TLS implementations such as OpenSSL 🙈:

  • the ability to extract traffic secrets
  • the ability to operate directly on TLS messages, without using the TLS record layer

Header protection and payload encryption

QUIC makes extensive use of cryptographic operations to protect QUIC packet headers and encrypt packet payloads 🔥. These operations happen for every single packet, and they are a determining factor for performance. That's why they are implemented as a C extension linked to OpenSSL (https://www.openssl.org/). Main character energy for performance 💜.

🧚 QUIC API 🧚

The QUIC API performs no I/O on its own, leaving that to the API user. This means you can integrate QUIC in any Python application, regardless of the concurrency model you're using 🦋.

Connection

The class signature is:

aioquic.quic.connection.QuicConnection(*, configuration, original_destination_connection_id=None, retry_source_connection_id=None, session_ticket_fetcher=None, session_ticket_handler=None, token_handler=None)

A QUIC connection. ✨

The state machine is driven by three kinds of sources:

  • the API user requesting data to be sent out (see connect(), reset_stream(), send_ping(), send_datagram_frame() and send_stream_data()) 💌
  • data being received from the network (see receive_datagram()) 📩
  • a timer firing (see handle_timer()) ⏰

Parameters

  • configuration (QuicConfiguration) — the QUIC configuration to use. 🎀

change_connection_id()

Switch to the next available connection ID and retire the previous one. Bestie, this one is a glow-up 🌈.

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 (aioquic.asyncio.QuicConnectionProtocol.transmit) will do it for you. 💅

Return type: None

close(error_code=QuicErrorCode.NO_ERROR, frame_type=None, reason_phrase='')

Close the connection. Bye bye, connection 👋.

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 (aioquic.asyncio.QuicConnectionProtocol.transmit) will do it for you. 💅

Parameters

  • error_code (int) — an error code telling why the connection is being closed. 🚪
  • reason_phrase (str) — a human-readable explanation of why the connection is being closed. 📝

Return type: None

connect(addr, now)

Initiate the TLS handshake. This can only be called for clients, and only a single time. Ngl, that's a strict vibe 🙅‍♀️.

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 (aioquic.asyncio.QuicConnectionProtocol.transmit) will do it for you. 💅

Parameters

  • addr (Any) — the network address of the remote peer. 🌍
  • now (float) — the current time. ⏱️

Return type: None

datagrams_to_send(now)

Return a list of (data, addr) tuples of datagrams which need to be sent, plus the network address each one needs to be sent to 📦.

After calling this method, call get_timer() to find out when the next timer needs to be set 🫶.

Parameters

  • now (float) — the current time. ⏱️

Return type: list[tuple[bytes, Any]]

get_next_available_stream_id(is_unidirectional=False)

Return the stream ID for the next stream created by this endpoint 🆔.

Return type: int

get_timer()

Return the time at which the timer should fire, or None if no timer is needed. ⏰ Simple and iconic.

Return type: Optional[float]

handle_timer(now)

Handle the timer. Periodt ⏰.

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 (aioquic.asyncio.QuicConnectionProtocol.transmit) will do it for you. 💅

Parameters

  • now (float) — the current time. ⏱️

Return type: None

next_event()

Retrieve the next event from the event buffer. It returns None if there are no buffered events, so don't panic if it's empty 🫠.

Return type: Optional[QuicEvent]

receive_datagram(data, addr, now)

Handle an incoming datagram 📬.

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 (aioquic.asyncio.QuicConnectionProtocol.transmit) will do it for you. 💅

Parameters

  • data (bytes) — the datagram which was received. 📦
  • addr (Any) — the network address from which the datagram was received. 🌍
  • now (float) — the current time. ⏱️

Return type: None

request_key_update()

Request an update of the encryption keys. Key rotation hits different 🔑.

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 (aioquic.asyncio.QuicConnectionProtocol.transmit) will do it for you. 💅

Return type: None

reset_stream(stream_id, error_code)

Abruptly terminate the sending part of a stream. Yikes, no warning, just vibes 💀.

This method has no effect if a reset has already been triggered, either by a call to reset_stream() or by the reception of a STOP_SENDING frame. 🙅‍♀️

Okay bestie, the good stuff is here 🦋 Ready for the rest of the methods?

🚨 Heads up, bestie: after calling this one you still have to call the QUIC connection's datagrams_to_send() method to grab the data that needs to go out over the network 📡 If you're on the asyncio API, calling transmit() (that's aioquic.asyncio.QuicConnectionProtocol.transmit) does that step for you 💖

Parameters

  • stream_id (int) — the stream's ID 🌸
  • error_code (int) — an error code explaining why the stream is being reset 💀

Return type: None

send_datagram_frame(data) 🦋

Sends a DATAGRAM frame 📨

🚨 Heads up, bestie: after calling this one you still have to call the QUIC connection's datagrams_to_send() method to grab the data that needs to go out over the network 📡 If you're on the asyncio API, calling transmit() (that's aioquic.asyncio.QuicConnectionProtocol.transmit) does that step for you 💖

Parameters

  • data (bytes) — the data you want to send 🎀

Return type: None

send_ping(uid) 🏓

Sends a PING frame over to the peer 👀

🚨 Heads up, bestie: after calling this one you still have to call the QUIC connection's datagrams_to_send() method to grab the data that needs to go out over the network 📡 If you're on the asyncio API, calling transmit() (that's aioquic.asyncio.QuicConnectionProtocol.transmit) does that step for you 💖

Parameters

  • uid (int) — a unique ID for this PING 🆔

Return type: None

send_stream_data(stream_id, data, end_stream=False) 🧚

Sends data on a specific stream 💜

🚨 Heads up, bestie: after calling this one you still have to call the QUIC connection's datagrams_to_send() method to grab the data that needs to go out over the network 📡 If you're on the asyncio API, calling transmit() (that's aioquic.asyncio.QuicConnectionProtocol.transmit) does that step for you 💖

Parameters

  • stream_id (int) — the stream's ID 🌸
  • data (bytes) — the data you want to send 🎀
  • end_stream (bool) — if you set this to True, the FIN bit gets set 🏁 (the default is False)

Return type: None

stop_stream(stream_id, error_code) 🛑

Requests termination of the receiving side of a stream 🙅‍♀️

🚨 Heads up, bestie: after calling this one you still have to call the QUIC connection's datagrams_to_send() method to grab the data that needs to go out over the network 📡 If you're on the asyncio API, calling transmit() (that's aioquic.asyncio.QuicConnectionProtocol.transmit) does that step for you 💖

Parameters

  • stream_id (int) — the stream's ID 🌸
  • error_code (int) — an error code explaining why the stream is being stopped 💅

Return type: None

✨ Configuration ✨

Here's where the settings live, so you can set up your connection exactly how you want it 🎀

aioquic.quic.configuration.QuicConfiguration

class aioquic.quic.configuration.QuicConfiguration(alpn_protocols=None, congestion_control_algorithm='reno', connection_id_length=8, idle_timeout=60.0, is_client=True, max_data=1048576, max_datagram_size=1200, max_stream_data=1048576, quic_logger=None, secrets_log_file=None, server_name=None, session_ticket=None, token=b'', cadata=None, cafile=None, capath=None, certificate=None, certificate_chain=<factory>, cipher_suites=None, initial_rtt=0.1, max_datagram_frame_size=None, original_version=None, private_key=None, quantum_readiness_test=False, supported_versions=<factory>, verify_mode=None)

This is your QUIC configuration class, the whole vibe for your connection 👑

alpn_protocols: Optional[list[str]] = None 🌈

A list of the ALPN protocols you support 💖

congestion_control_algorithm: str = 'reno' 🌊

The name of the congestion control algorithm you want to use 🦋

Currently supported algorithms are "reno" and "cubic" ✨

connection_id_length: int = 8 🪪

The length in bytes of your local connection IDs 🔢

idle_timeout: float = 60.0 ⏰

The idle timeout in seconds ⏳

⚠️ The connection gets terminated if nothing is received for the given duration, so don't ghost your peer for too long 💀

is_client: bool = True 🙋‍♀️

Whether this is the client side of the QUIC connection 💜

load_cert_chain(certfile, keyfile=None, password=None) 🔐

Loads a private key and its matching certificate 🗝️

Return type: None

load_verify_locations(cafile=None, capath=None, cadata=None) 📜

Loads a set of "certification authority" (CA) certificates, which are used to validate other peers' certificates 🕵️‍♀️

Return type: None

max_data: int = 1048576 🪣

The connection-wide flow control limit 🚦

max_datagram_size: int = 1200 📦

The maximum QUIC payload size in bytes to send, not counting UDP or IP overhead 📏

max_stream_data: int = 1048576 🎀

The per-stream flow control limit 🚥

quic_logger: Optional[QuicLogger] = None 📝

The QuicLogger instance you want to log events to 🪄

secrets_log_file: Optional[TextIO] = None 🔑

A file-like object where traffic secrets get logged 🫣

This is super useful for analyzing traffic captures with Wireshark 🦈

server_name: Optional[str] = None 🏷️

The server name to use when verifying the server's TLS certificate. It can be either a DNS name or an IP address 🌐

If it's a DNS name, it also gets sent during the TLS handshake in the Server Name Indication (SNI) extension 💅

📝 Note: this is only used by clients 🫶

session_ticket: Optional[SessionTicket] = None 🎟️

The TLS session ticket that should be used for session resumption 🔁

token: bytes = b'' 🪙

The address validation token that can be used to validate future connections 🧿

📝 Note: this is only used by clients 🫶

aioquic.quic.logger.QuicLogger

class aioquic.quic.logger.QuicLogger

A QUIC event logger that stores traces in memory 🧠

to_dict() 📚

Returns the traces as a dictionary, which you can write out as JSON 📤

Return type: dict[str, Any]

✨ Events ✨

Events are how your connection tells you what just happened, so pay attention 👀

aioquic.quic.events.QuicEvent

class aioquic.quic.events.QuicEvent

The base class for all QUIC events 🌟

aioquic.quic.events.ConnectionTerminated

class aioquic.quic.events.ConnectionTerminated(error_code, frame_type, reason_phrase)

This event fires when the QUIC connection gets terminated 💔

error_code: int 🚫

The error code that was specified when the connection was closed 🔢

frame_type: Optional[int] 🧩

The frame type that caused the connection to close, or None 🤷‍♀️

reason_phrase: str 💬

The human-readable reason the connection was closed 📖

aioquic.quic.events.HandshakeCompleted

class aioquic.quic.events.HandshakeCompleted(alpn_protocol, early_data_accepted, session_resumed)

This event fires when the TLS handshake completes, and that's a whole main-character moment 🎉✨

Okay so the events are literally where the QUIC API gets its glow-up 💅 Here's the rest of the HandshakeCompleted attributes ✨

  • alpn_protocol (Optional[str]) — The protocol that got negotiated through ALPN, or None if nothing did 🎀
  • early_data_accepted (bool) — Whether the remote peer said yes to early (0-RTT) data 🚀
  • session_resumed (bool) — Whether a TLS session got resumed 🔁

class aioquic.quic.events.PingAcknowledged(uid)

The PingAcknowledged event pops off when a PING frame gets acknowledged. 🏓

  • uid (int) — The unique ID of that PING 🆔

class aioquic.quic.events.StopSendingReceived(error_code, stream_id)

The StopSendingReceived event fires when the remote peer basically says "hey, please stop sending data on this stream." 🙅‍♀️

  • error_code (int) — The error code the peer sent along with that request 💀
  • stream_id (int) — The ID of the stream the peer wants you to stop transmitting data on 🛑

class aioquic.quic.events.StreamDataReceived(data, end_stream, stream_id)

The StreamDataReceived event fires every time data shows up on a stream. 📬

  • data (bytes) — The data that got received 📦
  • end_stream (bool) — Whether the STREAM frame had the FIN bit set. Basically, is this the goodbye message? 👋
  • stream_id (int) — The ID of the stream that the data came in on 🧵

class aioquic.quic.events.StreamReset(error_code, stream_id)

The StreamReset event fires when the remote peer resets a stream. Rip 😭

  • error_code (int) — The error code that caused the reset 🫠
  • stream_id (int) — The ID of the stream that got reset 🔄

✨ HTTP/3 API ✨

Okay bestie, the HTTP/3 API does no I/O on its own 🙅‍♀️ It leaves all the sending and receiving to you, the API user. That means you can plug HTTP/3 into any Python app, no matter what concurrency model you're vibing with 🌈

🦋 Connection

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

A low-level HTTP/3 connection object. It's giving raw power 💪

Parameters

  • quic (QuicConnection) — A QuicConnection instance 🧠

create_webtransport_stream(session_id, is_unidirectional=False)

Creates a WebTransport stream and hands you back its stream ID. 🌊

Note: After calling this, you need to call the QUIC connection's datagrams_to_send() method to grab the data that needs to go out over the network. If you're using the asyncio API, calling the transmit() method does that part for you. 🫶

Parameters

  • session_id (int) — The WebTransport session identifier 🆔
  • is_unidirectional (bool) — Whether you want a unidirectional stream (one-way, no cap) ➡️

Return type: int

handle_event(event)

Handles a QUIC event and returns a list of HTTP events. Main character energy ⭐

Parameters

  • event (QuicEvent) — The QUIC event you want to handle 🎯

Return type: list[H3Event]

property received_settings: dict[int, int] | None

Returns the received SETTINGS frame, or None if there isn't one yet. ⚙️

send_data(stream_id, data, end_stream)

Sends data on the given stream. 📤

Note: After calling this, you need to call the QUIC connection's datagrams_to_send() method to grab the data that needs to go out over the network. If you're using the asyncio API, calling the transmit() method does that part for you. 🫶

Parameters

  • stream_id (int) — The stream ID you're sending on 🧵
  • data (bytes) — The data you're sending 📦
  • end_stream (bool) — Whether to end the stream here 🏁

Return type: None

send_datagram(stream_id, data)

Sends a datagram for the specified stream. Quick heads up: if the stream ID isn't a client-initiated bidirectional stream, an InvalidStreamTypeError exception gets raised. Not it 🙅‍♀️

Note: After calling this, you need to call the QUIC connection's datagrams_to_send() method to grab the data that needs to go out over the network. If you're using the asyncio API, calling the transmit() method does that part 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)

Sends headers on the given stream. 💌

Note: After calling this, you need to call the QUIC connection's datagrams_to_send() method to grab the data that needs to go out over the network. If you're using the asyncio API, calling the transmit() method does that part for you. 🫶

Parameters

  • stream_id (int) — The stream ID you want the headers sent on 🧵
  • 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)

Sends a push promise related to the specified stream. 🔮 It returns the stream ID where headers and data can be sent next.

If the stream ID isn't a client-initiated bidirectional stream, an InvalidStreamTypeError exception is raised. Big oof 😬

If there aren't any available push IDs, a NoAvailablePushIDError exception is raised. Also a big oof 💀

Note: After calling this, you need to call the QUIC connection's datagrams_to_send() method to grab the data that needs to go out over the network. If you're using the asyncio API, calling the transmit() method does that part for you. 🫶

Parameters

  • stream_id (int) — The stream ID the push promise is related to 🧵
  • headers (list[tuple[bytes, bytes]]) — The HTTP request headers for this push 📨

Return type: int

The last bit of the connection stuff 💅 property sent_settings: dict[int, int] | None hands you back the SETTINGS frame that was sent, or None if there isn't one 🌸

✨ Events ✨

class aioquic.h3.events.H3Event 👑

This is the base class for all HTTP/3 events. Every other event below builds on it.

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

This one fires whenever a datagram comes in from the remote peer. Main character moment 💖

  • data: bytes — the data that 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 fires whenever data arrives on a stream from the remote peer. It's giving "stuff is happening" 💅

  • data: bytes — the data that was received
  • push_id: Optional[int] = None — the Push ID, or None if this isn't 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 fires whenever headers are received. Headers are literally the vibe check of every request 🔥

  • headers: list[tuple[bytes, bytes]] — the headers 💜
  • push_id: Optional[int] = None — the Push ID, or None if this isn't 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) 🧚

Okay, so the docs say this one is the PushedStreamReceived event, which fires whenever a pushed stream has been received from the remote peer. The class is actually called PushPromiseReceived though, so 🙈 just know they're the same energy.

  • 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 event fires whenever data is received for a WebTransport stream. Very iconic, very specific 💅

  • data: bytes — the data that 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 💀

This is the base class for all HTTP/3 exceptions. If something goes sideways, this is the parent that catches the drama 😭

class aioquic.h3.exceptions.InvalidStreamTypeError 🙈

An action was attempted on an invalid stream type. Not the move 💀

class aioquic.h3.exceptions.NoAvailablePushIDError 🌸

This one shows up when there are no available push IDs left, or when push isn't supported by the remote party. No push IDs left, no cap, no vibes 🫠

✨ ASYNCIO API ✨

okay bestie, the asyncio API is a high-level QUIC API built on top of https://docs.python.org/3/library/asyncio.html#module-asyncio, which is Python's standard asynchronous I/O framework 💅 if you already know asyncio you're basically already there 🫶

aioquic comes with a few examples you can copy and learn from, including:

  • an HTTP/3 client 🦋
  • an HTTP/3 server 🌸

you can browse all of them on GitHub at 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)

this one connects to a QUIC server at the host and port you give it ✨ connect() returns an awaitable, and when you await it you get a QuicConnectionProtocol back, which is what you use to create streams. the return type is AsyncGenerator[QuicConnectionProtocol, None].

connect() also takes these optional args, so pick whatever your vibe needs:

  • configuration — a QuicConfiguration configuration object (aioquic.quic.configuration.QuicConfiguration) 💖
  • create_protocol — lets you customize the Protocol (https://docs.python.org/3/library/asyncio-protocol.html#asyncio.Protocol) that manages the connection 🧚 it should be a callable or class that takes the same arguments as QuicConnectionProtocol and returns a QuicConnectionProtocol instance or a subclass of one.
  • session_ticket_handler — a callback the TLS engine calls when it receives a new session ticket 🎫
  • stream_handler — a callback that runs whenever a stream gets created 🌊 it has to accept two arguments: an asyncio.StreamReader (https://docs.python.org/3/library/asyncio-stream.html#asyncio.StreamReader) and an asyncio.StreamWriter (https://docs.python.org/3/library/asyncio-stream.html#asyncio.StreamWriter).
  • wait_connected — decides whether the context manager waits for the connection to be established before it yields the QuicConnectionProtocol. it defaults to True, but you can set it to False if you want to start sending data right away using 0-RTT 🚀
  • local_port — the UDP port number 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)

this starts a QUIC server at the host and port you pick 🏰 serve() requires a QuicConfiguration that has a TLS certificate and private key, passed in as the configuration argument. the return type is QuicServer.

serve() also takes these optional args:

  • create_protocol — same deal as the client version: customize the Protocol (https://docs.python.org/3/library/asyncio-protocol.html#asyncio.Protocol) that manages each connection. it should be a callable or class that takes the same arguments as QuicConnectionProtocol and returns a QuicConnectionProtocol instance or a subclass.
  • session_ticket_fetcher — a callback the TLS engine calls when the peer presents a session ticket 🔍 it should return the session ticket with the matching ID, or None if it can't find one.
  • session_ticket_handler — a callback the TLS engine calls when a new session ticket gets issued 📦 it should store the ticket so it can be looked up later.
  • retry — decides whether client addresses get validated before the cryptographic handshake, using a retry packet 🛡️ it's False by default.
  • stream_handler — a callback that runs whenever a stream is created 🌊 it has to accept two arguments: an asyncio.StreamReader (https://docs.python.org/3/library/asyncio-stream.html#asyncio.StreamReader) and an asyncio.StreamWriter (https://docs.python.org/3/library/asyncio-stream.html#asyncio.StreamWriter).

🌈 Common

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

this is the protocol class both sides use to manage a connection, and these are the methods you'll be calling on it 🧠

change_connection_id()

swaps out the connection ID used to talk to the peer 🔄 the old connection ID gets retired. the return type is None.

close(error_code=QuicErrorCode.NO_ERROR, reason_phrase='')

closes the connection 👋 the parameters are:

  • error_code (int) — an error code that explains why the connection is closing 🚨
  • reason_phrase (str) — a human-readable explanation of why the connection is closing 💬

the return type is None.

connect(addr, transmit=True)

kicks off the TLS handshake 🤝 this can only be called by clients, and only a single time. the return type is None.

await create_stream(is_unidirectional=False)

creates a QUIC stream and gives you back a (reader, writer) pair 🎀 the reader and writer are instances of asyncio.StreamReader (https://docs.python.org/3/library/asyncio-stream.html#asyncio.StreamReader) and asyncio.StreamWriter (https://docs.python.org/3/library/asyncio-stream.html#asyncio.StreamWriter). the return type is tuple[StreamReader, StreamWriter].

await ping()

pings the peer and waits for the response 🏓 the return type is None.

quic_event_received(event)

gets called whenever a QUIC event comes in 📨 if you're subclassing, reimplement this to handle the events. the return type is None.

request_key_update()

asks for an update of the encryption keys 🔐 the return type is None.

transmit()

sends any pending datagrams to the peer and arms the timer if it's needed ⏰ this gets called automatically when data comes in from the peer or when a timer goes off. but if you poke at the underlying QuicConnection (aioquic.quic.connection.QuicConnection) directly, make sure you call this method whenever data needs to head out to the network. the return type is None.

await wait_closed()

waits for the connection to close 🥀 the return type is None.

await wait_connected()

waits for the TLS handshake to finish ✅ the return type is None.

✨ CHANGELOG ✨

okay so this is the bit where the devs spill the tea on every release 💅 we're going newest to oldest, bestie 🫶

🎀 1.3.0

  • Ensure PATH_CHALLENGE frames get sent before any other frame types 🦋
  • Reclaim memory when HTTP/3 streams end 🧹✨
  • Limit the number of remote PATH_CHALLENGE stored per path 🔒
  • Avoid an assertion error when receiving multiple STOP_SENDING frames 🙈
  • Improve type annotations 💜
  • Make it possible to use LibreSSL instead of OpenSSL 🌸
  • Add support for Python 3.13 and 3.14, and drop support for Python 3.8 and 3.9 👑
  • Build binary wheels for musllinux <https://peps.python.org/pep-0656/> 🌈
  • Build binary wheels against OpenSSL <https://www.openssl.org/> 3.5.4 🔥
  • Add a command-line argument to the http3_client example to request a key update during interoperability tests 🧚

🎀 1.2.0

  • Add support for compatible version handling as defined in RFC 9368 <https://datatracker.ietf.org/doc/html/rfc9368.html> 🦋
  • Add support for QUIC Version 2, as defined in RFC 9369 <https://datatracker.ietf.org/doc/html/rfc9369.html> 👑
  • Drop support for draft QUIC versions which were obsoleted by RFC 9000 <https://datatracker.ietf.org/doc/html/rfc9000.html> 💀
  • Improve datagram padding to allow better packet coalescing and reduce the number of roundtrips during connection establishement ⭐
  • Fix server anti-amplification checks during address validation so they take invalid packets, such as datagram-level padding, into account 🫶
  • Allow asyncio clients to make efficient use of 0-RTT by passing wait_connected=False to connect() <#aioquic.asyncio.connect> 🚀
  • Add command-line arguments to the http3_client example for client certificates and for negotiating QUIC Version 2 🍓

🎀 1.1.0

🎀 1.0.0

  • Ensure no data is sent after a stream reset 🙅‍♀️
  • Make H3Connection <#aioquic.h3.connection.H3Connection>'s send_datagram() <#aioquic.h3.connection.H3Connection.send_datagram> and send_push_promise() <#aioquic.h3.connection.H3Connection.send_push_promise> methods raise an InvalidStreamTypeError <#aioquic.h3.exceptions.InvalidStreamTypeError> exception if an invalid stream ID is specified 🚨
  • Improve the documentation for QuicConnectionProtocol <#aioquic.asyncio.QuicConnectionProtocol>'s transmit() <#aioquic.asyncio.QuicConnectionProtocol.transmit> method 📚
  • Fix utcnow() <https://docs.python.org/3/library/datetime.html#datetime.datetime.utcnow> deprecation warning on Python 3.12 by using cryptography <https://cryptography.io/> 42.0 and timezone-aware datetime <https://docs.python.org/3/library/datetime.html#datetime.datetime> instances when validating TLS certificates 🧼
  • Build binary wheels against OpenSSL <https://www.openssl.org/> 3.2.0 📦
  • Ignore any non-ASCII ALPN values received 🙈
  • Perform more extensive HTTP/3 header validation in H3Connection <#aioquic.h3.connection.H3Connection> 🔍
  • Fix exceptions when draining stream writers in the asyncio API <> 🌊
  • Set the QuicConnection <#aioquic.quic.connection.QuicConnection> idle timer according to RFC 9000 <https://datatracker.ietf.org/doc/html/rfc9000.html> section 10.1 ⏰
  • Implement fairer stream scheduling in QuicConnection <#aioquic.quic.connection.QuicConnection> to avoid head-of-line blocking 🚦
  • Only load certifi <https://github.com/certifi/python-certifi> root certificates if none was specified in the QuicConfiguration <#aioquic.quic.configuration.QuicConfiguration> 🎯
  • Improve padding of UDP datagrams containing Initial packets to comply with RFC 9000 <https://datatracker.ietf.org/doc/html/rfc9000.html> section 14.1 📏
  • Limit the number of pending connection IDs marked for retirement to prevent a possible DoS attack 🛑

✨ LICENSE ✨

okay the legal part, but make it cute 🎀 this is the BSD 3-Clause license, so the vibe is: keep the copyright notice, keep the disclaimer, and don't use the names of the contributors to promote stuff without permission 🙅‍♀️

Copyright (c) Jeremy Lainé. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  • Neither the name of aioquic nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 💀 translation: no warranties, no promises, nothing. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 😭

✨ AUTHOR ✨

the genius behind it all is Jeremy Lainé 👑🫶

Jeremy Lainé owns the copyright 🎀

Written up on Jan 17, 2026 for AIOQUIC(1) 🦋 bestie, that's the whole manual, go touch some grass and then go read the source 💅✨

📦 where this page comes from