# _compression URL: /pounce/api/_compression/ Section: api Description: Content encoding negotiation and compressor factory. Parses Accept-Encoding headers, selects the best encoding, and returns per-request compressor instances. Each compressor is created fresh per request — never shared between requests or threads. Encoding priority: zstd > gzip > identity (matching modern browser support). Zstd uses Python 3.14 stdlib compression.zstd (PEP 784). Gzip uses stdlib zlib for the raw deflate stream. Both are stdlib modules that work correctly under free-threading (3.14t). Note: Brotli (br) is intentionally excluded — the ``brotli`` C extension re-enables the GIL on Python 3.14t, defeating pounce's free-threading architecture. Clients that only send ``Accept-Encoding: br`` will receive uncompressed responses. Dictionary compression (RFC 9842): When a client sends an ``Available-Dictionary`` header matching a server-loaded dictionary, responses use ``dcz`` (dictionary-compressed zstd) encoding for dramatically better compression ratios on repetitive payloads. --- > For a complete page index, fetch /pounce/llms.txt. Open LLM text (/pounce/api/_compression/index.txt) Share with AI Ask Claude (https://claude.ai/new?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2F_compression%2Findex.txt) Ask ChatGPT (https://chatgpt.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2F_compression%2Findex.txt) Ask Gemini (https://gemini.google.com/app?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2F_compression%2Findex.txt) Ask Copilot (https://copilot.microsoft.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2F_compression%2Findex.txt) Module # `_compression` Content encoding negotiation and compressor factory. Parses Accept-Encoding headers, selects the best encoding, and returns per-request compressor instances. Each compressor is created fresh per request — never shared between requests or threads. Encoding priority: zstd > gzip > identity (matching modern browser support). Zstd uses Python 3.14 stdlib compression.zstd (PEP 784). Gzip uses stdlib zlib for the raw deflate stream. Both are stdlib modules that work correctly under free-threading (3.14t). Note: Brotli (br) is intentionally excluded — the`brotli`C extension re-enables the GIL on Python 3.14t, defeating pounce's free-threading architecture. Clients that only send`Accept-Encoding: br`will receive uncompressed responses. Dictionary compression (RFC 9842): When a client sends an `Available-Dictionary`header matching a server-loaded dictionary, responses use`dcz`(dictionary-compressed zstd) encoding for dramatically better compression ratios on repetitive payloads. 5Classes10Functions ## Classes `Compressor` 4 ▼ Contract for content encoders. Bases: `Protocol` Contract for content encoders. #### Methods `encoding` 0 `str` ▼ The Content-Encoding value for this compressor (e.g., 'gzip'). property `def encoding(self) -> str` ##### Returns `str` `compress` 1 `bytes` ▼ Compress a chunk of data. `def compress(self, data: bytes) -> bytes` ##### Parameters Name Type Description `data` `—` Input bytes to compress. ##### Returns `bytes` Compressed bytes (may be empty if buffering internally). `flush` 0 `bytes` ▼ Flush any buffered compressed data and finalize the stream. After calling flus… `def flush(self) -> bytes` Flush any buffered compressed data and finalize the stream. After calling flush(), the compressor should not be used again. ##### Returns `bytes` Final compressed bytes. `sync_flush` 0 `bytes` ▼ Force buffered data out without finalizing the stream. Used for streaming resp… `def sync_flush(self) -> bytes` Force buffered data out without finalizing the stream. Used for streaming responses where each chunk must produce compressed output immediately. The compressor remains usable after this call. ##### Returns `bytes` Compressed bytes for any internally buffered data. `GzipCompressor` 5 ▼ Gzip compressor using stdlib zlib. Creates a fresh zlib compressor per instance. Each request gets… Gzip compressor using stdlib zlib. Creates a fresh zlib compressor per instance. Each request gets its own GzipCompressor — no shared state. #### Methods `encoding` 0 `str` ▼ property `def encoding(self) -> str` ##### Returns `str` `compress` 1 `bytes` ▼ `def compress(self, data: bytes) -> bytes` ##### Parameters Name Type Description `data` `—` ##### Returns `bytes` `flush` 0 `bytes` ▼ `def flush(self) -> bytes` ##### Returns `bytes` `sync_flush` 0 `bytes` ▼ `def sync_flush(self) -> bytes` ##### Returns `bytes` Internal Methods 1 ▼ `__init__` 1 ▼ `def __init__(self, *, level: int = 6) -> None` ##### Parameters Name Type Description `level` `—` Default:`6` `ZstdCompressor` 5 ▼ Zstd compressor using Python 3.14 stdlib compression.zstd. Requires Python 3.14+ with compression.… Zstd compressor using Python 3.14 stdlib compression.zstd. Requires Python 3.14+ with compression.zstd available (PEP 784). Each request gets its own ZstdCompressor — no shared state. #### Methods `encoding` 0 `str` ▼ property `def encoding(self) -> str` ##### Returns `str` `compress` 1 `bytes` ▼ `def compress(self, data: bytes) -> bytes` ##### Parameters Name Type Description `data` `—` ##### Returns `bytes` `flush` 0 `bytes` ▼ `def flush(self) -> bytes` ##### Returns `bytes` `sync_flush` 0 `bytes` ▼ `def sync_flush(self) -> bytes` ##### Returns `bytes` Internal Methods 1 ▼ `__init__` 1 ▼ `def __init__(self, *, level: int = 3) -> None` ##### Parameters Name Type Description `level` `—` Default:`3` `DictZstdCompressor` 5 ▼ Zstd compressor pre-loaded with a shared dictionary (RFC 9842). Uses a ``CompressionDictionary`` t… Zstd compressor pre-loaded with a shared dictionary (RFC 9842). Uses a `CompressionDictionary` (/pounce/api/_compression/#CompressionDictionary) to achieve dramatically better compression ratios on repetitive payloads (e.g. API JSON responses). The`Content-Encoding` is `dcz`(dictionary-compressed zstd). Each request gets its own DictZstdCompressor — the underlying `ZstdDict`is immutable and safe to share across threads. #### Methods `encoding` 0 `str` ▼ property `def encoding(self) -> str` ##### Returns `str` `compress` 1 `bytes` ▼ `def compress(self, data: bytes) -> bytes` ##### Parameters Name Type Description `data` `—` ##### Returns `bytes` `flush` 0 `bytes` ▼ `def flush(self) -> bytes` ##### Returns `bytes` `sync_flush` 0 `bytes` ▼ `def sync_flush(self) -> bytes` ##### Returns `bytes` Internal Methods 1 ▼ `__init__` 2 ▼ `def __init__(self, zstd_dict: _zstd_mod.ZstdDict, *, level: int = 3) -> None` ##### Parameters Name Type Description `zstd_dict` `—` `level` `—` Default:`3` `CompressionDictionary` 4 ▼ A loaded zstd dictionary with its RFC 9842 identity. Immutable after creation — safe to share acro… A loaded zstd dictionary with its RFC 9842 identity. Immutable after creation — safe to share across threads. #### Attributes Name Type Description `sf_hash` `str` SHA-256 hash of dict content as sf-binary (e.g.`:abc=:`). `match` `str` URL pattern this dictionary applies to (e.g.`/api/v1/*`). `zstd_dict` `_zstd_mod.ZstdDict` The stdlib`ZstdDict`instance for compressor creation. #### Methods Internal Methods 1 ▼ `__init__` 2 ▼ `def __init__(self, dict_content: bytes, match: str) -> None` ##### Parameters Name Type Description `dict_content` `—` `match` `—` ## Functions `_build_encoding_priority` 0 `tuple[str, ...]` ▼ Build encoding priority based on available libraries. `def _build_encoding_priority() -> tuple[str, ...]` ##### Returns `tuple[str, ...]` `load_dictionary` 2 `CompressionDictionary (/pounce/api/_compression/#CompressionDictionary)` ▼ Load a zstd dictionary from disk. `def load_dictionary(path: Path, match: str) -> CompressionDictionary` ##### Parameters Name Type Description `path` `Path` Path to the dictionary file (created by`zstd --train`). `match` `str` URL pattern this dictionary applies to. ##### Returns `CompressionDictionary (/pounce/api/_compression/#CompressionDictionary)` `parse_sf_binary` 1 `bytes` ▼ Parse an RFC 8941 structured field binary value. Structured field binary is ba… `def parse_sf_binary(value: bytes | str) -> bytes` Parse an RFC 8941 structured field binary value. Structured field binary is base64-encoded content between colons: `:base64content=:` ##### Parameters Name Type Description `value` `bytes | str` The sf-binary value (with or without surrounding whitespace). ##### Returns `bytes` `negotiate_encoding` 1 `str | None` ▼ Parse Accept-Encoding and return the best supported encoding. Respects q-value… `def negotiate_encoding(accept_encoding: bytes | str) -> str | None` Parse Accept-Encoding and return the best supported encoding. Respects q-values and our encoding priority (zstd > gzip). Returns None if no supported encoding matches or the client explicitly declines all encodings. ##### Parameters Name Type Description `accept_encoding` `bytes | str` The Accept-Encoding header value. ##### Returns `str | None` `_parse_accept_encoding` 1 `dict[str, float]` ▼ Parse Accept-Encoding into an {encoding: q-value} mapping. Encodings explicitl… `def _parse_accept_encoding(accept_encoding: bytes | str) -> dict[str, float]` Parse Accept-Encoding into an {encoding: q-value} mapping. Encodings explicitly declined with`q=0`are omitted from the result. ##### Parameters Name Type Description `accept_encoding` `bytes | str` The Accept-Encoding header value. ##### Returns `dict[str, float]` `accepted_encodings` 1 `list[str]` ▼ Return acceptable encodings from Accept-Encoding, in our priority order. Respe… `def accepted_encodings(accept_encoding: bytes | str) -> list[str]` Return acceptable encodings from Accept-Encoding, in our priority order. Respects q-values: encodings with`q=0`are excluded and a non-zero wildcard (`*`) makes any priority encoding acceptable. Unlike `negotiate_encoding` (/pounce/api/_compression/#negotiate_encoding)(), this returns all acceptable priority encodings (zstd before gzip) so callers can pick the best variant that actually exists on disk. ##### Parameters Name Type Description `accept_encoding` `bytes | str` The Accept-Encoding header value. ##### Returns `list[str]` `create_compressor` 2 `Compressor (/pounce/api/_compression/#Compressor)` ▼ Create a compressor instance for the given encoding. `def create_compressor(encoding: str, *, dictionary: CompressionDictionary | None = None) -> Compressor` ##### Parameters Name Type Description `encoding` `str` Encoding name (e.g., "zstd", "gzip", "dcz"). `dictionary` `CompressionDictionary (/pounce/api/_compression/#CompressionDictionary) | None` Optional compression dictionary for`dcz`encoding. Default:`None` ##### Returns `Compressor (/pounce/api/_compression/#Compressor)` `negotiate_dictionary` 3 `CompressionDictionary (/pounce/api/_compression/#CompressionDictionary) | …` ▼ Match an ``Available-Dictionary`` header to a loaded dictionary. `def negotiate_dictionary(available_dictionary: bytes | str, dictionaries: tuple[CompressionDictionary, ...], request_target: str = '') -> CompressionDictionary | None` ##### Parameters Name Type Description `available_dictionary` `bytes | str` The`Available-Dictionary`header value (sf-binary hash). `dictionaries` `tuple[CompressionDictionary (/pounce/api/_compression/#CompressionDictionary), ...]` Server-loaded dictionaries to match against. `request_target` `str` The request URL path — used to filter by`match`pattern. Default:`''` ##### Returns `CompressionDictionary (/pounce/api/_compression/#CompressionDictionary) | None` `_match_pattern` 2 `bool` ▼ Simple glob-style match: ``/api/v1/*`` matches ``/api/v1/users``. `def _match_pattern(pattern: str, target: str) -> bool` ##### Parameters Name Type Description `pattern` `str` `target` `str` ##### Returns `bool` `should_compress_body` 2 `bool` ▼ Decide whether a response body of known size should be compressed. Used by the… `def should_compress_body(known_size: int | None, min_size: int) -> bool` Decide whether a response body of known size should be compressed. Used by the async H1/H2/H3 bridges to enforce `ServerConfig.compression_min_size`for the common single-shot case (one`http.response.body` with `more_body=False`, or an app-supplied `Content-Length` at `http.response.start`). ##### Parameters Name Type Description `known_size` `int | None` The body size in bytes when known, or`None`for a genuinely streaming response of unknown total size. `min_size` `int` The configured`compression_min_size`threshold. ##### Returns `bool`