blob: 9234c5f47a8566953a489c8fbb06cb8efc6253f2 [file] [log] [blame]
Guido van Rossumeb0f0661997-12-30 20:38:16 +00001% XXX The module has been extended (by Jeremy) but this documentation hasn't been updated yet
2
Guido van Rossum04bc9d61997-04-30 18:12:27 +00003\section{Built-in Module \sectcode{zlib}}
Guido van Rossume47da0a1997-07-17 16:34:52 +00004\label{module-zlib}
Guido van Rossum04bc9d61997-04-30 18:12:27 +00005\bimodindex{zlib}
6
7For applications that require data compression, the functions in this
Guido van Rossum412154f1997-04-30 19:39:21 +00008module allow compression and decompression, using the zlib library,
9which is based on GNU zip. The zlib library has its own home page at
Fred Drakeed797831998-01-22 16:11:18 +000010\url{http://www.cdrom.com/pub/infozip/zlib/}.
Guido van Rossumeb0f0661997-12-30 20:38:16 +000011Version 1.0.4 is the most recent version as of December, 1997; use a
Guido van Rossum412154f1997-04-30 19:39:21 +000012later version if one is available.
Guido van Rossum04bc9d61997-04-30 18:12:27 +000013
14The available functions in this module are:
15
Fred Drake19479911998-02-13 06:58:54 +000016\setindexsubitem{(in module zlib)}
Guido van Rossum04bc9d61997-04-30 18:12:27 +000017\begin{funcdesc}{adler32}{string\optional{\, value}}
18 Computes a Adler-32 checksum of \var{string}. (An Adler-32
19 checksum is almost as reliable as a CRC32 but can be computed much
20 more quickly.) If \var{value} is present, it is used as the
21 starting value of the checksum; otherwise, a fixed default value is
22 used. This allows computing a running checksum over the
23 concatenation of several input strings. The algorithm is not
24 cryptographically strong, and should not be used for
25 authentication or digital signatures.
26\end{funcdesc}
27
28\begin{funcdesc}{compress}{string\optional{\, level}}
29Compresses the data in \var{string}, returning a string contained
Fred Drakeed797831998-01-22 16:11:18 +000030compressed data. \var{level} is an integer from \code{1} to \code{9}
31controlling the level of compression; \code{1} is fastest and produces
32the least compression, \code{9} is slowest and produces the most. The
33default value is \code{6}. Raises the \exception{zlib.error}
34exception if any error occurs.
Guido van Rossum04bc9d61997-04-30 18:12:27 +000035\end{funcdesc}
36
37\begin{funcdesc}{compressobj}{\optional{level}}
Fred Drakeed797831998-01-22 16:11:18 +000038 Returns a compression object, to be used for compressing data streams
Guido van Rossum04bc9d61997-04-30 18:12:27 +000039 that won't fit into memory at once. \var{level} is an integer from
Fred Drakeed797831998-01-22 16:11:18 +000040 \code{1} to \code{9} controlling the level of compression; \code{1} is
41 fastest and produces the least compression, \code{9} is slowest and
42 produces the most. The default value is \code{6}.
Guido van Rossum04bc9d61997-04-30 18:12:27 +000043\end{funcdesc}
44
45\begin{funcdesc}{crc32}{string\optional{\, value}}
46 Computes a CRC (Cyclic Redundancy Check) sum of \var{string}. If
47 \var{value} is present, it is used as the starting value of the
48 checksum; otherwise, a fixed default value is used. This allows
49 computing a running checksum over the concatenation of several
50 input strings. The algorithm is not cryptographically strong, and
51 should not be used for authentication or digital signatures.
52\end{funcdesc}
53
54\begin{funcdesc}{decompress}{string}
55Decompresses the data in \var{string}, returning a string containing
Fred Drakeed797831998-01-22 16:11:18 +000056the uncompressed data. Raises the \exception{zlib.error} exception if any
Guido van Rossum04bc9d61997-04-30 18:12:27 +000057error occurs.
58\end{funcdesc}
59
60\begin{funcdesc}{decompressobj}{\optional{wbits}}
61Returns a compression object, to be used for decompressing data streams
Guido van Rossum412154f1997-04-30 19:39:21 +000062that won't fit into memory at once. The \var{wbits} parameter
63controls the size of the window buffer; usually this can be left
64alone.
Guido van Rossum04bc9d61997-04-30 18:12:27 +000065\end{funcdesc}
66
67Compression objects support the following methods:
68
69\begin{funcdesc}{compress}{string}
70Compress \var{string}, returning a string containing compressed data
71for at least part of the data in \var{string}. This data should be
72concatenated to the output produced by any preceding calls to the
Fred Drakeed797831998-01-22 16:11:18 +000073\method{compress()} method. Some input may be kept in internal buffers
Guido van Rossum04bc9d61997-04-30 18:12:27 +000074for later processing.
75\end{funcdesc}
76
77\begin{funcdesc}{flush}{}
78All pending input is processed, and an string containing the remaining
Fred Drakeed797831998-01-22 16:11:18 +000079compressed output is returned. After calling \method{flush()}, the
80\method{compress()} method cannot be called again; the only realistic
Guido van Rossum04bc9d61997-04-30 18:12:27 +000081action is to delete the object.
82\end{funcdesc}
83
84Decompression objects support the following methods:
85
86\begin{funcdesc}{decompress}{string}
87Decompress \var{string}, returning a string containing the
88uncompressed data corresponding to at least part of the data in
89\var{string}. This data should be concatenated to the output produced
90by any preceding calls to the
Fred Drakeed797831998-01-22 16:11:18 +000091\method{decompress()} method. Some of the input data may be preserved
Guido van Rossum412154f1997-04-30 19:39:21 +000092in internal buffers for later processing.
Guido van Rossum04bc9d61997-04-30 18:12:27 +000093\end{funcdesc}
94
95\begin{funcdesc}{flush}{}
96All pending input is processed, and a string containing the remaining
Fred Drakeed797831998-01-22 16:11:18 +000097uncompressed output is returned. After calling \method{flush()}, the
98\method{decompress()} method cannot be called again; the only realistic
Guido van Rossum04bc9d61997-04-30 18:12:27 +000099action is to delete the object.
100\end{funcdesc}
101
Guido van Rossume47da0a1997-07-17 16:34:52 +0000102\begin{seealso}
103\seemodule{gzip}{reading and writing \file{gzip}-format files}
104\end{seealso}
Guido van Rossum04bc9d61997-04-30 18:12:27 +0000105
106