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.

3Classes3Functions

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

Functions

_build_encoding_priority 0 tuple[str, ...] ▼
Build encoding priority based on available libraries.
def _build_encoding_priority() -> tuple[str, ...]
Returns
tuple[str, ...]
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 1 Compressor ▼
Create a compressor instance for the given encoding.
def create_compressor(encoding: str) -> Compressor
Parameters
Name Type Description
encoding str

Encoding name (e.g., "zstd", "gzip").
Returns
Compressor