diff options
Diffstat (limited to 'Doc/library/zlib.rst')
| -rw-r--r-- | Doc/library/zlib.rst | 209 |
1 files changed, 209 insertions, 0 deletions
diff --git a/Doc/library/zlib.rst b/Doc/library/zlib.rst new file mode 100644 index 0000000000..e57a1562c2 --- /dev/null +++ b/Doc/library/zlib.rst @@ -0,0 +1,209 @@ + +:mod:`zlib` --- Compression compatible with :program:`gzip` +=========================================================== + +.. 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 +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; +consult the zlib manual at http://www.zlib.net/manual.html for authoritative +information. + +The available exception and functions in this module are: + + +.. exception:: error + + Exception raised on compression and decompression errors. + + +.. function:: adler32(string[, value]) + + Computes a Adler-32 checksum of *string*. (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 + concatenation of several input strings. 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. + + +.. 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` + exception if any error occurs. + + +.. 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``. + + +.. function:: crc32(string[, value]) + + .. index:: + single: Cyclic Redundancy Check + single: checksum; Cyclic Redundancy Check + + Computes a CRC (Cyclic Redundancy Check) checksum of *string*. 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 + concatenation of several input strings. 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. + + .. % + + +.. 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. + + The absolute value of *wbits* is the base two logarithm of the size of the + history buffer (the "window size") used when compressing data. Its absolute + value should be between 8 and 15 for the most recent versions of the zlib + library, larger values resulting in better compression at the expense of greater + memory usage. The default value is 15. When *wbits* is negative, the standard + :program:`gzip` header is suppressed; this is an undocumented feature of the + zlib library, used for compatibility with :program:`unzip`'s compression file + format. + + *bufsize* is the initial size of the buffer used to hold decompressed data. If + more space is required, the buffer size will be increased as needed, so you + don't have to get this value exactly right; tuning it will only save a few calls + to :cfunc:`malloc`. The default size is 16384. + + +.. function:: decompressobj([wbits]) + + Returns a decompression object, to be used for decompressing data streams that + won't fit into memory at once. The *wbits* parameter controls the size of the + window buffer. + +Compression objects support the following methods: + + +.. method:: Compress.compress(string) + + Compress *string*, returning a string containing compressed data for at least + part of the data in *string*. This data should be concatenated to the output + produced by any preceding calls to the :meth:`compress` method. Some input may + be kept in internal buffers for later processing. + + +.. method:: Compress.flush([mode]) + + All pending input is processed, and a string containing the remaining compressed + output is returned. *mode* can be selected from the constants + :const:`Z_SYNC_FLUSH`, :const:`Z_FULL_FLUSH`, or :const:`Z_FINISH`, + defaulting to :const:`Z_FINISH`. :const:`Z_SYNC_FLUSH` and + :const:`Z_FULL_FLUSH` allow compressing further strings of data, while + :const:`Z_FINISH` finishes the compressed stream and prevents compressing any + more data. After calling :meth:`flush` with *mode* set to :const:`Z_FINISH`, + the :meth:`compress` method cannot be called again; the only realistic action is + to delete the object. + + +.. method:: Compress.copy() + + 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: + + +.. 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. + + +.. 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. + + +.. method:: Decompress.decompress(string[, max_length]) + + Decompress *string*, returning a string containing the uncompressed data + corresponding to at least part of the data in *string*. This data should be + concatenated to the output produced by any preceding calls to the + :meth:`decompress` method. Some of the input data may be preserved in internal + buffers for later processing. + + If the optional parameter *max_length* is supplied then the return value will be + no longer than *max_length*. This may mean that not all of the compressed input + can be processed; and unconsumed data will be stored in the attribute + :attr:`unconsumed_tail`. This string must be passed to a subsequent call to + :meth:`decompress` if decompression is to continue. If *max_length* is not + supplied then the whole input is decompressed, and :attr:`unconsumed_tail` is an + empty string. + + +.. method:: Decompress.flush([length]) + + All pending input is processed, and a string containing the remaining + uncompressed output is returned. After calling :meth:`flush`, the + :meth:`decompress` method cannot be called again; the only realistic action is + to delete the object. + + The optional parameter *length* sets the initial size of the output buffer. + + +.. method:: Decompress.copy() + + Returns a copy of the decompression object. This can be used to save the state + of the decompressor midway through the data stream in order to speed up random + seeks into the stream at a future point. + + .. versionadded:: 2.5 + + +.. seealso:: + + Module :mod:`gzip` + Reading and writing :program:`gzip`\ -format files. + + http://www.zlib.net + The zlib library home page. + + http://www.zlib.net/manual.html + The zlib manual explains the semantics and usage of the library's many + functions. + |