Metadata-Version: 2.4
Name: brotli-rs
Version: 9.1.1.post2
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Programming Language :: Rust
Classifier: Topic :: System :: Archiving :: Compression
Classifier: Typing :: Typed
Requires-Dist: brotli==1.2.1 ; extra == 'test'
Requires-Dist: hypothesis>=6 ; extra == 'test'
Requires-Dist: pytest>=8 ; extra == 'test'
Provides-Extra: test
License-File: LICENSE
License-File: licenses/README.md
License-File: licenses/alloc-no-stdlib-3.0.0/LICENSE
License-File: licenses/alloc-stdlib-0.3.0/LICENSE
License-File: licenses/brotli-9.1.0/LICENSE.BSD-3-Clause
License-File: licenses/brotli-9.1.0/LICENSE.MIT
License-File: licenses/brotli-decompressor-6.2.0/LICENSE
License-File: licenses/heck-0.5.0/LICENSE-APACHE
License-File: licenses/heck-0.5.0/LICENSE-MIT
License-File: licenses/libc-0.2.191/LICENSE-APACHE
License-File: licenses/libc-0.2.191/LICENSE-MIT
License-File: licenses/once_cell-1.21.4/LICENSE-APACHE
License-File: licenses/once_cell-1.21.4/LICENSE-MIT
License-File: licenses/portable-atomic-1.15.0/LICENSE-APACHE
License-File: licenses/portable-atomic-1.15.0/LICENSE-MIT
License-File: licenses/proc-macro2-1.0.107/LICENSE-APACHE
License-File: licenses/proc-macro2-1.0.107/LICENSE-MIT
License-File: licenses/pyo3-0.30.1/LICENSE-APACHE
License-File: licenses/pyo3-0.30.1/LICENSE-MIT
License-File: licenses/pyo3-build-config-0.30.1/LICENSE-APACHE
License-File: licenses/pyo3-build-config-0.30.1/LICENSE-MIT
License-File: licenses/pyo3-ffi-0.30.1/LICENSE-APACHE
License-File: licenses/pyo3-ffi-0.30.1/LICENSE-MIT
License-File: licenses/pyo3-macros-0.30.1/LICENSE-APACHE
License-File: licenses/pyo3-macros-0.30.1/LICENSE-MIT
License-File: licenses/pyo3-macros-backend-0.30.1/LICENSE-APACHE
License-File: licenses/pyo3-macros-backend-0.30.1/LICENSE-MIT
License-File: licenses/quote-1.0.47/LICENSE-APACHE
License-File: licenses/quote-1.0.47/LICENSE-MIT
License-File: licenses/syn-3.0.9/LICENSE-APACHE
License-File: licenses/syn-3.0.9/LICENSE-MIT
License-File: licenses/target-lexicon-0.13.5/LICENSE
License-File: licenses/unicode-ident-1.0.27/LICENSE-APACHE
License-File: licenses/unicode-ident-1.0.27/LICENSE-MIT
License-File: licenses/unicode-ident-1.0.27/LICENSE-UNICODE
Summary: Python bindings for the safe-Rust brotli crate
Keywords: brotli,compression,rust
Home-Page: https://github.com/bugsink/brotli-rs
License-Expression: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Issues, https://github.com/bugsink/brotli-rs/issues
Project-URL: Source, https://github.com/bugsink/brotli-rs

# brotli-rs

<img src="https://raw.githubusercontent.com/bugsink/brotli-rs/main/brotli-rs-logo.png"
     alt="brotli-rs logo" width="128" align="right">

Python bindings for Dropbox's safe-Rust [`brotli`](https://github.com/dropbox/rust-brotli) crate.

The C implementation [is a security liability](https://www.bugsink.com/blog/bye-bye-brotli/) and
is not regularly released; this package remedies that by providing a memory-safe alternative.
It is a drop-in replacement for the [`Brotli`](https://pypi.org/project/Brotli/) package.

## How to use

The public API follows the `Brotli` Python package where that can be done
without inheriting its C extension. The distribution and import names are
both `brotli-rs` / `brotli_rs`, deliberately avoiding a collision with the
existing `brotli` module.

```python
import brotli_rs as brotli

compressed = brotli.compress(b"hello")
assert brotli.decompress(compressed) == b"hello"
```

Streaming compression and decompression are available through `Compressor`
and `Decompressor`. `Decompressor.process()` supports a strict
`output_buffer_limit`, and both streaming and one-shot decompression accept an
optional `max_output` limit.

```python
decoder = brotli.Decompressor(max_output=16 * 1024 * 1024)
parts = []
for compressed_chunk in source:
    while not decoder.is_finished() and not decoder.can_accept_more_data():
        parts.append(decoder.process(b"", output_buffer_limit=64 * 1024))
    parts.append(decoder.process(compressed_chunk, output_buffer_limit=64 * 1024))
while not decoder.is_finished() and not decoder.can_accept_more_data():
    parts.append(decoder.process(b"", output_buffer_limit=64 * 1024))
if not decoder.is_finished():
    raise brotli.error("incomplete stream")
```

The compatibility surface consists of `compress`, `decompress`,
`Compressor.process()` / `.flush()` / `.finish()`,
`Decompressor.process()` / `.can_accept_more_data()` / `.is_finished()`, the
three `MODE_*` constants, `error`, `version`, and `__version__`. 

Compressed bytes are not promised to be byte-identical to Google's encoder.
They are Brotli-compatible streams, tested in both directions against whatever
the most recent Google encoder produces/consumers.

Exception text, subclassing, pickling, non-contiguous buffers,
and private implementation names are outside the compatibility contract.

The base package version tracks the Rust `brotli` crate exactly.

## Development

Install Rust and Python 3.11 or newer, then:

```console
python -m venv .venv
. .venv/bin/activate
python -m pip install maturin
maturin develop --extras=test
pytest
```

[See](tests/upstream/README.md) the provenance of imported and adapted upstream
tests.

This package was built with heavy use of LLMs. Trust in its correctness is
derived from the circa 500 tests, which are a combination of upstream tests
and new tests for the Python API. Also: the actual interface surface is small
enough to be manually reviewed, and the underlying Rust crate is well-tested and
actively maintained. Also also: it's not the upstream [C lib is free from LLM mistakes](https://github.com/google/brotli/commit/643b22949dacf6fa1d471ca95279e3885c767838).

