pylsqpack

Warnings

• breaking The underlying `ls-qpack` C library, which `pylsqpack` wraps, underwent significant API changes in its 2.x versions. `pylsqpack` did not immediately update to `ls-qpack` 2.x due to these substantial changes. Users expecting direct compatibility or features available only in `ls-qpack` 2.x may encounter mismatches. [10]
  Fix: Consult the `pylsqpack` documentation or GitHub issues for updates regarding `ls-qpack` 2.x compatibility. Ensure the features you need are supported by the `ls-qpack` version `pylsqpack` is built against.
• gotcha `pylsqpack` is a wrapper around a C library (`ls-qpack`). Its behavior and performance are inherently tied to the underlying C implementation. Advanced usage, performance tuning, or debugging complex QPACK scenarios may require a conceptual understanding of the QPACK specification and the `ls-qpack` C API beyond just the Python bindings. [1, 2, 3]
  Fix: Familiarize yourself with the QPACK specification and the `ls-qpack` library's design principles, especially for production environments or when deep customization is required.
• gotcha The `Decoder` and `Encoder` constructors require `max_table_capacity` and `blocked_streams` parameters. These are crucial QPACK-specific settings. Incorrectly setting these values (e.g., not matching the values advertised by the peer via HTTP/3 SETTINGS frames) can lead to suboptimal compression/decompression, stream blocking, or outright decoding failures. [2]
  Fix: Ensure that `max_table_capacity` and `blocked_streams` are set correctly based on the QPACK settings exchanged with the peer in your HTTP/3 connection. Refer to the QPACK specification (RFC 9204) for details on these parameters.

Install

• pip install pylsqpack Install latest version

Imports

• Encoder

  from pylsqpack import Encoder

• Decoder

  from pylsqpack import Decoder

Quickstart

This quickstart demonstrates how to initialize an `Encoder` and `Decoder`, encode a list of HTTP/3 headers, and then decode the resulting header block. Note the use of bytes for header names and values, and the `max_table_capacity` and `blocked_streams` parameters for the `Decoder` (and implicitly for `Encoder` settings which would be exchanged via HTTP/3 SETTINGS frames). [2, 7]

from pylsqpack import Encoder, Decoder

# Example HTTP/3 headers
headers = [
    (b':method', b'GET'),
    (b':scheme', b'https'),
    (b':path', b'/resource'),
    (b':authority', b'example.org'),
    (b'user-agent', b'pylsqpack-example/1.0')
]

# Encoder initialization
# The exact values for max_table_capacity and blocked_streams depend on QPACK settings
e = Encoder()

# Encode headers for stream ID 0
# The encode method returns a tuple: (encoder_stream_data, encoded_header_block)
encoder_stream_data, encoded_header_block = e.encode(0, headers)

print("Original Headers:", headers)
print("Encoded Header Block:", encoded_header_block)

# Decoder initialization
# max_table_capacity and blocked_streams must match peer's settings
d = Decoder(max_table_capacity=4096, blocked_streams=100)

# Feed encoder stream data to the decoder, if any
# (In simple encode/decode, this might be empty, but important for full QPACK interaction)
if encoder_stream_data:
    unblocked_streams = d.feed_encoder_stream(encoder_stream_data)
    # For actual HTTP/3, you'd then resume decoding for unblocked_streams

# Decode the header block for stream ID 0
try:
    control_data, decoded_headers = d.decode(0, encoded_header_block)
    print("Decoded Headers:", decoded_headers)
except Exception as e:
    print(f"Decoding failed: {e}")