Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
2 | <html> | |
3 | <head> | |
4 | <link rel="STYLESHEET" href="lib.css" type='text/css' /> | |
5 | <link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" /> | |
6 | <link rel='start' href='../index.html' title='Python Documentation Index' /> | |
7 | <link rel="first" href="lib.html" title='Python Library Reference' /> | |
8 | <link rel='contents' href='contents.html' title="Contents" /> | |
9 | <link rel='index' href='genindex.html' title='Index' /> | |
10 | <link rel='last' href='about.html' title='About this document...' /> | |
11 | <link rel='help' href='about.html' title='About this document...' /> | |
12 | <link rel="next" href="module-gzip.html" /> | |
13 | <link rel="prev" href="module-dumbdbm.html" /> | |
14 | <link rel="parent" href="someos.html" /> | |
15 | <link rel="next" href="module-gzip.html" /> | |
16 | <meta name='aesop' content='information' /> | |
17 | <title>7.15 zlib -- Compression compatible with gzip</title> | |
18 | </head> | |
19 | <body> | |
20 | <DIV CLASS="navigation"> | |
21 | <div id='top-navigation-panel' xml:id='top-navigation-panel'> | |
22 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
23 | <tr> | |
24 | <td class='online-navigation'><a rel="prev" title="7.14.1 Dumbdbm Objects" | |
25 | href="dumbdbm-objects.html"><img src='../icons/previous.png' | |
26 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
27 | <td class='online-navigation'><a rel="parent" title="7. Optional Operating System" | |
28 | href="someos.html"><img src='../icons/up.png' | |
29 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
30 | <td class='online-navigation'><a rel="next" title="7.16 gzip " | |
31 | href="module-gzip.html"><img src='../icons/next.png' | |
32 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
33 | <td align="center" width="100%">Python Library Reference</td> | |
34 | <td class='online-navigation'><a rel="contents" title="Table of Contents" | |
35 | href="contents.html"><img src='../icons/contents.png' | |
36 | border='0' height='32' alt='Contents' width='32' /></A></td> | |
37 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' | |
38 | border='0' height='32' alt='Module Index' width='32' /></a></td> | |
39 | <td class='online-navigation'><a rel="index" title="Index" | |
40 | href="genindex.html"><img src='../icons/index.png' | |
41 | border='0' height='32' alt='Index' width='32' /></A></td> | |
42 | </tr></table> | |
43 | <div class='online-navigation'> | |
44 | <b class="navlabel">Previous:</b> | |
45 | <a class="sectref" rel="prev" href="dumbdbm-objects.html">7.14.1 Dumbdbm Objects</A> | |
46 | <b class="navlabel">Up:</b> | |
47 | <a class="sectref" rel="parent" href="someos.html">7. Optional Operating System</A> | |
48 | <b class="navlabel">Next:</b> | |
49 | <a class="sectref" rel="next" href="module-gzip.html">7.16 gzip </A> | |
50 | </div> | |
51 | <hr /></div> | |
52 | </DIV> | |
53 | <!--End of Navigation Panel--> | |
54 | ||
55 | <H1><A NAME="SECTION0091500000000000000000"> | |
56 | 7.15 <tt class="module">zlib</tt> -- | |
57 | Compression compatible with <b class="program">gzip</b></A> | |
58 | </H1> | |
59 | ||
60 | <P> | |
61 | <A NAME="module-zlib"></A> | |
62 | ||
63 | <P> | |
64 | For applications that require data compression, the functions in this | |
65 | module allow compression and decompression, using the zlib library. | |
66 | The zlib library has its own home page at <a class="url" href="http://www.gzip.org/zlib/">http://www.gzip.org/zlib/</a>. | |
67 | There are known incompatibilities between the Python module and | |
68 | versions of the zlib library earlier than 1.1.3; 1.1.3 has a security | |
69 | vulnerability, so we recommend using 1.1.4 or later. | |
70 | ||
71 | <P> | |
72 | The available exception and functions in this module are: | |
73 | ||
74 | <P> | |
75 | <dl><dt><b><span class="typelabel">exception</span> <tt id='l2h-2815' xml:id='l2h-2815' class="exception">error</tt></b></dt> | |
76 | <dd> | |
77 | Exception raised on compression and decompression errors. | |
78 | </dd></dl> | |
79 | ||
80 | <P> | |
81 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
82 | <td><nobr><b><tt id='l2h-2816' xml:id='l2h-2816' class="function">adler32</tt></b>(</nobr></td> | |
83 | <td><var>string</var><big>[</big><var>, value</var><big>]</big><var></var>)</td></tr></table></dt> | |
84 | <dd> | |
85 | Computes a Adler-32 checksum of <var>string</var>. (An Adler-32 | |
86 | checksum is almost as reliable as a CRC32 but can be computed much | |
87 | more quickly.) If <var>value</var> is present, it is used as the | |
88 | starting value of the checksum; otherwise, a fixed default value is | |
89 | used. This allows computing a running checksum over the | |
90 | concatenation of several input strings. The algorithm is not | |
91 | cryptographically strong, and should not be used for | |
92 | authentication or digital signatures. Since the algorithm is | |
93 | designed for use as a checksum algorithm, it is not suitable for | |
94 | use as a general hash algorithm. | |
95 | </dl> | |
96 | ||
97 | <P> | |
98 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
99 | <td><nobr><b><tt id='l2h-2817' xml:id='l2h-2817' class="function">compress</tt></b>(</nobr></td> | |
100 | <td><var>string</var><big>[</big><var>, level</var><big>]</big><var></var>)</td></tr></table></dt> | |
101 | <dd> | |
102 | Compresses the data in <var>string</var>, returning a string contained | |
103 | compressed data. <var>level</var> is an integer from <code>1</code> to | |
104 | <code>9</code> controlling the level of compression; <code>1</code> is fastest | |
105 | and produces the least compression, <code>9</code> is slowest and produces | |
106 | the most. The default value is <code>6</code>. Raises the | |
107 | <tt class="exception">error</tt> exception if any error occurs. | |
108 | </dl> | |
109 | ||
110 | <P> | |
111 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
112 | <td><nobr><b><tt id='l2h-2818' xml:id='l2h-2818' class="function">compressobj</tt></b>(</nobr></td> | |
113 | <td><var></var><big>[</big><var>level</var><big>]</big><var></var>)</td></tr></table></dt> | |
114 | <dd> | |
115 | Returns a compression object, to be used for compressing data streams | |
116 | that won't fit into memory at once. <var>level</var> is an integer from | |
117 | <code>1</code> to <code>9</code> controlling the level of compression; <code>1</code> is | |
118 | fastest and produces the least compression, <code>9</code> is slowest and | |
119 | produces the most. The default value is <code>6</code>. | |
120 | </dl> | |
121 | ||
122 | <P> | |
123 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
124 | <td><nobr><b><tt id='l2h-2819' xml:id='l2h-2819' class="function">crc32</tt></b>(</nobr></td> | |
125 | <td><var>string</var><big>[</big><var>, value</var><big>]</big><var></var>)</td></tr></table></dt> | |
126 | <dd> | |
127 | Computes a CRC (Cyclic Redundancy Check)<a id='l2h-2828' xml:id='l2h-2828'></a> | |
128 | checksum of <var>string</var>. If | |
129 | <var>value</var> is present, it is used as the starting value of the | |
130 | checksum; otherwise, a fixed default value is used. This allows | |
131 | computing a running checksum over the concatenation of several | |
132 | input strings. The algorithm is not cryptographically strong, and | |
133 | should not be used for authentication or digital signatures. Since | |
134 | the algorithm is designed for use as a checksum algorithm, it is not | |
135 | suitable for use as a general hash algorithm. | |
136 | </dl> | |
137 | ||
138 | <P> | |
139 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
140 | <td><nobr><b><tt id='l2h-2820' xml:id='l2h-2820' class="function">decompress</tt></b>(</nobr></td> | |
141 | <td><var>string</var><big>[</big><var>, wbits</var><big>[</big><var>, bufsize</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt> | |
142 | <dd> | |
143 | Decompresses the data in <var>string</var>, returning a string containing | |
144 | the uncompressed data. The <var>wbits</var> parameter controls the size of | |
145 | the window buffer. If <var>bufsize</var> is given, it is used as the | |
146 | initial size of the output buffer. Raises the <tt class="exception">error</tt> | |
147 | exception if any error occurs. | |
148 | ||
149 | <P> | |
150 | The absolute value of <var>wbits</var> is the base two logarithm of the | |
151 | size of the history buffer (the ``window size'') used when compressing | |
152 | data. Its absolute value should be between 8 and 15 for the most | |
153 | recent versions of the zlib library, larger values resulting in better | |
154 | compression at the expense of greater memory usage. The default value | |
155 | is 15. When <var>wbits</var> is negative, the standard | |
156 | <b class="program">gzip</b> header is suppressed; this is an undocumented feature | |
157 | of the zlib library, used for compatibility with <b class="program">unzip</b>'s | |
158 | compression file format. | |
159 | ||
160 | <P> | |
161 | <var>bufsize</var> is the initial size of the buffer used to hold | |
162 | decompressed data. If more space is required, the buffer size will be | |
163 | increased as needed, so you don't have to get this value exactly | |
164 | right; tuning it will only save a few calls to <tt class="cfunction">malloc()</tt>. The | |
165 | default size is 16384. | |
166 | ||
167 | <P> | |
168 | </dl> | |
169 | ||
170 | <P> | |
171 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
172 | <td><nobr><b><tt id='l2h-2821' xml:id='l2h-2821' class="function">decompressobj</tt></b>(</nobr></td> | |
173 | <td><var></var><big>[</big><var>wbits</var><big>]</big><var></var>)</td></tr></table></dt> | |
174 | <dd> | |
175 | Returns a decompression object, to be used for decompressing data | |
176 | streams that won't fit into memory at once. The <var>wbits</var> | |
177 | parameter controls the size of the window buffer. | |
178 | </dl> | |
179 | ||
180 | <P> | |
181 | Compression objects support the following methods: | |
182 | ||
183 | <P> | |
184 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
185 | <td><nobr><b><tt id='l2h-2822' xml:id='l2h-2822' class="method">compress</tt></b>(</nobr></td> | |
186 | <td><var>string</var>)</td></tr></table></dt> | |
187 | <dd> | |
188 | Compress <var>string</var>, returning a string containing compressed data | |
189 | for at least part of the data in <var>string</var>. This data should be | |
190 | concatenated to the output produced by any preceding calls to the | |
191 | <tt class="method">compress()</tt> method. Some input may be kept in internal buffers | |
192 | for later processing. | |
193 | </dl> | |
194 | ||
195 | <P> | |
196 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
197 | <td><nobr><b><tt id='l2h-2823' xml:id='l2h-2823' class="method">flush</tt></b>(</nobr></td> | |
198 | <td><var></var><big>[</big><var>mode</var><big>]</big><var></var>)</td></tr></table></dt> | |
199 | <dd> | |
200 | All pending input is processed, and a string containing the remaining | |
201 | compressed output is returned. <var>mode</var> can be selected from the | |
202 | constants <tt class="constant">Z_SYNC_FLUSH</tt>, <tt class="constant">Z_FULL_FLUSH</tt>, or | |
203 | <tt class="constant">Z_FINISH</tt>, defaulting to <tt class="constant">Z_FINISH</tt>. <tt class="constant">Z_SYNC_FLUSH</tt> and | |
204 | <tt class="constant">Z_FULL_FLUSH</tt> allow compressing further strings of data and | |
205 | are used to allow partial error recovery on decompression, while | |
206 | <tt class="constant">Z_FINISH</tt> finishes the compressed stream and | |
207 | prevents compressing any more data. After calling | |
208 | <tt class="method">flush()</tt> with <var>mode</var> set to <tt class="constant">Z_FINISH</tt>, the | |
209 | <tt class="method">compress()</tt> method cannot be called again; the only realistic | |
210 | action is to delete the object. | |
211 | </dl> | |
212 | ||
213 | <P> | |
214 | Decompression objects support the following methods, and two attributes: | |
215 | ||
216 | <P> | |
217 | <dl><dt><b><tt id='l2h-2824' xml:id='l2h-2824' class="member">unused_data</tt></b></dt> | |
218 | <dd> | |
219 | A string which contains any bytes past the end of the compressed data. | |
220 | That is, this remains <code>""</code> until the last byte that contains | |
221 | compression data is available. If the whole string turned out to | |
222 | contain compressed data, this is <code>""</code>, the empty string. | |
223 | ||
224 | <P> | |
225 | The only way to determine where a string of compressed data ends is by | |
226 | actually decompressing it. This means that when compressed data is | |
227 | contained part of a larger file, you can only find the end of it by | |
228 | reading data and feeding it followed by some non-empty string into a | |
229 | decompression object's <tt class="method">decompress</tt> method until the | |
230 | <tt class="member">unused_data</tt> attribute is no longer the empty string. | |
231 | </dl> | |
232 | ||
233 | <P> | |
234 | <dl><dt><b><tt id='l2h-2825' xml:id='l2h-2825' class="member">unconsumed_tail</tt></b></dt> | |
235 | <dd> | |
236 | A string that contains any data that was not consumed by the last | |
237 | <tt class="method">decompress</tt> call because it exceeded the limit for the | |
238 | uncompressed data buffer. This data has not yet been seen by the zlib | |
239 | machinery, so you must feed it (possibly with further data | |
240 | concatenated to it) back to a subsequent <tt class="method">decompress</tt> method | |
241 | call in order to get correct output. | |
242 | </dl> | |
243 | ||
244 | <P> | |
245 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
246 | <td><nobr><b><tt id='l2h-2826' xml:id='l2h-2826' class="method">decompress</tt></b>(</nobr></td> | |
247 | <td><var>string</var><big>[</big><var>, max_length</var><big>]</big><var></var>)</td></tr></table></dt> | |
248 | <dd> | |
249 | Decompress <var>string</var>, returning a string containing the | |
250 | uncompressed data corresponding to at least part of the data in | |
251 | <var>string</var>. This data should be concatenated to the output produced | |
252 | by any preceding calls to the | |
253 | <tt class="method">decompress()</tt> method. Some of the input data may be preserved | |
254 | in internal buffers for later processing. | |
255 | ||
256 | <P> | |
257 | If the optional parameter <var>max_length</var> is supplied then the return value | |
258 | will be no longer than <var>max_length</var>. This may mean that not all of the | |
259 | compressed input can be processed; and unconsumed data will be stored | |
260 | in the attribute <tt class="member">unconsumed_tail</tt>. This string must be passed | |
261 | to a subsequent call to <tt class="method">decompress()</tt> if decompression is to | |
262 | continue. If <var>max_length</var> is not supplied then the whole input is | |
263 | decompressed, and <tt class="member">unconsumed_tail</tt> is an empty string. | |
264 | </dl> | |
265 | ||
266 | <P> | |
267 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
268 | <td><nobr><b><tt id='l2h-2827' xml:id='l2h-2827' class="method">flush</tt></b>(</nobr></td> | |
269 | <td><var></var>)</td></tr></table></dt> | |
270 | <dd> | |
271 | All pending input is processed, and a string containing the remaining | |
272 | uncompressed output is returned. After calling <tt class="method">flush()</tt>, the | |
273 | <tt class="method">decompress()</tt> method cannot be called again; the only realistic | |
274 | action is to delete the object. | |
275 | </dl> | |
276 | ||
277 | <P> | |
278 | <div class="seealso"> | |
279 | <p class="heading">See Also:</p> | |
280 | ||
281 | <dl compact="compact" class="seemodule"> | |
282 | <dt>Module <b><tt class="module"><a href="module-gzip.html">gzip</a></tt>:</b> | |
283 | <dd>Reading and writing <b class="program">gzip</b>-format files. | |
284 | </dl> | |
285 | <dl compact="compact" class="seeurl"> | |
286 | <dt><a href="http://www.gzip.org/zlib/" | |
287 | class="url">http://www.gzip.org/zlib/</a></dt> | |
288 | <dd>The zlib library home page.</dd> | |
289 | </dl> | |
290 | </div> | |
291 | ||
292 | <DIV CLASS="navigation"> | |
293 | <div class='online-navigation'> | |
294 | <p></p><hr /> | |
295 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
296 | <tr> | |
297 | <td class='online-navigation'><a rel="prev" title="7.14.1 Dumbdbm Objects" | |
298 | href="dumbdbm-objects.html"><img src='../icons/previous.png' | |
299 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
300 | <td class='online-navigation'><a rel="parent" title="7. Optional Operating System" | |
301 | href="someos.html"><img src='../icons/up.png' | |
302 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
303 | <td class='online-navigation'><a rel="next" title="7.16 gzip " | |
304 | href="module-gzip.html"><img src='../icons/next.png' | |
305 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
306 | <td align="center" width="100%">Python Library Reference</td> | |
307 | <td class='online-navigation'><a rel="contents" title="Table of Contents" | |
308 | href="contents.html"><img src='../icons/contents.png' | |
309 | border='0' height='32' alt='Contents' width='32' /></A></td> | |
310 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' | |
311 | border='0' height='32' alt='Module Index' width='32' /></a></td> | |
312 | <td class='online-navigation'><a rel="index" title="Index" | |
313 | href="genindex.html"><img src='../icons/index.png' | |
314 | border='0' height='32' alt='Index' width='32' /></A></td> | |
315 | </tr></table> | |
316 | <div class='online-navigation'> | |
317 | <b class="navlabel">Previous:</b> | |
318 | <a class="sectref" rel="prev" href="dumbdbm-objects.html">7.14.1 Dumbdbm Objects</A> | |
319 | <b class="navlabel">Up:</b> | |
320 | <a class="sectref" rel="parent" href="someos.html">7. Optional Operating System</A> | |
321 | <b class="navlabel">Next:</b> | |
322 | <a class="sectref" rel="next" href="module-gzip.html">7.16 gzip </A> | |
323 | </div> | |
324 | </div> | |
325 | <hr /> | |
326 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> | |
327 | </DIV> | |
328 | <!--End of Navigation Panel--> | |
329 | <ADDRESS> | |
330 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. | |
331 | </ADDRESS> | |
332 | </BODY> | |
333 | </HTML> |