Doc/library/zlib.rst

   1
   2 :mod:`zlib` --- Compression compatible with :program:`gzip`
   3 ===========================================================
   4
   5 .. module:: zlib
   6    :synopsis: Low-level interface to compression and decompression routines compatible with
   7               gzip.
   8
   9
  10 For applications that require data compression, the functions in this module
  11 allow compression and decompression, using the zlib library. The zlib library
  12 has its own home page at http://www.zlib.net.   There are known
  13 incompatibilities between the Python module and versions of the zlib library
  14 earlier than 1.1.3; 1.1.3 has a security vulnerability, so we recommend using
  15 1.1.4 or later.
  16
  17 zlib's functions have many options and often need to be used in a particular
  18 order.  This documentation doesn't attempt to cover all of the permutations;
  19 consult the zlib manual at http://www.zlib.net/manual.html for authoritative
  20 information.
  21
  22 For reading and writing ``.gz`` files see the :mod:`gzip` module. For
  23 other archive formats, see the :mod:`bz2`, :mod:`zipfile`, and
  24 :mod:`tarfile` modules.
  25
  26 The available exception and functions in this module are:
  27
  28
  29 .. exception:: error
  30
  31    Exception raised on compression and decompression errors.
  32
  33
  34 .. function:: adler32(string[, value])
  35
  36    Computes a Adler-32 checksum of *string*.  (An Adler-32 checksum is almost as
  37    reliable as a CRC32 but can be computed much more quickly.)  If *value* is
  38    present, it is used as the starting value of the checksum; otherwise, a fixed
  39    default value is used.  This allows computing a running checksum over the
  40    concatenation of several input strings.  The algorithm is not cryptographically
  41    strong, and should not be used for authentication or digital signatures.  Since
  42    the algorithm is designed for use as a checksum algorithm, it is not suitable
  43    for use as a general hash algorithm.
  44
  45    This function always returns an integer object.
  46
  47 .. versionchanged:: 2.6
  48    For consistent cross-platform behavior we always return a signed integer.
  49    ie: Results in the (2**31)...(2**32-1) range will be negative.
  50
  51
  52 .. function:: compress(string[, level])
  53
  54    Compresses the data in *string*, returning a string contained compressed data.
  55    *level* is an integer from ``1`` to ``9`` controlling the level of compression;
  56    ``1`` is fastest and produces the least compression, ``9`` is slowest and
  57    produces the most.  The default value is ``6``.  Raises the :exc:`error`
  58    exception if any error occurs.
  59
  60
  61 .. function:: compressobj([level])
  62
  63    Returns a compression object, to be used for compressing data streams that won't
  64    fit into memory at once.  *level* is an integer from ``1`` to ``9`` controlling
  65    the level of compression; ``1`` is fastest and produces the least compression,
  66    ``9`` is slowest and produces the most.  The default value is ``6``.
  67
  68
  69 .. function:: crc32(string[, value])
  70
  71    .. index::
  72       single: Cyclic Redundancy Check
  73       single: checksum; Cyclic Redundancy Check
  74
  75    Computes a CRC (Cyclic Redundancy Check)  checksum of *string*. If *value* is
  76    present, it is used as the starting value of the checksum; otherwise, a fixed
  77    default value is used.  This allows computing a running checksum over the
  78    concatenation of several input strings.  The algorithm is not cryptographically
  79    strong, and should not be used for authentication or digital signatures.  Since
  80    the algorithm is designed for use as a checksum algorithm, it is not suitable
  81    for use as a general hash algorithm.
  82
  83    This function always returns an integer object.
  84
  85 .. versionchanged:: 2.6
  86    For consistent cross-platform behavior we always return a signed integer.
  87    ie: Results in the (2**31)...(2**32-1) range will be negative.
  88
  89
  90 .. function:: decompress(string[, wbits[, bufsize]])
  91
  92    Decompresses the data in *string*, returning a string containing the
  93    uncompressed data.  The *wbits* parameter controls the size of the window
  94    buffer.  If *bufsize* is given, it is used as the initial size of the output
  95    buffer.  Raises the :exc:`error` exception if any error occurs.
  96
  97    The absolute value of *wbits* is the base two logarithm of the size of the
  98    history buffer (the "window size") used when compressing data.  Its absolute
  99    value should be between 8 and 15 for the most recent versions of the zlib
 100    library, larger values resulting in better compression at the expense of greater
 101    memory usage.  The default value is 15.  When *wbits* is negative, the standard
 102    :program:`gzip` header is suppressed; this is an undocumented feature of the
 103    zlib library, used for compatibility with :program:`unzip`'s compression file
 104    format.
 105
 106    *bufsize* is the initial size of the buffer used to hold decompressed data.  If
 107    more space is required, the buffer size will be increased as needed, so you
 108    don't have to get this value exactly right; tuning it will only save a few calls
 109    to :cfunc:`malloc`.  The default size is 16384.
 110
 111
 112 .. function:: decompressobj([wbits])
 113
 114    Returns a decompression object, to be used for decompressing data streams that
 115    won't fit into memory at once.  The *wbits* parameter controls the size of the
 116    window buffer.
 117
 118 Compression objects support the following methods:
 119
 120
 121 .. method:: Compress.compress(string)
 122
 123    Compress *string*, returning a string containing compressed data for at least
 124    part of the data in *string*.  This data should be concatenated to the output
 125    produced by any preceding calls to the :meth:`compress` method.  Some input may
 126    be kept in internal buffers for later processing.
 127
 128
 129 .. method:: Compress.flush([mode])
 130
 131    All pending input is processed, and a string containing the remaining compressed
 132    output is returned.  *mode* can be selected from the constants
 133    :const:`Z_SYNC_FLUSH`,  :const:`Z_FULL_FLUSH`,  or  :const:`Z_FINISH`,
 134    defaulting to :const:`Z_FINISH`.  :const:`Z_SYNC_FLUSH` and
 135    :const:`Z_FULL_FLUSH` allow compressing further strings of data, while
 136    :const:`Z_FINISH` finishes the compressed stream and  prevents compressing any
 137    more data.  After calling :meth:`flush` with *mode* set to :const:`Z_FINISH`,
 138    the :meth:`compress` method cannot be called again; the only realistic action is
 139    to delete the object.
 140
 141
 142 .. method:: Compress.copy()
 143
 144    Returns a copy of the compression object.  This can be used to efficiently
 145    compress a set of data that share a common initial prefix.
 146
 147    .. versionadded:: 2.5
 148
 149 Decompression objects support the following methods, and two attributes:
 150
 151
 152 .. attribute:: Decompress.unused_data
 153
 154    A string which contains any bytes past the end of the compressed data. That is,
 155    this remains ``""`` until the last byte that contains compression data is
 156    available.  If the whole string turned out to contain compressed data, this is
 157    ``""``, the empty string.
 158
 159    The only way to determine where a string of compressed data ends is by actually
 160    decompressing it.  This means that when compressed data is contained part of a
 161    larger file, you can only find the end of it by reading data and feeding it
 162    followed by some non-empty string into a decompression object's
 163    :meth:`decompress` method until the :attr:`unused_data` attribute is no longer
 164    the empty string.
 165
 166
 167 .. attribute:: Decompress.unconsumed_tail
 168
 169    A string that contains any data that was not consumed by the last
 170    :meth:`decompress` call because it exceeded the limit for the uncompressed data
 171    buffer.  This data has not yet been seen by the zlib machinery, so you must feed
 172    it (possibly with further data concatenated to it) back to a subsequent
 173    :meth:`decompress` method call in order to get correct output.
 174
 175
 176 .. method:: Decompress.decompress(string[, max_length])
 177
 178    Decompress *string*, returning a string containing the uncompressed data
 179    corresponding to at least part of the data in *string*.  This data should be
 180    concatenated to the output produced by any preceding calls to the
 181    :meth:`decompress` method.  Some of the input data may be preserved in internal
 182    buffers for later processing.
 183
 184    If the optional parameter *max_length* is supplied then the return value will be
 185    no longer than *max_length*. This may mean that not all of the compressed input
 186    can be processed; and unconsumed data will be stored in the attribute
 187    :attr:`unconsumed_tail`. This string must be passed to a subsequent call to
 188    :meth:`decompress` if decompression is to continue.  If *max_length* is not
 189    supplied then the whole input is decompressed, and :attr:`unconsumed_tail` is an
 190    empty string.
 191
 192
 193 .. method:: Decompress.flush([length])
 194
 195    All pending input is processed, and a string containing the remaining
 196    uncompressed output is returned.  After calling :meth:`flush`, the
 197    :meth:`decompress` method cannot be called again; the only realistic action is
 198    to delete the object.
 199
 200    The optional parameter *length* sets the initial size of the output buffer.
 201
 202
 203 .. method:: Decompress.copy()
 204
 205    Returns a copy of the decompression object.  This can be used to save the state
 206    of the decompressor midway through the data stream in order to speed up random
 207    seeks into the stream at a future point.
 208
 209    .. versionadded:: 2.5
 210
 211
 212 .. seealso::
 213
 214    Module :mod:`gzip`
 215       Reading and writing :program:`gzip`\ -format files.
 216
 217    http://www.zlib.net
 218       The zlib library home page.
 219
 220    http://www.zlib.net/manual.html
 221       The zlib manual explains  the semantics and usage of the library's many
 222       functions.
 223