|
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 |