{"id":5830,"library":"zlib-state","title":"zlib-state: Low-level Zlib Interface for Decoding State Capture","description":"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.","status":"active","version":"0.1.10","language":"en","source_language":"en","source_url":"https://github.com/seanmacavaney/zlib-state","tags":["compression","zlib","gzip","state management","decompression","low-level"],"install":[{"cmd":"pip install zlib-state","lang":"bash","label":"Install with pip"}],"dependencies":[],"imports":[{"symbol":"Decompressor","correct":"from zlib_state import Decompressor"},{"symbol":"GzipStateFile","correct":"from zlib_state import GzipStateFile"},{"note":"Classes like Decompressor and GzipStateFile should be imported directly or accessed via the top-level package, not as submodules of 'zlib_state'.","wrong":"import zlib_state.Decompressor","symbol":"zlib_state","correct":"import zlib_state"}],"quickstart":{"code":"import zlib_state\nimport gzip\nimport os\n\n# Create a dummy gzipped file for demonstration\ndummy_content = b\"Line 1\\nLine 2\\nLine 3 (State Capture Point)\\nLine 4\\n\" * 50\nwith gzip.open(\"test_data.txt.gz\", \"wb\") as f:\n    f.write(dummy_content)\n\nTARGET_LINE = 100\nstate_to_resume = None\nposition_to_resume = 0\n\ntry:\n    # Use GzipStateFile to capture state at a specific point\n    with zlib_state.GzipStateFile('test_data.txt.gz', keep_last_state=True) as f:\n        for i, line in enumerate(f):\n            if i == TARGET_LINE:\n                state_to_resume = f.last_state\n                position_to_resume = f.last_state_pos\n                print(f\"Captured state at line {i+1}, byte pos {position_to_resume}\")\n                break\n\n    if state_to_resume and position_to_resume:\n        print(f\"\\nResuming decompression from line {TARGET_LINE+1}...\")\n        with zlib_state.GzipStateFile('test_data.txt.gz') as f_resume:\n            f_resume.zseek(position_to_resume, state_to_resume)\n            remainder = f_resume.read(50) # Read a small portion after resuming\n            print(f\"Decompressed remainder (first 50 bytes): {remainder.decode('utf-8').strip()}...\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\nfinally:\n    # Clean up the dummy file\n    if os.path.exists(\"test_data.txt.gz\"):\n        os.remove(\"test_data.txt.gz\")\n","lang":"python","description":"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."},"warnings":[{"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.","message":"The `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).","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"While `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.","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"The 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.","severity":"breaking","affected_versions":"<0.1.6 (for Python 3.12 support), <0.1.10 (for Python 3.13 support)"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}