Brotlipy: Python Bindings to Brotli Compression

0.7.0 · renamed · verified Sat Apr 11

brotlipy is a Python library that provides CFFI-based bindings to Google's Brotli lossless compression algorithm. It enables Python applications to efficiently compress and decompress data using Brotli, supporting both one-shot and streaming operations. Version 0.7.0 is the final release of this library, as the project has been archived and its development continues under the `brotlicffi` package.

Warnings

breaking The `brotlipy` package has been archived and is deprecated. All further development and updates have moved to the `brotlicffi` package. Users are strongly advised to migrate to `brotlicffi` for continued support and new features.
Fix: Migrate to `brotlicffi`: `pip install brotlicffi`. Update imports from `import brotli` to `import brotlicffi`. Refer to `brotlicffi` documentation for any API changes.
gotcha The `brotlipy` library installs as `brotlipy` but its main module is imported as `brotli`. This can create import conflicts if another Python package also provides a top-level `brotli` module (e.g., the pure-Python `brotli` package). The successor `brotlicffi` addresses this by using `import brotlicffi`.
Fix: Be aware of potential module name collisions. When migrating to `brotlicffi`, the import path changes to `import brotlicffi`.
gotcha On Linux systems, `brotlipy` is a CFFI-based binding that requires compilation during installation. This necessitates having a C compiler (e.g., `build-essential` or `gcc`), Python development headers (`python-dev` or `python-devel`), and the `libffi` development library (`libffi-dev` or `libffi-devel`) installed on the system.
Fix: Install the necessary system-level development packages before running `pip install brotlipy`. Examples: `sudo apt-get install build-essential python-dev libffi-dev` (Debian/Ubuntu) or `sudo yum install gcc libffi-devel python-devel` (Red Hat/CentOS).
gotcha When using dictionaries with the compression and decompression APIs, it is crucial that the *exact same dictionary* is provided to both the compressor and the decompressor. A mismatch will lead to decompression errors or corrupted output.
Fix: Ensure dictionary bytes are identical for corresponding compression and decompression operations. Store and manage dictionaries carefully.

Install

pip install brotlipy Basic Installation
sudo apt-get install build-essential python-dev libffi-dev Linux Build Dependencies (Debian/Ubuntu)
sudo yum install gcc libffi-devel python-devel Linux Build Dependencies (Red Hat/CentOS)

Imports

brotli
```
import brotli
```
The package installs as `brotlipy` but exposes its functionality under the `brotli` module name, which can lead to conflicts with other `brotli` packages.
compress
```
brotli.compress(data)
```
For one-shot compression.
decompress
```
brotli.decompress(data)
```
For one-shot decompression.
Compressor
```
brotli.Compressor()
```
For streaming compression.
Decompressor
```
brotli.Decompressor()
```
For streaming decompression.
Error
```
brotli.Error
```
Exception raised for compression/decompression errors.

Quickstart

This quickstart demonstrates both one-shot and streaming compression/decompression using `brotlipy`. For one-shot operations, `brotli.compress()` and `brotli.decompress()` are used. For streaming, `brotli.Compressor()` and `brotli.Decompressor()` objects are initialized, and data is processed in chunks. Remember that `brotli.compress()` and `brotli.decompress()` expect and return byte strings.

import brotli

original_data = b"This is some data to be compressed using Brotli. It can be any bytes string."

# One-shot compression and decompression
compressed_data = brotli.compress(original_data, quality=11) # quality from 0-11
decompressed_data = brotli.decompress(compressed_data)

print(f"Original size: {len(original_data)} bytes")
print(f"Compressed size: {len(compressed_data)} bytes")
print(f"Decompressed data matches original: {original_data == decompressed_data}")

# Streaming compression
compressor = brotli.Compressor(quality=5)
compressed_stream = b''
chunk_size = len(original_data) // 2

compressed_stream += compressor.compress(original_data[:chunk_size])
compressed_stream += compressor.compress(original_data[chunk_size:])
compressed_stream += compressor.finish()

# Streaming decompression
decompressor = brotli.Decompressor()
decompressed_stream = b''

decompressed_stream += decompressor.decompress(compressed_stream[:chunk_size])
decompressed_stream += decompressor.decompress(compressed_stream[chunk_size:])
decompressed_stream += decompressor.flush() # flush() is deprecated for Decompressor since 0.4.0 but shown in older docs

print(f"Streaming decompression matches original: {original_data == decompressed_stream}")

view raw JSON →