micropython/docs/library/zlib.rst
Jim Mussared b804443cb3 docs/library/deflate: Add docs for deflate.DeflateIO.
Also update zlib & gzip docs to describe the micropython-lib modules.

This work was funded through GitHub Sponsors.

Signed-off-by: Jim Mussared <jim.mussared@gmail.com>
2023-07-21 19:32:42 +10:00

83 lines
3.7 KiB
ReStructuredText

:mod:`zlib` -- zlib compression & decompression
===============================================
.. module:: zlib
:synopsis: zlib compression & decompression
|see_cpython_module| :mod:`python:zlib`.
This module allows compression and decompression of binary data with the
`DEFLATE algorithm <https://en.wikipedia.org/wiki/DEFLATE>`_
(commonly used in the zlib library and gzip archiver).
.. note:: Prefer to use :class:`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:**
* From MicroPython v1.21 onwards, this module may not be present by default on
all MicroPython firmware as it duplicates functionality available in
the :mod:`deflate <deflate>` module.
* A copy of this module can be installed (or frozen)
from :term:`micropython-lib` (`source <https://github.com/micropython/micropython-lib/blob/master/python-stdlib/zlib/zlib.py>`_).
See :ref:`packages` for more information. This documentation describes that module.
* Requires the built-in :mod:`deflate <deflate>` module (available since MicroPython v1.21)
* Compression support will only be available if compression support is enabled
in the built-in :mod:`deflate <deflate>` module.
Functions
---------
.. function:: decompress(data, wbits=15, /)
Decompresses *data* into a bytes object.
The *wbits* parameter works the same way as for :meth:`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 :meth:`zlib.compress`, see the :mod:`CPython documentation for zlib <python:zlib>`
for more information about the *wbits* parameter. As for :meth:`zlib.compress`,
MicroPython also supports smaller window sizes than CPython. See more
:ref:`MicroPython-specific details <deflate_wbits>` in the
:mod:`deflate <deflate>` module documentation.
If the data to be decompressed requires a larger window size, it will
fail during decompression.
.. function:: compress(data, wbits=15, /)
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 :mod:`CPython documentation for zlib <python: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 :ref:`MicroPython-specific details <deflate_wbits>`
in the :mod:`deflate <deflate>` module documentation.