| |
| .. module:: zlib |
| :synopsis: Low-level interface to compression and decompression routines compatible with |
| gzip. |
| |
| |
| For applications that require data compression, the functions in this module |
| allow compression and decompression, using the zlib library. The zlib library |
n | has its own home page at `<http://www.zlib.net>`_. There are known |
n | has its own home page at http://www.zlib.net. There are known |
| incompatibilities between the Python module and versions of the zlib library |
| earlier than 1.1.3; 1.1.3 has a security vulnerability, so we recommend using |
| 1.1.4 or later. |
| |
| zlib's functions have many options and often need to be used in a particular |
| order. This documentation doesn't attempt to cover all of the permutations; |
n | consult the zlib manual at `<http://www.zlib.net/manual.html>`_ for |
n | consult the zlib manual at http://www.zlib.net/manual.html for authoritative |
| authoritative information. |
| information. |
| |
| For reading and writing ``.gz`` files see the :mod:`gzip` module. For |
| other archive formats, see the :mod:`bz2`, :mod:`zipfile`, and |
| :mod:`tarfile` modules. |
| |
| The available exception and functions in this module are: |
| |
| |
| .. exception:: error |
| |
| Exception raised on compression and decompression errors. |
| |
| |
n | .. function:: adler32(string[, value]) |
n | .. function:: adler32(data[, value]) |
| |
n | Computes a Adler-32 checksum of *string*. (An Adler-32 checksum is almost as |
n | Computes a Adler-32 checksum of *data*. (An Adler-32 checksum is almost as |
| reliable as a CRC32 but can be computed much more quickly.) If *value* is |
| present, it is used as the starting value of the checksum; otherwise, a fixed |
| default value is used. This allows computing a running checksum over the |
n | concatenation of several input strings. The algorithm is not cryptographically |
n | concatenation of several inputs. The algorithm is not cryptographically |
| strong, and should not be used for authentication or digital signatures. Since |
| the algorithm is designed for use as a checksum algorithm, it is not suitable |
| for use as a general hash algorithm. |
n | |
| This function always returns an integer object. |
| |
| .. note:: |
| To generate the same numeric value across all Python versions and |
| platforms use adler32(data) & 0xffffffff. If you are only using |
| the checksum in packed binary format this is not necessary as the |
| return value is the correct 32bit binary representation |
| regardless of sign. |
| |
| .. versionchanged:: 2.6 |
| The return value is in the range [-2**31, 2**31-1] |
| regardless of platform. In older versions the value is |
| signed on some platforms and unsigned on others. |
| |
| .. versionchanged:: 3.0 |
| The return value is unsigned and in the range [0, 2**32-1] |
| regardless of platform. |
| |
| |
| .. function:: compress(string[, level]) |
| |
| Compresses the data in *string*, returning a string contained compressed data. |
| *level* is an integer from ``1`` to ``9`` controlling the level of compression; |
| ``1`` is fastest and produces the least compression, ``9`` is slowest and |
| produces the most. The default value is ``6``. Raises the :exc:`error` |
| .. function:: compressobj([level]) |
| |
| Returns a compression object, to be used for compressing data streams that won't |
| fit into memory at once. *level* is an integer from ``1`` to ``9`` controlling |
| the level of compression; ``1`` is fastest and produces the least compression, |
| ``9`` is slowest and produces the most. The default value is ``6``. |
| |
| |
n | .. function:: crc32(string[, value]) |
n | .. function:: crc32(data[, value]) |
| |
| .. index:: |
| single: Cyclic Redundancy Check |
| single: checksum; Cyclic Redundancy Check |
| |
n | Computes a CRC (Cyclic Redundancy Check) checksum of *string*. If *value* is |
n | Computes a CRC (Cyclic Redundancy Check) checksum of *data*. If *value* is |
| present, it is used as the starting value of the checksum; otherwise, a fixed |
| default value is used. This allows computing a running checksum over the |
n | concatenation of several input strings. The algorithm is not cryptographically |
n | concatenation of several inputs. The algorithm is not cryptographically |
| strong, and should not be used for authentication or digital signatures. Since |
| the algorithm is designed for use as a checksum algorithm, it is not suitable |
| for use as a general hash algorithm. |
| |
n | .. % |
n | This function always returns an integer object. |
| |
| .. note:: |
| To generate the same numeric value across all Python versions and |
| platforms use crc32(data) & 0xffffffff. If you are only using |
| the checksum in packed binary format this is not necessary as the |
| return value is the correct 32bit binary representation |
| regardless of sign. |
| |
| .. versionchanged:: 2.6 |
| The return value is in the range [-2**31, 2**31-1] |
| regardless of platform. In older versions the value would be |
| signed on some platforms and unsigned on others. |
| |
| .. versionchanged:: 3.0 |
| The return value is unsigned and in the range [0, 2**32-1] |
| regardless of platform. |
| |
| |
| .. function:: decompress(string[, wbits[, bufsize]]) |
| |
| Decompresses the data in *string*, returning a string containing the |
| uncompressed data. The *wbits* parameter controls the size of the window |
| buffer. If *bufsize* is given, it is used as the initial size of the output |
| buffer. Raises the :exc:`error` exception if any error occurs. |
| Returns a copy of the compression object. This can be used to efficiently |
| compress a set of data that share a common initial prefix. |
| |
| .. versionadded:: 2.5 |
| |
| Decompression objects support the following methods, and two attributes: |
| |
| |
n | .. attribute:: XXX Class.unused_data |
n | .. attribute:: Decompress.unused_data |
| |
| A string which contains any bytes past the end of the compressed data. That is, |
| this remains ``""`` until the last byte that contains compression data is |
| available. If the whole string turned out to contain compressed data, this is |
| ``""``, the empty string. |
| |
| The only way to determine where a string of compressed data ends is by actually |
| decompressing it. This means that when compressed data is contained part of a |
| larger file, you can only find the end of it by reading data and feeding it |
| followed by some non-empty string into a decompression object's |
| :meth:`decompress` method until the :attr:`unused_data` attribute is no longer |
| the empty string. |
| |
| |
t | .. attribute:: XXX Class.unconsumed_tail |
t | .. attribute:: Decompress.unconsumed_tail |
| |
| A string that contains any data that was not consumed by the last |
| :meth:`decompress` call because it exceeded the limit for the uncompressed data |
| buffer. This data has not yet been seen by the zlib machinery, so you must feed |
| it (possibly with further data concatenated to it) back to a subsequent |
| :meth:`decompress` method call in order to get correct output. |
| |
| |