Guido van Rossum | 04bc9d6 | 1997-04-30 18:12:27 +0000 | [diff] [blame] | 1 | \section{Built-in Module \sectcode{zlib}} |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame^] | 2 | \label{module-zlib} |
Guido van Rossum | 04bc9d6 | 1997-04-30 18:12:27 +0000 | [diff] [blame] | 3 | \bimodindex{zlib} |
| 4 | |
| 5 | For applications that require data compression, the functions in this |
Guido van Rossum | 412154f | 1997-04-30 19:39:21 +0000 | [diff] [blame] | 6 | module allow compression and decompression, using the zlib library, |
| 7 | which is based on GNU zip. The zlib library has its own home page at |
| 8 | \code{http://www.cdrom.com/pub/infozip/zlib/}. |
| 9 | Version 1.0.4 is the most recent version as of April 30, 1997; use a |
| 10 | later version if one is available. |
Guido van Rossum | 04bc9d6 | 1997-04-30 18:12:27 +0000 | [diff] [blame] | 11 | |
| 12 | The available functions in this module are: |
| 13 | |
| 14 | \renewcommand{\indexsubitem}{(in module zlib)} |
| 15 | \begin{funcdesc}{adler32}{string\optional{\, value}} |
| 16 | Computes a Adler-32 checksum of \var{string}. (An Adler-32 |
| 17 | checksum is almost as reliable as a CRC32 but can be computed much |
| 18 | more quickly.) If \var{value} is present, it is used as the |
| 19 | starting value of the checksum; otherwise, a fixed default value is |
| 20 | used. This allows computing a running checksum over the |
| 21 | concatenation of several input strings. The algorithm is not |
| 22 | cryptographically strong, and should not be used for |
| 23 | authentication or digital signatures. |
| 24 | \end{funcdesc} |
| 25 | |
| 26 | \begin{funcdesc}{compress}{string\optional{\, level}} |
| 27 | Compresses the data in \var{string}, returning a string contained |
| 28 | compressed data. \var{level} is an integer from 1 to 9 controlling |
| 29 | the level of compression; 1 is fastest and produces the least |
| 30 | compression, 9 is slowest and produces the most. The default value is |
Guido van Rossum | 2525bed | 1997-06-02 17:22:06 +0000 | [diff] [blame] | 31 | 6. Raises the \code{zlib.error} exception if any error occurs. |
Guido van Rossum | 04bc9d6 | 1997-04-30 18:12:27 +0000 | [diff] [blame] | 32 | \end{funcdesc} |
| 33 | |
| 34 | \begin{funcdesc}{compressobj}{\optional{level}} |
| 35 | Returns a compression object, to be used for compressing data streams |
| 36 | that won't fit into memory at once. \var{level} is an integer from |
| 37 | 1 to 9 controlling the level of compression; 1 is fastest and |
| 38 | produces the least compression, 9 is slowest and produces the most. |
| 39 | The default value is 6. |
| 40 | \end{funcdesc} |
| 41 | |
| 42 | \begin{funcdesc}{crc32}{string\optional{\, value}} |
| 43 | Computes a CRC (Cyclic Redundancy Check) sum of \var{string}. If |
| 44 | \var{value} is present, it is used as the starting value of the |
| 45 | checksum; otherwise, a fixed default value is used. This allows |
| 46 | computing a running checksum over the concatenation of several |
| 47 | input strings. The algorithm is not cryptographically strong, and |
| 48 | should not be used for authentication or digital signatures. |
| 49 | \end{funcdesc} |
| 50 | |
| 51 | \begin{funcdesc}{decompress}{string} |
| 52 | Decompresses the data in \var{string}, returning a string containing |
| 53 | the uncompressed data. Raises the \code{zlib.error} exception if any |
| 54 | error occurs. |
| 55 | \end{funcdesc} |
| 56 | |
| 57 | \begin{funcdesc}{decompressobj}{\optional{wbits}} |
| 58 | Returns a compression object, to be used for decompressing data streams |
Guido van Rossum | 412154f | 1997-04-30 19:39:21 +0000 | [diff] [blame] | 59 | that won't fit into memory at once. The \var{wbits} parameter |
| 60 | controls the size of the window buffer; usually this can be left |
| 61 | alone. |
Guido van Rossum | 04bc9d6 | 1997-04-30 18:12:27 +0000 | [diff] [blame] | 62 | \end{funcdesc} |
| 63 | |
| 64 | Compression objects support the following methods: |
| 65 | |
| 66 | \begin{funcdesc}{compress}{string} |
| 67 | Compress \var{string}, returning a string containing compressed data |
| 68 | for at least part of the data in \var{string}. This data should be |
| 69 | concatenated to the output produced by any preceding calls to the |
| 70 | \code{compress()} method. Some input may be kept in internal buffers |
| 71 | for later processing. |
| 72 | \end{funcdesc} |
| 73 | |
| 74 | \begin{funcdesc}{flush}{} |
| 75 | All pending input is processed, and an string containing the remaining |
| 76 | compressed output is returned. After calling \code{flush()}, the |
| 77 | \code{compress()} method cannot be called again; the only realistic |
| 78 | action is to delete the object. |
| 79 | \end{funcdesc} |
| 80 | |
| 81 | Decompression objects support the following methods: |
| 82 | |
| 83 | \begin{funcdesc}{decompress}{string} |
| 84 | Decompress \var{string}, returning a string containing the |
| 85 | uncompressed data corresponding to at least part of the data in |
| 86 | \var{string}. This data should be concatenated to the output produced |
| 87 | by any preceding calls to the |
Guido van Rossum | 412154f | 1997-04-30 19:39:21 +0000 | [diff] [blame] | 88 | \code{decompress()} method. Some of the input data may be preserved |
| 89 | in internal buffers for later processing. |
Guido van Rossum | 04bc9d6 | 1997-04-30 18:12:27 +0000 | [diff] [blame] | 90 | \end{funcdesc} |
| 91 | |
| 92 | \begin{funcdesc}{flush}{} |
| 93 | All pending input is processed, and a string containing the remaining |
| 94 | uncompressed output is returned. After calling \code{flush()}, the |
| 95 | \code{decompress()} method cannot be called again; the only realistic |
| 96 | action is to delete the object. |
| 97 | \end{funcdesc} |
| 98 | |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame^] | 99 | \begin{seealso} |
| 100 | \seemodule{gzip}{reading and writing \file{gzip}-format files} |
| 101 | \end{seealso} |
Guido van Rossum | 04bc9d6 | 1997-04-30 18:12:27 +0000 | [diff] [blame] | 102 | |
| 103 | |