Rust-for-CPython · dmadisetti · May 19, 2026 · May 19, 2026 · May 19, 2026 · May 19, 2026
diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml
@@ -93,9 +93,14 @@ jobs:
           - runner: windows-latest
             target: x64
             python_arch: x64
-          - runner: windows-latest
-            target: x86
-            python_arch: x86
+          # x86 (i686) target disabled: hosted runner ships only x64 pythons
+          # in C:\hostedtoolcache, so maturin --find-interpreter skips all
+          # of them with a platform-mismatch warning and the build fails
+          # with "Could not find any interpreters". Re-enable once we have
+          # a way to provision a 32-bit interpreter on the runner.
+          # - runner: windows-latest
+          #   target: x86
+          #   python_arch: x86
           - runner: windows-11-arm
             target: aarch64
             python_arch: arm64

diff --git a/Cargo.toml b/Cargo.toml
@@ -10,5 +10,5 @@ crate-type = ["cdylib"]
 
 
 [dependencies]
-pyo3 = { version = "0.27.0", features = ["abi3-py38"] }
+pyo3 = { version = "0.27.0", features = ["abi3-py311"] }
 zlib-rs = "0.6.3"
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rust for CPython enthusiasts
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
@@ -32,9 +32,41 @@ uv run maturin develop
 uv run python -c 'import zlib_py; print(zlib_py.compress(...))'
 ```
 
-This uses whatever CPython + pyo3 your environment resolves (no grantees of working).
+This uses whatever CPython + pyo3 your environment resolves (no guarantees of working).
 
 
+## Benchmarks
+
+The benchmark script (vendored from `farhaanaliii/zlib-rs-python`) compares
+`zlib_py` against the stdlib `zlib` on the same interpreter. Run with:
+
+```sh
+./result-test/bin/python benchmarks/bench_zlib.py
+```
+
+Sample numbers from Darwin arm64 / CPython 3.16.0a0 (median of N iterations
+per upstream's schedule; sub-millisecond rows are noisy):
+
+| Operation | Size | CPython `zlib` | `zlib_py` | Speedup |
+|---|---|---:|---:|---:|
+| decompress | 1 MB (L6) | 464 µs | 91 µs | **5.1× faster** |
+| decompress | 10 MB (L6) | 5.24 ms | 868 µs | **6.0× faster** |
+| stream compress | 1 MB (L6) | 1.52 ms | 292 µs | **5.2× faster** |
+| stream compress | 10 MB (L6) | 15.42 ms | 2.77 ms | **5.6× faster** |
+| stream decompress | 1 MB (L6) | 469 µs | 127 µs | **3.7× faster** |
+| compress | 10 MB (L9) | 14.82 ms | 8.12 ms | **1.8× faster** |
+| adler32 | 1 MB | 273 µs | 28 µs | **9.7× faster** |
+| adler32 | 10 MB | 2.77 ms | 281 µs | **9.9× faster** |
+| crc32 | 1 MB | 34 µs | 99 µs | 2.9× slower |
+| crc32 | 10 MB | 343 µs | 1.00 ms | 2.9× slower |
+| compress binary | 1 MB (L6) | 14.63 ms | 12.03 ms | 1.2× faster |
+
+`crc32` regresses on payloads ≥64 KB because CPython's implementation uses
+Intel CRC32 intrinsics that `zlib-rs` 0.6.3 doesn't hit on aarch64-darwin.
+
+Output bytes match stdlib exactly at level 9 and diverge at intermediate
+levels — engine-level property of `zlib-rs`, documented in `THIRD_PARTY.md`.
+
 ## Rust for CPython — links
 
 - [Official GitHub org](https://github.com/Rust-for-CPython)
@@ -43,8 +75,10 @@ This uses whatever CPython + pyo3 your environment resolves (no grantees of work
 
 ## Acknowledgements
 
-Prior art and inspiration: [`farhaanaliii/zlib-rs-python`](https://github.com/farhaanaliii/zlib-rs-python) — a separate pyo3 binding to `zlib-rs` with a broader stdlib-`zlib`-compatible surface (`compressobj`, `decompressobj`, checksums). If you want a more complete drop-in replacement today, look there.
+Prior art and inspiration:
+[`farhaanaliii/zlib-rs-python`](https://github.com/farhaanaliii/zlib-rs-python)
+a separate pyo3 binding to `zlib-rs`.
 
 ## License
 
-MIT — see [LICENSE](./LICENSE).
+[MIT](./LICENSE)
diff --git a/THIRD_PARTY.md b/THIRD_PARTY.md
@@ -0,0 +1,44 @@
+# Third-party attributions
+
+## farhaanaliii/zlib-rs-python
+
+The pyo3 bindings in `src/lib.rs` are adapted from
+[farhaanaliii/zlib-rs-python](https://github.com/farhaanaliii/zlib-rs-python),
+an earlier pyo3 port of the [`zlib-rs`](https://crates.io/crates/zlib-rs)
+crate. We use the algorithmic core (zlib-rs API call patterns, buffer
+sizing, streaming loop shapes) as a starting point and rewrite the
+Python-facing surface to match CPython's spec at the rev we target
+(`5775aa8e295102156de14fd1ba284722c6ede95a`, 3.16-alpha).
+
+The reference port deviates from the stdlib `zlib` spec in several
+places. The corrections we apply when porting are:
+
+| # | Area | Reference behavior | Our behavior (matches CPython spec) |
+|---|------|---|---|
+| 1 | Buffer type | `&[u8]` (bytes-only) | `PyBuffer<u8>` — accepts any object supporting the buffer protocol |
+| 2 | `compress` signature | `(data, level=-1)` | `(data, level=Z_DEFAULT_COMPRESSION, wbits=MAX_WBITS, /)` |
+| 3 | Positional-only args | Keyword-allowed | All public functions positional-only |
+| 4 | `compressobj` kwarg | `mem_level` | `memLevel` (matches CPython's AC clinic name) |
+| 5 | `compressobj` memLevel/strategy | Silently ignored | Currently ignored with a TODO; `libz-rs-sys` follow-up for full coverage |
+| 6 | `wbits` validation | Silently clamps invalid values | Errors for out-of-range wbits |
+| 7 | `decompress` buffer growth | Starts at `bufsize.max(data.len()*4)`, hard 256 MB cap | Spec: starts at `bufsize`, doubles on `BufError`, no fixed cap |
+| 8 | `Compress.flush(Z_NO_FLUSH)` | Loops calling `compress` | Returns empty bytes immediately (spec no-op) |
+| 9 | `Decompress.flush(length<=0)` | Coerces with `length.max(4096)` | Raises `ValueError` |
+| 10 | `decompressobj` `zdict` default | `None` | `b''` (matches CPython introspection) |
+| 11 | `Compress.copy` / `__copy__` / `__deepcopy__` | Not implemented | Implemented (separate slice, may require `libz-rs-sys`) |
+| 12 | `needs_input` on Decompress | Not exposed | Exposed (CPython HEAD exposes unconditionally) |
+| 13 | Non-spec attrs | Adds `total_in`, `total_out`, `__repr__` on Compress/Decompress | Omitted — not in stdlib |
+| 14 | `Z_DEFLATED` constant | Defined | Omitted — stdlib has `DEFLATED` only |
+| 15 | `error` exception | Imported from stdlib `zlib` | Defined in our module |
+| 16 | `ZLIB_VERSION` | Hardcoded `"1.2.11"` | `"1.3.1.zlib-rs-0.6.3"` (honest about the underlying engine) |
+| 17 | gzip streaming | n/a (reference omits gzip support entirely) | `decompressobj()` and `_ZlibDecompressor` reject gzip wbits (24..=31) and auto-detect (40..=47) with an honest error; zlib-rs 0.6.3's stable `Inflate::new` only does zlib/raw. Use one-shot `decompress()` for gzip — it routes through `decompress_slice` which accepts the full `InflateConfig`. |
+
+See `CONVERSION.md` for the full mapping from `zlibmodule.c` to
+`zlib-rs`. License compatibility for the adaptation is recorded in the
+project `LICENSE` file.
+
+## zlib-rs
+
+The underlying engine is [`zlib-rs`](https://crates.io/crates/zlib-rs)
+(`0.6.3`), a pure-Rust reimplementation of zlib. Licensed under
+Zlib/Apache-2.0/MIT (tri-license); see the crate for details.