zlib — zlib compression & decompression

This module allows compression and decompression of binary data with the DEFLATE algorithm (commonly used in the zlib library and gzip archiver).

Note

Prefer to use deflate.DeflateIO instead of the functions in this module as it provides a streaming interface to compression and decompression which is convenient and more memory efficient when working with reading or writing compressed data to a file, socket, or stream.

Availability:

  • This module is not included on the OpenMV Cam by default, as it duplicates functionality already provided by the deflate module.

  • A copy can be installed (or frozen into custom firmware) from micropython-lib (source). See Package management for more information. This documentation describes that module.

  • It relies on the built-in deflate module, which is present on all OpenMV Cams.

  • Compression is only available if compression is available in the built-in deflate module – that is, not on the STM32-based OpenMV Cams (see its availability note above).

Functions

zlib.decompress(data: bytes, wbits: int = 15, /) → bytes

Decompresses data into a bytes object.

The wbits parameter works the same way as for zlib.compress() with the following additional valid values:

  • 0: Automatically determine the window size from the zlib header (data must be in zlib format).

  • 35 to 47: Auto-detect either the zlib or gzip format.

As for zlib.compress(), see the CPython documentation for zlib for more information about the wbits parameter. As for zlib.compress(), MicroPython also supports smaller window sizes than CPython. See more MicroPython-specific details in the deflate module documentation.

If the data to be decompressed requires a larger window size, it will fail during decompression.

zlib.compress(data: bytes, wbits: int = 15, /) → bytes

Compresses data into a bytes object.

wbits allows you to configure the DEFLATE dictionary window size and the output format. The window size allows you to trade-off memory usage for compression level. A larger window size will allow the compressor to reference fragments further back in the input. The output formats are “raw” DEFLATE (no header/footer), zlib, and gzip, where the latter two include a header and checksum.

The low four bits of the absolute value of wbits set the base-2 logarithm of the DEFLATE dictionary window size. So for example, wbits=10, wbits=-10, and wbits=26 all set the window size to 1024 bytes. Valid window sizes are 5 to 15 inclusive (corresponding to 32 to 32k bytes).

Negative values of wbits between -5 and -15 correspond to “raw” output mode, positive values between 5 and 15 correspond to zlib output mode, and positive values between 21 and 31 correspond to gzip output mode.

See the CPython documentation for zlib for more information about the wbits parameter. Note that MicroPython allows for smaller window sizes, which is useful when memory is constrained while still achieving a reasonable level of compression. It also speeds up the compressor. See more MicroPython-specific details in the deflate module documentation.