Guido van Rossum | eb0f066 | 1997-12-30 20:38:16 +0000 | [diff] [blame] | 1 | % XXX The module has been extended (by Jeremy) but this documentation hasn't been updated yet |
| 2 | |
Guido van Rossum | 04bc9d6 | 1997-04-30 18:12:27 +0000 | [diff] [blame] | 3 | \section{Built-in Module \sectcode{zlib}} |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 4 | \label{module-zlib} |
Guido van Rossum | 04bc9d6 | 1997-04-30 18:12:27 +0000 | [diff] [blame] | 5 | \bimodindex{zlib} |
| 6 | |
| 7 | For applications that require data compression, the functions in this |
Guido van Rossum | 412154f | 1997-04-30 19:39:21 +0000 | [diff] [blame] | 8 | module allow compression and decompression, using the zlib library, |
| 9 | which is based on GNU zip. The zlib library has its own home page at |
Fred Drake | ed79783 | 1998-01-22 16:11:18 +0000 | [diff] [blame] | 10 | \url{http://www.cdrom.com/pub/infozip/zlib/}. |
Guido van Rossum | eb0f066 | 1997-12-30 20:38:16 +0000 | [diff] [blame] | 11 | Version 1.0.4 is the most recent version as of December, 1997; use a |
Guido van Rossum | 412154f | 1997-04-30 19:39:21 +0000 | [diff] [blame] | 12 | later version if one is available. |
Guido van Rossum | 04bc9d6 | 1997-04-30 18:12:27 +0000 | [diff] [blame] | 13 | |
| 14 | The available functions in this module are: |
| 15 | |
| 16 | \renewcommand{\indexsubitem}{(in module zlib)} |
| 17 | \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}} |
| 29 | Compresses the data in \var{string}, returning a string contained |
Fred Drake | ed79783 | 1998-01-22 16:11:18 +0000 | [diff] [blame] | 30 | compressed data. \var{level} is an integer from \code{1} to \code{9} |
| 31 | controlling the level of compression; \code{1} is fastest and produces |
| 32 | the least compression, \code{9} is slowest and produces the most. The |
| 33 | default value is \code{6}. Raises the \exception{zlib.error} |
| 34 | exception if any error occurs. |
Guido van Rossum | 04bc9d6 | 1997-04-30 18:12:27 +0000 | [diff] [blame] | 35 | \end{funcdesc} |
| 36 | |
| 37 | \begin{funcdesc}{compressobj}{\optional{level}} |
Fred Drake | ed79783 | 1998-01-22 16:11:18 +0000 | [diff] [blame] | 38 | Returns a compression object, to be used for compressing data streams |
Guido van Rossum | 04bc9d6 | 1997-04-30 18:12:27 +0000 | [diff] [blame] | 39 | that won't fit into memory at once. \var{level} is an integer from |
Fred Drake | ed79783 | 1998-01-22 16:11:18 +0000 | [diff] [blame] | 40 | \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 Rossum | 04bc9d6 | 1997-04-30 18:12:27 +0000 | [diff] [blame] | 43 | \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} |
| 55 | Decompresses the data in \var{string}, returning a string containing |
Fred Drake | ed79783 | 1998-01-22 16:11:18 +0000 | [diff] [blame] | 56 | the uncompressed data. Raises the \exception{zlib.error} exception if any |
Guido van Rossum | 04bc9d6 | 1997-04-30 18:12:27 +0000 | [diff] [blame] | 57 | error occurs. |
| 58 | \end{funcdesc} |
| 59 | |
| 60 | \begin{funcdesc}{decompressobj}{\optional{wbits}} |
| 61 | Returns a compression object, to be used for decompressing data streams |
Guido van Rossum | 412154f | 1997-04-30 19:39:21 +0000 | [diff] [blame] | 62 | that won't fit into memory at once. The \var{wbits} parameter |
| 63 | controls the size of the window buffer; usually this can be left |
| 64 | alone. |
Guido van Rossum | 04bc9d6 | 1997-04-30 18:12:27 +0000 | [diff] [blame] | 65 | \end{funcdesc} |
| 66 | |
| 67 | Compression objects support the following methods: |
| 68 | |
| 69 | \begin{funcdesc}{compress}{string} |
| 70 | Compress \var{string}, returning a string containing compressed data |
| 71 | for at least part of the data in \var{string}. This data should be |
| 72 | concatenated to the output produced by any preceding calls to the |
Fred Drake | ed79783 | 1998-01-22 16:11:18 +0000 | [diff] [blame] | 73 | \method{compress()} method. Some input may be kept in internal buffers |
Guido van Rossum | 04bc9d6 | 1997-04-30 18:12:27 +0000 | [diff] [blame] | 74 | for later processing. |
| 75 | \end{funcdesc} |
| 76 | |
| 77 | \begin{funcdesc}{flush}{} |
| 78 | All pending input is processed, and an string containing the remaining |
Fred Drake | ed79783 | 1998-01-22 16:11:18 +0000 | [diff] [blame] | 79 | compressed output is returned. After calling \method{flush()}, the |
| 80 | \method{compress()} method cannot be called again; the only realistic |
Guido van Rossum | 04bc9d6 | 1997-04-30 18:12:27 +0000 | [diff] [blame] | 81 | action is to delete the object. |
| 82 | \end{funcdesc} |
| 83 | |
| 84 | Decompression objects support the following methods: |
| 85 | |
| 86 | \begin{funcdesc}{decompress}{string} |
| 87 | Decompress \var{string}, returning a string containing the |
| 88 | uncompressed data corresponding to at least part of the data in |
| 89 | \var{string}. This data should be concatenated to the output produced |
| 90 | by any preceding calls to the |
Fred Drake | ed79783 | 1998-01-22 16:11:18 +0000 | [diff] [blame] | 91 | \method{decompress()} method. Some of the input data may be preserved |
Guido van Rossum | 412154f | 1997-04-30 19:39:21 +0000 | [diff] [blame] | 92 | in internal buffers for later processing. |
Guido van Rossum | 04bc9d6 | 1997-04-30 18:12:27 +0000 | [diff] [blame] | 93 | \end{funcdesc} |
| 94 | |
| 95 | \begin{funcdesc}{flush}{} |
| 96 | All pending input is processed, and a string containing the remaining |
Fred Drake | ed79783 | 1998-01-22 16:11:18 +0000 | [diff] [blame] | 97 | uncompressed output is returned. After calling \method{flush()}, the |
| 98 | \method{decompress()} method cannot be called again; the only realistic |
Guido van Rossum | 04bc9d6 | 1997-04-30 18:12:27 +0000 | [diff] [blame] | 99 | action is to delete the object. |
| 100 | \end{funcdesc} |
| 101 | |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 102 | \begin{seealso} |
| 103 | \seemodule{gzip}{reading and writing \file{gzip}-format files} |
| 104 | \end{seealso} |
Guido van Rossum | 04bc9d6 | 1997-04-30 18:12:27 +0000 | [diff] [blame] | 105 | |
| 106 | |