1 \section{\module{zlib
} ---
2 Compression compatible with
\program{gzip
}}
4 \declaremodule{builtin
}{zlib
}
5 \modulesynopsis{Low-level interface to compression and decompression
6 routines compatible with
\program{gzip
}.
}
9 For applications that require data compression, the functions in this
10 module allow compression and decompression, using the zlib library.
11 The zlib library has its own home page at
12 \url{http://www.gzip.org/zlib/
}. Version
1.1.3 is the
13 most recent version as of September
2000; use a later version if one
14 is available. There are known incompatibilities between the Python
15 module and earlier versions of the zlib library.
17 The available exception and functions in this module are:
19 \begin{excdesc
}{error
}
20 Exception raised on compression and decompression errors.
24 \begin{funcdesc
}{adler32
}{string
\optional{, value
}}
25 Computes a Adler-
32 checksum of
\var{string
}. (An Adler-
32
26 checksum is almost as reliable as a CRC32 but can be computed much
27 more quickly.) If
\var{value
} is present, it is used as the
28 starting value of the checksum; otherwise, a fixed default value is
29 used. This allows computing a running checksum over the
30 concatenation of several input strings. The algorithm is not
31 cryptographically strong, and should not be used for
32 authentication or digital signatures. Since the algorithm is
33 designed for use as a checksum algorithm, it is not suitable for
34 use as a general hash algorithm.
37 \begin{funcdesc
}{compress
}{string
\optional{, level
}}
38 Compresses the data in
\var{string
}, returning a string contained
39 compressed data.
\var{level
} is an integer from
\code{1} to
40 \code{9} controlling the level of compression;
\code{1} is fastest
41 and produces the least compression,
\code{9} is slowest and produces
42 the most. The default value is
\code{6}. Raises the
43 \exception{error
} exception if any error occurs.
46 \begin{funcdesc
}{compressobj
}{\optional{level
}}
47 Returns a compression object, to be used for compressing data streams
48 that won't fit into memory at once.
\var{level
} is an integer from
49 \code{1} to
\code{9} controlling the level of compression;
\code{1} is
50 fastest and produces the least compression,
\code{9} is slowest and
51 produces the most. The default value is
\code{6}.
54 \begin{funcdesc
}{crc32
}{string
\optional{, value
}}
55 Computes a CRC (Cyclic Redundancy Check)
%
56 \index{Cyclic Redundancy Check
}
57 \index{checksum!Cyclic Redundancy Check
}
58 checksum of
\var{string
}. If
59 \var{value
} is present, it is used as the starting value of the
60 checksum; otherwise, a fixed default value is used. This allows
61 computing a running checksum over the concatenation of several
62 input strings. The algorithm is not cryptographically strong, and
63 should not be used for authentication or digital signatures. Since
64 the algorithm is designed for use as a checksum algorithm, it is not
65 suitable for use as a general hash algorithm.
68 \begin{funcdesc
}{decompress
}{string
\optional{, wbits
\optional{, bufsize
}}}
69 Decompresses the data in
\var{string
}, returning a string containing
70 the uncompressed data. The
\var{wbits
} parameter controls the size of
71 the window buffer. If
\var{bufsize
} is given, it is used as the
72 initial size of the output buffer. Raises the
\exception{error
}
73 exception if any error occurs.
75 The absolute value of
\var{wbits
} is the base two logarithm of the
76 size of the history buffer (the ``window size'') used when compressing
77 data. Its absolute value should be between
8 and
15 for the most
78 recent versions of the zlib library, larger values resulting in better
79 compression at the expense of greater memory usage. The default value
80 is
15. When
\var{wbits
} is negative, the standard
81 \program{gzip
} header is suppressed; this is an undocumented feature
82 of the zlib library, used for compatibility with
\program{unzip
}'s
83 compression file format.
85 \var{bufsize
} is the initial size of the buffer used to hold
86 decompressed data. If more space is required, the buffer size will be
87 increased as needed, so you don't have to get this value exactly
88 right; tuning it will only save a few calls to
\cfunction{malloc()
}. The
89 default size is
16384.
93 \begin{funcdesc
}{decompressobj
}{\optional{wbits
}}
94 Returns a decompression object, to be used for decompressing data
95 streams that won't fit into memory at once. The
\var{wbits
}
96 parameter controls the size of the window buffer.
99 Compression objects support the following methods:
101 \begin{methoddesc
}[Compress
]{compress
}{string
}
102 Compress
\var{string
}, returning a string containing compressed data
103 for at least part of the data in
\var{string
}. This data should be
104 concatenated to the output produced by any preceding calls to the
105 \method{compress()
} method. Some input may be kept in internal buffers
106 for later processing.
109 \begin{methoddesc
}[Compress
]{flush
}{\optional{mode
}}
110 All pending input is processed, and a string containing the remaining
111 compressed output is returned.
\var{mode
} can be selected from the
112 constants
\constant{Z_SYNC_FLUSH
},
\constant{Z_FULL_FLUSH
}, or
113 \constant{Z_FINISH
}, defaulting to
\constant{Z_FINISH
}.
\constant{Z_SYNC_FLUSH
} and
114 \constant{Z_FULL_FLUSH
} allow compressing further strings of data and
115 are used to allow partial error recovery on decompression, while
116 \constant{Z_FINISH
} finishes the compressed stream and
117 prevents compressing any more data. After calling
118 \method{flush()
} with
\var{mode
} set to
\constant{Z_FINISH
}, the
119 \method{compress()
} method cannot be called again; the only realistic
120 action is to delete the object.
123 Decompression objects support the following methods, and two attributes:
125 \begin{memberdesc
}{unused_data
}
126 A string which contains any unused data from the last string fed to
127 this decompression object. If the whole string turned out to contain
128 compressed data, this is
\code{""
}, the empty string.
130 The only way to determine where a string of compressed data ends is by
131 actually decompressing it. This means that when compressed data is
132 contained part of a larger file, you can only find the end of it by
133 reading data and feeding it into a decompression object's
134 \method{decompress
} method until the
\member{unused_data
} attribute is
135 no longer the empty string.
138 \begin{memberdesc
}{unconsumed_tail
}
139 A string that contains any data that was not consumed by the last
140 \method{decompress
} call because it exceeded the limit for the
141 uncompressed data buffer.
144 \begin{methoddesc
}[Decompress
]{decompress
}{string
}{\optional{max_length
}}
145 Decompress
\var{string
}, returning a string containing the
146 uncompressed data corresponding to at least part of the data in
147 \var{string
}. This data should be concatenated to the output produced
148 by any preceding calls to the
149 \method{decompress()
} method. Some of the input data may be preserved
150 in internal buffers for later processing.
152 If the optional parameter
\var{max_length
} is supplied then the return value
153 will be no longer than
\var{max_length
}. This may mean that not all of the
154 compressed input can be processed; and unconsumed data will be stored
155 in the attribute
\member{unconsumed_tail
}. This string must be passed
156 to a subsequent call to
\method{decompress()
} if decompression is to
157 continue. If
\var{max_length
} is not supplied then the whole input is
158 decompressed, and
\member{unconsumed_tail
} is an empty string.
161 \begin{methoddesc
}[Decompress
]{flush
}{}
162 All pending input is processed, and a string containing the remaining
163 uncompressed output is returned. After calling
\method{flush()
}, the
164 \method{decompress()
} method cannot be called again; the only realistic
165 action is to delete the object.
169 \seemodule{gzip
}{Reading and writing
\program{gzip
}-format files.
}
170 \seeurl{http://www.gzip.org/zlib/
}{The zlib library home page.
}
