{"id":2698,"library":"pylsqpack","title":"pylsqpack","description":"pylsqpack is a Python wrapper for the `ls-qpack` C library, providing Python `Decoder` and `Encoder` objects for reading and writing HTTP/3 headers compressed with QPACK. It enables applications to handle the header compression and decompression necessary for HTTP/3. It is currently at version 0.3.24 and is maintained as part of the `aiortc` project. [1, 4]","status":"active","version":"0.3.24","language":"en","source_language":"en","source_url":"https://github.com/aiortc/pylsqpack","tags":["HTTP/3","QPACK","compression","networking","aiortc"],"install":[{"cmd":"pip install pylsqpack","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"pylsqpack is a wrapper around the `ls-qpack` C library. The C library is typically bundled within the prebuilt wheels.","package":"ls-qpack","optional":false}],"imports":[{"note":null,"wrong":null,"symbol":"Encoder","correct":"from pylsqpack import Encoder"},{"note":null,"wrong":null,"symbol":"Decoder","correct":"from pylsqpack import Decoder"}],"quickstart":{"code":"from pylsqpack import Encoder, Decoder\n\n# Example HTTP/3 headers\nheaders = [\n    (b':method', b'GET'),\n    (b':scheme', b'https'),\n    (b':path', b'/resource'),\n    (b':authority', b'example.org'),\n    (b'user-agent', b'pylsqpack-example/1.0')\n]\n\n# Encoder initialization\n# The exact values for max_table_capacity and blocked_streams depend on QPACK settings\ne = Encoder()\n\n# Encode headers for stream ID 0\n# The encode method returns a tuple: (encoder_stream_data, encoded_header_block)\nencoder_stream_data, encoded_header_block = e.encode(0, headers)\n\nprint(\"Original Headers:\", headers)\nprint(\"Encoded Header Block:\", encoded_header_block)\n\n# Decoder initialization\n# max_table_capacity and blocked_streams must match peer's settings\nd = Decoder(max_table_capacity=4096, blocked_streams=100)\n\n# Feed encoder stream data to the decoder, if any\n# (In simple encode/decode, this might be empty, but important for full QPACK interaction)\nif encoder_stream_data:\n    unblocked_streams = d.feed_encoder_stream(encoder_stream_data)\n    # For actual HTTP/3, you'd then resume decoding for unblocked_streams\n\n# Decode the header block for stream ID 0\ntry:\n    control_data, decoded_headers = d.decode(0, encoded_header_block)\n    print(\"Decoded Headers:\", decoded_headers)\nexcept Exception as e:\n    print(f\"Decoding failed: {e}\")\n","lang":"python","description":"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]"},"warnings":[{"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.","message":"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]","severity":"breaking","affected_versions":"<=0.3.24 (compared to `ls-qpack` 2.x)"},{"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.","message":"`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]","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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]","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}