zlib-ng Python Bindings

Warnings

• gotcha Compression level 1 in `zlib_ng` offers worse compression rates compared to the standard `zlib` module. For most other compression levels (0 or 2-9), `zlib_ng` provides better compression.
  Fix: Avoid using compression level 1 if optimal compression ratio is critical. Use other levels (e.g., default -1, or 2-9) for improved performance and usually better compression.
• gotcha The `gzip_ng.open()` function returns a `gzip_ng.GzipNGFile` object, not `gzip.GzipFile` as in the standard library. While `gzip_ng.GzipFile` exists as an alias for compatibility, be aware of the underlying type difference if performing type checks.
  Fix: If performing type checks, check for `gzip_ng.GzipNGFile` or rely on duck-typing due to API compatibility. Using `import gzip_ng as gzip` helps maintain consistent code behavior.
• gotcha Pre-built wheels for `zlib-ng` are available for common platforms (Linux, Windows, MacOS). For less common or specific system architectures, installation might require building the C `zlib-ng` library from source, which necessitates appropriate build tools (like a C compiler) on the target system.
  Fix: Ensure that your deployment environment has the necessary build tools if pre-built wheels are not available for your specific platform/architecture.
• gotcha The `gzip_ng_threaded.open()` function is designed exclusively for streaming operations. Seeking within files opened with `gzip_ng_threaded.open()` is not supported.
  Fix: For files requiring random access or seeking, use `gzip_ng.open()` instead of `gzip_ng_threaded.open()`.
• breaking Version 1.0.0 of `zlib-ng` has dropped official support for Python 3.8 and 3.9.
  Fix: Ensure your project uses Python 3.10 or newer to be compatible with `zlib-ng` version 1.0.0. The `requires_python` metadata is `>=3.9` on PyPI, but documentation clarifies 3.8/3.9 are no longer supported as of 1.0.0.

Install

• pip install zlib-ng Install with pip

Imports

• zlib_ng

  from zlib_ng import zlib_ng

• gzip_ng

  from zlib_ng import gzip_ng

• gzip_ng_threaded

  from zlib_ng import gzip_ng_threaded

  For multi-threaded streaming compression/decompression.
• zlib

  import zlib_ng as zlib

  For drop-in replacement of the standard library's 'zlib' module, it's common to import 'zlib_ng' and alias it as 'zlib'.
• gzip

  import gzip_ng as gzip

  For drop-in replacement of the standard library's 'gzip' module, it's common to import 'gzip_ng' and alias it as 'gzip'.

Quickstart

This quickstart demonstrates basic compression and decompression using the `zlib_ng` module, which mimics the standard `zlib` module's API. It compresses a byte string and then decompresses it, verifying that the original data is recovered.

from zlib_ng import zlib_ng

original_data = b'This is some data that will be compressed using zlib-ng.'

# Compress data
compressed_data = zlib_ng.compress(original_data)
print(f"Original size: {len(original_data)}")
print(f"Compressed size: {len(compressed_data)}")

# Decompress data
decompressed_data = zlib_ng.decompress(compressed_data)
print(f"Decompressed size: {len(decompressed_data)}")

assert original_data == decompressed_data
print("Data compressed and decompressed successfully!")