Jeremy Hylton | 45b0aed | 1999-04-05 21:55:21 +0000 | [diff] [blame] | 1 | % XXX The module has been extended (by Jeremy and Andrew) but this |
| 2 | % documentation is incorrect in some cases. |
Guido van Rossum | eb0f066 | 1997-12-30 20:38:16 +0000 | [diff] [blame] | 3 | |
Fred Drake | 295da24 | 1998-08-10 19:42:37 +0000 | [diff] [blame] | 4 | \section{\module{zlib} --- |
Fred Drake | b11d108 | 1999-04-21 18:44:41 +0000 | [diff] [blame^] | 5 | Compression compatible with \program{gzip}} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 6 | |
Fred Drake | bbac432 | 1999-02-20 00:14:17 +0000 | [diff] [blame] | 7 | \declaremodule{builtin}{zlib} |
Fred Drake | 08caa96 | 1998-07-27 22:08:49 +0000 | [diff] [blame] | 8 | \modulesynopsis{Low-level interface to compression and decompression |
Fred Drake | b11d108 | 1999-04-21 18:44:41 +0000 | [diff] [blame^] | 9 | routines compatible with \program{gzip}.} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 10 | |
Guido van Rossum | 04bc9d6 | 1997-04-30 18:12:27 +0000 | [diff] [blame] | 11 | |
| 12 | For applications that require data compression, the functions in this |
Fred Drake | 8a254b5 | 1998-04-09 15:41:44 +0000 | [diff] [blame] | 13 | module allow compression and decompression, using the zlib library. |
| 14 | The zlib library has its own home page at |
Jeremy Hylton | 45b0aed | 1999-04-05 21:55:21 +0000 | [diff] [blame] | 15 | \url{http://www.cdrom.com/pub/infozip/zlib/}. Version 1.1.3 is the |
Fred Drake | b11d108 | 1999-04-21 18:44:41 +0000 | [diff] [blame^] | 16 | most recent version as of April 1999; use a later version if one |
Jeremy Hylton | 45b0aed | 1999-04-05 21:55:21 +0000 | [diff] [blame] | 17 | is available. There are known incompatibilities between the Python |
| 18 | module and earlier versions of the zlib library. |
| 19 | |
| 20 | The documentation for this module is woefully out of date. In some |
| 21 | cases, the doc strings have been updated more recently. In other |
| 22 | cases, they are both stale. |
Guido van Rossum | 04bc9d6 | 1997-04-30 18:12:27 +0000 | [diff] [blame] | 23 | |
Fred Drake | 74810d5 | 1998-04-03 06:49:26 +0000 | [diff] [blame] | 24 | The available exception and functions in this module are: |
Guido van Rossum | 04bc9d6 | 1997-04-30 18:12:27 +0000 | [diff] [blame] | 25 | |
Fred Drake | 74810d5 | 1998-04-03 06:49:26 +0000 | [diff] [blame] | 26 | \begin{excdesc}{error} |
| 27 | Exception raised on compression and decompression errors. |
| 28 | \end{excdesc} |
| 29 | |
| 30 | |
Fred Drake | cce1090 | 1998-03-17 06:33:25 +0000 | [diff] [blame] | 31 | \begin{funcdesc}{adler32}{string\optional{, value}} |
Guido van Rossum | 04bc9d6 | 1997-04-30 18:12:27 +0000 | [diff] [blame] | 32 | Computes a Adler-32 checksum of \var{string}. (An Adler-32 |
| 33 | checksum is almost as reliable as a CRC32 but can be computed much |
| 34 | more quickly.) If \var{value} is present, it is used as the |
| 35 | starting value of the checksum; otherwise, a fixed default value is |
| 36 | used. This allows computing a running checksum over the |
| 37 | concatenation of several input strings. The algorithm is not |
| 38 | cryptographically strong, and should not be used for |
| 39 | authentication or digital signatures. |
| 40 | \end{funcdesc} |
| 41 | |
Fred Drake | cce1090 | 1998-03-17 06:33:25 +0000 | [diff] [blame] | 42 | \begin{funcdesc}{compress}{string\optional{, level}} |
Fred Drake | 5916070 | 1998-06-19 21:18:28 +0000 | [diff] [blame] | 43 | Compresses the data in \var{string}, returning a string contained |
| 44 | compressed data. \var{level} is an integer from \code{1} to |
| 45 | \code{9} controlling the level of compression; \code{1} is fastest |
| 46 | and produces the least compression, \code{9} is slowest and produces |
| 47 | the most. The default value is \code{6}. Raises the |
| 48 | \exception{error} exception if any error occurs. |
Guido van Rossum | 04bc9d6 | 1997-04-30 18:12:27 +0000 | [diff] [blame] | 49 | \end{funcdesc} |
| 50 | |
| 51 | \begin{funcdesc}{compressobj}{\optional{level}} |
Fred Drake | ed79783 | 1998-01-22 16:11:18 +0000 | [diff] [blame] | 52 | Returns a compression object, to be used for compressing data streams |
Guido van Rossum | 04bc9d6 | 1997-04-30 18:12:27 +0000 | [diff] [blame] | 53 | 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] | 54 | \code{1} to \code{9} controlling the level of compression; \code{1} is |
| 55 | fastest and produces the least compression, \code{9} is slowest and |
| 56 | produces the most. The default value is \code{6}. |
Guido van Rossum | 04bc9d6 | 1997-04-30 18:12:27 +0000 | [diff] [blame] | 57 | \end{funcdesc} |
| 58 | |
Fred Drake | cce1090 | 1998-03-17 06:33:25 +0000 | [diff] [blame] | 59 | \begin{funcdesc}{crc32}{string\optional{, value}} |
Fred Drake | 74810d5 | 1998-04-03 06:49:26 +0000 | [diff] [blame] | 60 | Computes a CRC (Cyclic Redundancy Check)% |
| 61 | \index{Cyclic Redundancy Check} |
Fred Drake | b208f12 | 1998-04-04 06:28:54 +0000 | [diff] [blame] | 62 | \index{checksum!Cyclic Redundancy Check} |
Fred Drake | 74810d5 | 1998-04-03 06:49:26 +0000 | [diff] [blame] | 63 | checksum of \var{string}. If |
| 64 | \var{value} is present, it is used as the starting value of the |
| 65 | checksum; otherwise, a fixed default value is used. This allows |
| 66 | computing a running checksum over the concatenation of several |
| 67 | input strings. The algorithm is not cryptographically strong, and |
| 68 | should not be used for authentication or digital signatures. |
Guido van Rossum | 04bc9d6 | 1997-04-30 18:12:27 +0000 | [diff] [blame] | 69 | \end{funcdesc} |
| 70 | |
Fred Drake | 5916070 | 1998-06-19 21:18:28 +0000 | [diff] [blame] | 71 | \begin{funcdesc}{decompress}{string\optional{, wbits\optional{, buffsize}}} |
| 72 | Decompresses the data in \var{string}, returning a string containing |
| 73 | the uncompressed data. The \var{wbits} parameter controls the size of |
| 74 | the window buffer. If \var{buffsize} is given, it is used as the |
| 75 | initial size of the output buffer. Raises the \exception{error} |
| 76 | exception if any error occurs. |
Guido van Rossum | 04bc9d6 | 1997-04-30 18:12:27 +0000 | [diff] [blame] | 77 | \end{funcdesc} |
| 78 | |
| 79 | \begin{funcdesc}{decompressobj}{\optional{wbits}} |
Fred Drake | 5916070 | 1998-06-19 21:18:28 +0000 | [diff] [blame] | 80 | Returns a compression object, to be used for decompressing data |
| 81 | streams that won't fit into memory at once. The \var{wbits} |
| 82 | parameter controls the size of the window buffer. |
Guido van Rossum | 04bc9d6 | 1997-04-30 18:12:27 +0000 | [diff] [blame] | 83 | \end{funcdesc} |
| 84 | |
| 85 | Compression objects support the following methods: |
| 86 | |
Fred Drake | 74810d5 | 1998-04-03 06:49:26 +0000 | [diff] [blame] | 87 | \begin{methoddesc}[Compress]{compress}{string} |
Guido van Rossum | 04bc9d6 | 1997-04-30 18:12:27 +0000 | [diff] [blame] | 88 | Compress \var{string}, returning a string containing compressed data |
| 89 | for at least part of the data in \var{string}. This data should be |
| 90 | concatenated to the output produced by any preceding calls to the |
Fred Drake | ed79783 | 1998-01-22 16:11:18 +0000 | [diff] [blame] | 91 | \method{compress()} method. Some input may be kept in internal buffers |
Guido van Rossum | 04bc9d6 | 1997-04-30 18:12:27 +0000 | [diff] [blame] | 92 | for later processing. |
Fred Drake | 74810d5 | 1998-04-03 06:49:26 +0000 | [diff] [blame] | 93 | \end{methoddesc} |
Guido van Rossum | 04bc9d6 | 1997-04-30 18:12:27 +0000 | [diff] [blame] | 94 | |
Andrew M. Kuchling | f07c328 | 1998-12-31 21:14:23 +0000 | [diff] [blame] | 95 | \begin{methoddesc}[Compress]{flush}{\optional{mode}} |
| 96 | All pending input is processed, and a string containing the remaining |
| 97 | compressed output is returned. \var{mode} can be selected from the |
| 98 | constants \constant{Z_SYNC_FLUSH}, \constant{Z_FULL_FLUSH}, or |
| 99 | \constant{Z_FINISH}, defaulting to \constant{Z_FINISH}. \constant{Z_SYNC_FLUSH} and |
| 100 | \constant{Z_FULL_FLUSH} allow compressing further strings of data and |
| 101 | are used to allow partial error recovery on decompression, while |
| 102 | \constant{Z_FINISH} finishes the compressed stream and |
| 103 | prevents compressing any more data. After calling |
| 104 | \method{flush()} with \var{mode} set to \constant{Z_FINISH}, the |
Fred Drake | ed79783 | 1998-01-22 16:11:18 +0000 | [diff] [blame] | 105 | \method{compress()} method cannot be called again; the only realistic |
Andrew M. Kuchling | f07c328 | 1998-12-31 21:14:23 +0000 | [diff] [blame] | 106 | action is to delete the object. |
Fred Drake | 74810d5 | 1998-04-03 06:49:26 +0000 | [diff] [blame] | 107 | \end{methoddesc} |
Guido van Rossum | 04bc9d6 | 1997-04-30 18:12:27 +0000 | [diff] [blame] | 108 | |
| 109 | Decompression objects support the following methods: |
| 110 | |
Fred Drake | 74810d5 | 1998-04-03 06:49:26 +0000 | [diff] [blame] | 111 | \begin{methoddesc}[Decompress]{decompress}{string} |
Guido van Rossum | 04bc9d6 | 1997-04-30 18:12:27 +0000 | [diff] [blame] | 112 | Decompress \var{string}, returning a string containing the |
| 113 | uncompressed data corresponding to at least part of the data in |
| 114 | \var{string}. This data should be concatenated to the output produced |
| 115 | by any preceding calls to the |
Fred Drake | ed79783 | 1998-01-22 16:11:18 +0000 | [diff] [blame] | 116 | \method{decompress()} method. Some of the input data may be preserved |
Guido van Rossum | 412154f | 1997-04-30 19:39:21 +0000 | [diff] [blame] | 117 | in internal buffers for later processing. |
Fred Drake | 74810d5 | 1998-04-03 06:49:26 +0000 | [diff] [blame] | 118 | \end{methoddesc} |
Guido van Rossum | 04bc9d6 | 1997-04-30 18:12:27 +0000 | [diff] [blame] | 119 | |
Fred Drake | 74810d5 | 1998-04-03 06:49:26 +0000 | [diff] [blame] | 120 | \begin{methoddesc}[Decompress]{flush}{} |
Guido van Rossum | 04bc9d6 | 1997-04-30 18:12:27 +0000 | [diff] [blame] | 121 | All pending input is processed, and a string containing the remaining |
Fred Drake | ed79783 | 1998-01-22 16:11:18 +0000 | [diff] [blame] | 122 | uncompressed output is returned. After calling \method{flush()}, the |
| 123 | \method{decompress()} method cannot be called again; the only realistic |
Guido van Rossum | 04bc9d6 | 1997-04-30 18:12:27 +0000 | [diff] [blame] | 124 | action is to delete the object. |
Fred Drake | 74810d5 | 1998-04-03 06:49:26 +0000 | [diff] [blame] | 125 | \end{methoddesc} |
Guido van Rossum | 04bc9d6 | 1997-04-30 18:12:27 +0000 | [diff] [blame] | 126 | |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 127 | \begin{seealso} |
Fred Drake | b11d108 | 1999-04-21 18:44:41 +0000 | [diff] [blame^] | 128 | \seemodule{gzip}{reading and writing \program{gzip}-format files} |
| 129 | \seetext{The zlib library home page is located at |
| 130 | \url{http://www.cdrom.com/pub/infozip/zlib/}.} |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 131 | \end{seealso} |