brotli

Brotli (PyPI: brotli) is the official Python binding for Google’s Brotli compression library, packaging the native C encoder and decoder as a CPython extension module. It implements the algorithm described in RFC 7932 — a combination of LZ77-style matching, Huffman coding, and second-order context modeling — delivering compression density competitive with the best general-purpose codecs while decompressing at speeds comparable to zlib.

The package exposes both a simple one-shot API (compress() / decompress()) and streaming Compressor / Decompressor classes for processing data incrementally, making it a drop-in choice for HTTP content-encoding, asset pipelines, and any workload that needs Brotli-compatible output without shelling out to a CLI.

What You Get

• One-shot compress/decompress - brotli.compress() and brotli.decompress() for simple byte-string round trips.
• Streaming Compressor/Decompressor classes - process large payloads incrementally without buffering the whole stream in memory.
• Tunable quality and window size - quality (0-11) and lgwin (10-24) parameters trade compression speed for density.
• Mode hints for text and fonts - MODE_TEXT and MODE_FONT let the encoder specialize context modeling for known content types.
• Native C extension performance - core encode/decode logic runs in Brotli’s shared C codebase used by every other language binding.

Common Use Cases

• HTTP content-encoding - compress response bodies with br encoding for smaller, faster page loads.
• Static asset pipelines - pre-compress JS/CSS/font bundles at build time for CDNs that serve .br files.
• WOFF2 font tooling - Brotli’s font mode underlies the WOFF2 web font compression format.
• General-purpose archival - swap in for gzip/zlib workloads that need a higher compression ratio at similar speed.

Under The Hood

Architecture The build (setup.py, pyproject.toml with the setuptools backend) compiles python/_brotli.c into a CPython extension that links directly against the shared C codebase in c/enc, c/dec, and c/common — the same encoder/decoder state machine used by every other language binding in this monorepo (Go, Java, C#, JS/WASM). python/brotli.py is a thin wrapper that re-exports the extension’s Compressor, Decompressor, compress(), and decompress() symbols with Python-friendly defaults and docstrings. Native calls release the GIL during heavy compute (Py_BEGIN_ALLOW_THREADS) and use critical sections under Python 3.13’s free-threaded build, so the binding layer stays a thin, well-isolated shim over a single shared core — a change to the core encoder/decoder state would ripple into every language binding, not just Python’s.

Tech Stack Pure setuptools build (no build-system extras beyond pkgconfig), with the C extension sourced from the top-level c/ directory shared across the whole repo. The package version is parsed directly out of c/common/version.h rather than duplicated in Python metadata. A USE_SYSTEM_BROTLI environment variable plus pkg-config lookup lets downstream packagers link against an OS-provided libbrotli instead of vendoring and rebuilding the C sources, which is how most Linux distro packages produce this wheel.

Code Quality Tests live under python/tests/ (compress_test.py, decompress_test.py, compressor_test.py, decompressor_test.py) and use pytest, parametrizing round-trip compress/decompress checks across quality levels, window sizes, and a shared text-input corpus (_test_utils.py) — a solid property-style regression suite for a codec. CI (.github/workflows/) runs multi-platform builds, WASM builds, CodeQL static analysis, continuous OSS-Fuzz fuzzing, lint checks, and an OpenSSF Scorecard job, which is unusually thorough for a compression binding. There’s no static type-checking layer on the thin Python wrapper, but the code follows the Google Python Style Guide with YAPF formatting.

API Design The public API is deliberately minimal and mirrors the stdlib zlib/gzip shape: module-level compress()/decompress() for the common one-shot case, and Compressor/Decompressor classes with process()/finish() for streaming. Sensible defaults (quality=11, lgwin=22) mean import brotli; brotli.compress(data) is a complete, correct usage — there’s essentially no boilerplate or configuration required to get started, and developers coming from zlib need almost no ramp-up.