\section{\module{zlib} ---         Compression compatible with \program{gzip}} \declaremodule{builtin}{zlib}\modulesynopsis{Low-level interface to compression and decompression                routines compatible with \program{gzip}.}  For applications that require data compression, the functions in thismodule allow compression and decompression, using the zlib library.The zlib library has its own home page at \url{http://www.zlib.net}.  There are known incompatibilities between the Python module andversions of the zlib library earlier than 1.1.3; 1.1.3 has a securityvulnerability, so we recommend using 1.1.4 or later. zlib's functions have many options and often need to be used in aparticular order.  This documentation doesn't attempt to cover all ofthe permutations; consult the zlib manual at\url{http://www.zlib.net/manual.html} for authoritative information. The available exception and functions in this module are: \begin{excdesc}{error}  Exception raised on compression and decompression errors.\end{excdesc}  \begin{funcdesc}{adler32}{string\optional{, value}}   Computes a Adler-32 checksum of \var{string}.  (An Adler-32   checksum is almost as reliable as a CRC32 but can be computed much   more quickly.)  If \var{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.\end{funcdesc} \begin{funcdesc}{compress}{string\optional{, level}}  Compresses the data in \var{string}, returning a string contained  compressed data.  \var{level} is an integer from \code{1} to  \code{9} controlling the level of compression; \code{1} is fastest  and produces the least compression, \code{9} is slowest and produces  the most.  The default value is \code{6}.  Raises the  \exception{error} exception if any error occurs.\end{funcdesc} \begin{funcdesc}{compressobj}{\optional{level}}  Returns a compression object, to be used for compressing data streams  that won't fit into memory at once.  \var{level} is an integer from  \code{1} to \code{9} controlling the level of compression; \code{1} is  fastest and produces the least compression, \code{9} is slowest and  produces the most.  The default value is \code{6}.\end{funcdesc} \begin{funcdesc}{crc32}{string\optional{, value}}  Computes a CRC (Cyclic Redundancy Check)%  \index{Cyclic Redundancy Check}  \index{checksum!Cyclic Redundancy Check}  checksum of \var{string}. If  \var{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.\end{funcdesc} \begin{funcdesc}{decompress}{string\optional{, wbits\optional{, bufsize}}}  Decompresses the data in \var{string}, returning a string containing  the uncompressed data.  The \var{wbits} parameter controls the size of  the window buffer.  If \var{bufsize} is given, it is used as the  initial size of the output buffer.  Raises the \exception{error}  exception if any error occurs. The absolute value of \var{wbits} is the base two logarithm of thesize of the history buffer (the ``window size'') used when compressingdata.  Its absolute value should be between 8 and 15 for the mostrecent versions of the zlib library, larger values resulting in bettercompression at the expense of greater memory usage.  The default valueis 15.  When \var{wbits} is negative, the standard\program{gzip} header is suppressed; this is an undocumented featureof the zlib library, used for compatibility with \program{unzip}'scompression file format. \var{bufsize} is the initial size of the buffer used to holddecompressed data.  If more space is required, the buffer size will beincreased as needed, so you don't have to get this value exactlyright; tuning it will only save a few calls to \cfunction{malloc()}.  Thedefault size is 16384.   \end{funcdesc} \begin{funcdesc}{decompressobj}{\optional{wbits}}  Returns a decompression object, to be used for decompressing data  streams that won't fit into memory at once.  The \var{wbits}  parameter controls the size of the window buffer.\end{funcdesc} Compression objects support the following methods: \begin{methoddesc}[Compress]{compress}{string}Compress \var{string}, returning a string containing compressed datafor at least part of the data in \var{string}.  This data should beconcatenated to the output produced by any preceding calls to the\method{compress()} method.  Some input may be kept in internal buffersfor later processing.\end{methoddesc} \begin{methoddesc}[Compress]{flush}{\optional{mode}}All pending input is processed, and a string containing the remainingcompressed output is returned.  \var{mode} can be selected from theconstants \constant{Z_SYNC_FLUSH},  \constant{Z_FULL_FLUSH},  or \constant{Z_FINISH}, defaulting to \constant{Z_FINISH}.  \constant{Z_SYNC_FLUSH} and \constant{Z_FULL_FLUSH} allow compressing further strings of data, while\constant{Z_FINISH} finishes the compressed stream and prevents compressing any more data.  After calling\method{flush()} with \var{mode} set to \constant{Z_FINISH}, the\method{compress()} method cannot be called again; the only realisticaction is to delete the object.  \end{methoddesc} \begin{methoddesc}[Compress]{copy}{}Returns a copy of the compression object.  This can be used to efficientlycompress a set of data that share a common initial prefix.\versionadded{2.5}\end{methoddesc} Decompression objects support the following methods, and two attributes: \begin{memberdesc}{unused_data}A string which contains any bytes past the end of the compressed data.That is, this remains \code{""} until the last byte that containscompression data is available.  If the whole string turned out tocontain compressed data, this is \code{""}, the empty string. The only way to determine where a string of compressed data ends is byactually decompressing it.  This means that when compressed data iscontained part of a larger file, you can only find the end of it byreading data and feeding it followed by some non-empty string into adecompression object's \method{decompress} method until the\member{unused_data} attribute is no longer the empty string.\end{memberdesc} \begin{memberdesc}{unconsumed_tail}A string that contains any data that was not consumed by the last\method{decompress} call because it exceeded the limit for theuncompressed data buffer.  This data has not yet been seen by the zlibmachinery, so you must feed it (possibly with further dataconcatenated to it) back to a subsequent \method{decompress} methodcall in order to get correct output.\end{memberdesc}  \begin{methoddesc}[Decompress]{decompress}{string\optional{, max_length}}Decompress \var{string}, returning a string containing theuncompressed data corresponding to at least part of the data in\var{string}.  This data should be concatenated to the output producedby any preceding calls to the\method{decompress()} method.  Some of the input data may be preservedin internal buffers for later processing. If the optional parameter \var{max_length} is supplied then the return valuewill be no longer than \var{max_length}. This may mean that not all of thecompressed input can be processed; and unconsumed data will be storedin the attribute \member{unconsumed_tail}. This string must be passedto a subsequent call to \method{decompress()} if decompression is tocontinue.  If \var{max_length} is not supplied then the whole input isdecompressed, and \member{unconsumed_tail} is an empty string.\end{methoddesc} \begin{methoddesc}[Decompress]{flush}{\optional{length}}All pending input is processed, and a string containing the remaininguncompressed output is returned.  After calling \method{flush()}, the\method{decompress()} method cannot be called again; the only realisticaction is to delete the object. The optional parameter \var{length} sets the initial size of theoutput buffer.\end{methoddesc} \begin{methoddesc}[Decompress]{copy}{}Returns a copy of the decompression object.  This can be used to save thestate of the decompressor midway through the data stream in order to speed uprandom seeks into the stream at a future point.\versionadded{2.5}\end{methoddesc} \begin{seealso}  \seemodule{gzip}{Reading and writing \program{gzip}-format files.}  \seeurl{http://www.zlib.net}{The zlib library home page.}  \seeurl{http://www.zlib.net/manual.html}{The zlib manual explains     the semantics and usage of the library's many functions.}\end{seealso}