Registry / data / zlib-state

zlib-state

JSON →
library0.1.12pypypi✓ verified 21d ago

The zlib-state library provides a low-level Python interface to the zlib compression library, specifically enabling the capture and restoration of decompression states. This allows for advanced use cases such as resuming decompression from arbitrary points within gzip or raw deflate streams. It features `Decompressor` for byte-level control and `GzipStateFile` for file-like object interaction, and is actively maintained with support for recent Python versions up to 3.13.

pip install zlib-state
INSTALL
IMPORT
SIG · ZLIB-STATE
Z
zlib-state
datapythonv0.1.12
Install
1.6s avg
Import
Disk
16MB
Pass rate
5/ 10
Env Coverage5 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.1.12 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
build_error
glibc
py 3.103.95 runs
installs and imports cleanly · install 1.6s · import 0.000s · 18MB
16MB installed
● package 16MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Decompressor
from zlib_state import Decompressor
GzipStateFile
from zlib_state import GzipStateFile
zlib_state
import zlib_state
import zlib_state.Decompressor
Classes like Decompressor and GzipStateFile should be imported directly or accessed via the top-level package, not as submodules of 'zlib_state'.

This quickstart demonstrates how to use `zlib-state.GzipStateFile` to decompress a gzipped file, capture the decoding state at a specific line, and then resume decompression from that exact point. This is particularly useful for random access or partial processing of large compressed files. A dummy `test_data.txt.gz` file is created and cleaned up by the example.

import zlib_state import gzip import os # Create a dummy gzipped file for demonstration dummy_content = b"Line 1\nLine 2\nLine 3 (State Capture Point)\nLine 4\n" * 50 with gzip.open("test_data.txt.gz", "wb") as f: f.write(dummy_content) TARGET_LINE = 100 state_to_resume = None position_to_resume = 0 try: # Use GzipStateFile to capture state at a specific point with zlib_state.GzipStateFile('test_data.txt.gz', keep_last_state=True) as f: for i, line in enumerate(f): if i == TARGET_LINE: state_to_resume = f.last_state position_to_resume = f.last_state_pos print(f"Captured state at line {i+1}, byte pos {position_to_resume}") break if state_to_resume and position_to_resume: print(f"\nResuming decompression from line {TARGET_LINE+1}...") with zlib_state.GzipStateFile('test_data.txt.gz') as f_resume: f_resume.zseek(position_to_resume, state_to_resume) remainder = f_resume.read(50) # Read a small portion after resuming print(f"Decompressed remainder (first 50 bytes): {remainder.decode('utf-8').strip()}...") except Exception as e: print(f"An error occurred: {e}") finally: # Clean up the dummy file if os.path.exists("test_data.txt.gz"): os.remove("test_data.txt.gz")
Debug
Known issues
gotchaThe `Decompressor` class is described as 'picky and unforgiving'. Users must precisely handle input, buffer sizes, and the `wbits` parameter to avoid `zlib` errors like `Z_BUF_ERROR`, `Z_DATA_ERROR`, or `Z_STREAM_ERROR`. Incorrect parameterization, especially for `wbits`, is a common source of issues when dealing with different compression formats (raw deflate, zlib, gzip).
fix
Carefully consult the `zlib` documentation (e.g., `zlib.h` or the Python `zlib` module docs) for `wbits` values. Ensure `feed_input` and `read` calls provide sufficient and correctly sized buffers. Implement robust error handling for `zlib` exceptions.
affects: All versions
gotchaWhile `zlib-state` enables efficient iteration over gzip files and state capture, `GzipStateFile` is 'somewhat slower than python's gzip' for general, full-file decompression. It is optimized for scenarios requiring state manipulation and resuming, not necessarily for raw speed improvements in basic decompression tasks.
fix
Evaluate your specific use case. If you do not need state capture or random access, the standard library's `gzip` module might offer better performance for simple decompression.
affects: All versions
breakingThe library explicitly supports Python 3.6 and newer, with recent versions adding support for Python 3.12 and 3.13. Using `zlib-state` with older Python versions (e.g., <3.6) is not supported and will likely lead to installation failures or runtime errors due to C extension compatibility.
fix
Ensure your project's Python environment meets the minimum requirement of Python 3.6. For the latest features and compatibility, use Python 3.13 or the latest officially supported Python version by `zlib-state`.
affects: <0.1.6 (for Python 3.12 support), <0.1.10 (for Python 3.13 support)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'zlibstate'
The Python package name for the 'zlib-state' library uses an underscore (`zlib_state`) for imports, not a hyphen.
fix
Use `import zlib_state` or `from zlib_state import Decompressor` (or other classes) to correctly import the library.
zlib.error: Error -3 while decompressing data: incorrect header check
This error occurs when the input data provided to `Decompressor` or `GzipStateFile` is not a valid zlib or gzip compressed stream, or the stream is corrupted or truncated.
fix
Verify that the input bytes or file content is a properly formatted zlib or gzip compressed stream.
TypeError: a bytes-like object is required, not 'str'
A method that expects binary data (e.g., `Decompressor.decompress` or `GzipStateFile.read`) was called with a string or another non-bytes type.
fix
Encode the input data to bytes (e.g., `my_string.encode('utf-8')`) before passing it to the method.
zlib.error: Error -5 while decompressing data: bad dictionary
The state bytes provided to `Decompressor.set_state` are corrupted, invalid, or do not correspond to a valid zlib dictionary/state, preventing the decompression context from being restored.
fix
Ensure the state bytes were correctly captured from a `Decompressor` instance using `Decompressor.state` and have not been modified or corrupted before calling `set_state`.
Upgrade
Version history
0.1.12latest on PyPI · released Apr 14, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
41 hits · last 30 days
node
32
OpenAI (training)
1
Resources
zlib-state — pip install zlib-state · libregistry