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 — thebrotliC extension re-enables the GIL on Python 3.14t, defeating pounce's free-threading architecture. Clients that only sendAccept-Encoding: brwill receive uncompressed responses.

Dictionary compression (RFC 9842): When a client sends an Available-Dictionaryheader matching a server-loaded dictionary, responses usedcz(dictionary-compressed zstd) encoding for dramatically better compression ratios on repetitive payloads.

5Classes7Functions

Classes

Compressor 4 ▼
Contract for content encoders.

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 aCompressionDictionaryto achieve dramatically better compression ratios on repetitive payloads (e.g. API JSON responses). TheContent-Encoding is dcz(dictionary-compressed zstd).

Each request gets its own DictZstdCompressor — the underlying ZstdDictis 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 stdlibZstdDictinstance 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 ▼
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 byzstd --train).
match str

URL pattern this dictionary applies to.
Returns
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
create_compressor 2 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 | None

Optional compression dictionary fordczencoding.

Default:None
Returns
Compressor
negotiate_dictionary 3 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

TheAvailable-Dictionaryheader value (sf-binary hash).
dictionaries tuple[CompressionDictionary, ...]

Server-loaded dictionaries to match against.
request_target str

The request URL path — used to filter bymatchpattern.

Default:''
Returns
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