Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libzlib.tex @ 21467:4e35fa5d5708 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add documentation for the help() built-in; contributed by Ka-Ping Yee. This is part of SF patch #494622.
author Fred Drake <fdrake@acm.org>
date Tue, 18 Dec 2001 16:31:08 +0000
parents 60e12f83d2d2
children cdc75de2f5c1
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
8918
acfffe14628e New section header style.
Fred Drake <fdrake@acm.org>
parents: 8768
diff changeset
1 \section{\module{zlib} ---
10664
933732026e9c The version information here was checked good in 1999, not 199. ;-)
Fred Drake <fdrake@acm.org>
parents: 10519
diff changeset
2 Compression compatible with \program{gzip}}
10251
d83935d14084 Shorten a few section titles.
Fred Drake <fdrake@acm.org>
parents: 9739
diff changeset
3
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8529
diff changeset
4 \declaremodule{builtin}{zlib}
8768
fc2a700b1007 Added a synopsis.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
5 \modulesynopsis{Low-level interface to compression and decompression
10664
933732026e9c The version information here was checked good in 1999, not 199. ;-)
Fred Drake <fdrake@acm.org>
parents: 10519
diff changeset
6 routines compatible with \program{gzip}.}
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8529
diff changeset
7
5387
09c58b174989 zlib by AMK
Guido van Rossum <guido@python.org>
parents:
diff changeset
8
09c58b174989 zlib by AMK
Guido van Rossum <guido@python.org>
parents:
diff changeset
9 For applications that require data compression, the functions in this
7932
0522ab210fcb Removed misleading comment about GNU software. This module and the zlib
Fred Drake <fdrake@acm.org>
parents: 7869
diff changeset
10 module allow compression and decompression, using the zlib library.
0522ab210fcb Removed misleading comment about GNU software. This module and the zlib
Fred Drake <fdrake@acm.org>
parents: 7869
diff changeset
11 The zlib library has its own home page at
18270
dee498961bfe Updated link to zlib's home page.
Fred Drake <fdrake@acm.org>
parents: 17586
diff changeset
12 \url{http://www.gzip.org/zlib/}. Version 1.1.3 is the
14622
46f762a61b99 Update *both* uses of the URL to the zlib home page, and use the version
Fred Drake <fdrake@acm.org>
parents: 14621
diff changeset
13 most recent version as of September 2000; use a later version if one
46f762a61b99 Update *both* uses of the URL to the zlib home page, and use the version
Fred Drake <fdrake@acm.org>
parents: 14621
diff changeset
14 is available. There are known incompatibilities between the Python
46f762a61b99 Update *both* uses of the URL to the zlib home page, and use the version
Fred Drake <fdrake@acm.org>
parents: 14621
diff changeset
15 module and earlier versions of the zlib library.
10519
b19f2a982030 correct version info for zlib.
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 10251
diff changeset
16
7819
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
17 The available exception and functions in this module are:
5387
09c58b174989 zlib by AMK
Guido van Rossum <guido@python.org>
parents:
diff changeset
18
7819
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
19 \begin{excdesc}{error}
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
20 Exception raised on compression and decompression errors.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
21 \end{excdesc}
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
22
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
23
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
24 \begin{funcdesc}{adler32}{string\optional{, value}}
5387
09c58b174989 zlib by AMK
Guido van Rossum <guido@python.org>
parents:
diff changeset
25 Computes a Adler-32 checksum of \var{string}. (An Adler-32
09c58b174989 zlib by AMK
Guido van Rossum <guido@python.org>
parents:
diff changeset
26 checksum is almost as reliable as a CRC32 but can be computed much
09c58b174989 zlib by AMK
Guido van Rossum <guido@python.org>
parents:
diff changeset
27 more quickly.) If \var{value} is present, it is used as the
09c58b174989 zlib by AMK
Guido van Rossum <guido@python.org>
parents:
diff changeset
28 starting value of the checksum; otherwise, a fixed default value is
09c58b174989 zlib by AMK
Guido van Rossum <guido@python.org>
parents:
diff changeset
29 used. This allows computing a running checksum over the
09c58b174989 zlib by AMK
Guido van Rossum <guido@python.org>
parents:
diff changeset
30 concatenation of several input strings. The algorithm is not
09c58b174989 zlib by AMK
Guido van Rossum <guido@python.org>
parents:
diff changeset
31 cryptographically strong, and should not be used for
20429
b02986e9a6be Added notes to clarify that binascii.crc32(), zlib.crc32(), and
Fred Drake <fdrake@acm.org>
parents: 18270
diff changeset
32 authentication or digital signatures. Since the algorithm is
b02986e9a6be Added notes to clarify that binascii.crc32(), zlib.crc32(), and
Fred Drake <fdrake@acm.org>
parents: 18270
diff changeset
33 designed for use as a checksum algorithm, it is not suitable for
b02986e9a6be Added notes to clarify that binascii.crc32(), zlib.crc32(), and
Fred Drake <fdrake@acm.org>
parents: 18270
diff changeset
34 use as a general hash algorithm.
5387
09c58b174989 zlib by AMK
Guido van Rossum <guido@python.org>
parents:
diff changeset
35 \end{funcdesc}
09c58b174989 zlib by AMK
Guido van Rossum <guido@python.org>
parents:
diff changeset
36
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
37 \begin{funcdesc}{compress}{string\optional{, level}}
8529
0366daefa23c Somewhat updated, but not checked for everything (just the stuff I was using).
Fred Drake <fdrake@acm.org>
parents: 7932
diff changeset
38 Compresses the data in \var{string}, returning a string contained
0366daefa23c Somewhat updated, but not checked for everything (just the stuff I was using).
Fred Drake <fdrake@acm.org>
parents: 7932
diff changeset
39 compressed data. \var{level} is an integer from \code{1} to
0366daefa23c Somewhat updated, but not checked for everything (just the stuff I was using).
Fred Drake <fdrake@acm.org>
parents: 7932
diff changeset
40 \code{9} controlling the level of compression; \code{1} is fastest
0366daefa23c Somewhat updated, but not checked for everything (just the stuff I was using).
Fred Drake <fdrake@acm.org>
parents: 7932
diff changeset
41 and produces the least compression, \code{9} is slowest and produces
0366daefa23c Somewhat updated, but not checked for everything (just the stuff I was using).
Fred Drake <fdrake@acm.org>
parents: 7932
diff changeset
42 the most. The default value is \code{6}. Raises the
0366daefa23c Somewhat updated, but not checked for everything (just the stuff I was using).
Fred Drake <fdrake@acm.org>
parents: 7932
diff changeset
43 \exception{error} exception if any error occurs.
5387
09c58b174989 zlib by AMK
Guido van Rossum <guido@python.org>
parents:
diff changeset
44 \end{funcdesc}
09c58b174989 zlib by AMK
Guido van Rossum <guido@python.org>
parents:
diff changeset
45
09c58b174989 zlib by AMK
Guido van Rossum <guido@python.org>
parents:
diff changeset
46 \begin{funcdesc}{compressobj}{\optional{level}}
7155
30ab39c2b186 Converted to use new macros. This example demonstrate \method{} and, more
Fred Drake <fdrake@acm.org>
parents: 7007
diff changeset
47 Returns a compression object, to be used for compressing data streams
5387
09c58b174989 zlib by AMK
Guido van Rossum <guido@python.org>
parents:
diff changeset
48 that won't fit into memory at once. \var{level} is an integer from
7155
30ab39c2b186 Converted to use new macros. This example demonstrate \method{} and, more
Fred Drake <fdrake@acm.org>
parents: 7007
diff changeset
49 \code{1} to \code{9} controlling the level of compression; \code{1} is
30ab39c2b186 Converted to use new macros. This example demonstrate \method{} and, more
Fred Drake <fdrake@acm.org>
parents: 7007
diff changeset
50 fastest and produces the least compression, \code{9} is slowest and
30ab39c2b186 Converted to use new macros. This example demonstrate \method{} and, more
Fred Drake <fdrake@acm.org>
parents: 7007
diff changeset
51 produces the most. The default value is \code{6}.
5387
09c58b174989 zlib by AMK
Guido van Rossum <guido@python.org>
parents:
diff changeset
52 \end{funcdesc}
09c58b174989 zlib by AMK
Guido van Rossum <guido@python.org>
parents:
diff changeset
53
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
54 \begin{funcdesc}{crc32}{string\optional{, value}}
7819
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
55 Computes a CRC (Cyclic Redundancy Check)%
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
56 \index{Cyclic Redundancy Check}
7869
31fa8a0fd178 Added index entry.
Fred Drake <fdrake@acm.org>
parents: 7819
diff changeset
57 \index{checksum!Cyclic Redundancy Check}
7819
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
58 checksum of \var{string}. If
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
59 \var{value} is present, it is used as the starting value of the
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
60 checksum; otherwise, a fixed default value is used. This allows
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
61 computing a running checksum over the concatenation of several
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
62 input strings. The algorithm is not cryptographically strong, and
20429
b02986e9a6be Added notes to clarify that binascii.crc32(), zlib.crc32(), and
Fred Drake <fdrake@acm.org>
parents: 18270
diff changeset
63 should not be used for authentication or digital signatures. Since
b02986e9a6be Added notes to clarify that binascii.crc32(), zlib.crc32(), and
Fred Drake <fdrake@acm.org>
parents: 18270
diff changeset
64 the algorithm is designed for use as a checksum algorithm, it is not
b02986e9a6be Added notes to clarify that binascii.crc32(), zlib.crc32(), and
Fred Drake <fdrake@acm.org>
parents: 18270
diff changeset
65 suitable for use as a general hash algorithm.
5387
09c58b174989 zlib by AMK
Guido van Rossum <guido@python.org>
parents:
diff changeset
66 \end{funcdesc}
09c58b174989 zlib by AMK
Guido van Rossum <guido@python.org>
parents:
diff changeset
67
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10664
diff changeset
68 \begin{funcdesc}{decompress}{string\optional{, wbits\optional{, bufsize}}}
8529
0366daefa23c Somewhat updated, but not checked for everything (just the stuff I was using).
Fred Drake <fdrake@acm.org>
parents: 7932
diff changeset
69 Decompresses the data in \var{string}, returning a string containing
0366daefa23c Somewhat updated, but not checked for everything (just the stuff I was using).
Fred Drake <fdrake@acm.org>
parents: 7932
diff changeset
70 the uncompressed data. The \var{wbits} parameter controls the size of
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10664
diff changeset
71 the window buffer. If \var{bufsize} is given, it is used as the
8529
0366daefa23c Somewhat updated, but not checked for everything (just the stuff I was using).
Fred Drake <fdrake@acm.org>
parents: 7932
diff changeset
72 initial size of the output buffer. Raises the \exception{error}
0366daefa23c Somewhat updated, but not checked for everything (just the stuff I was using).
Fred Drake <fdrake@acm.org>
parents: 7932
diff changeset
73 exception if any error occurs.
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10664
diff changeset
74
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10664
diff changeset
75 The absolute value of \var{wbits} is the base two logarithm of the
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10664
diff changeset
76 size of the history buffer (the ``window size'') used when compressing
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10664
diff changeset
77 data. Its absolute value should be between 8 and 15 for the most
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10664
diff changeset
78 recent versions of the zlib library, larger values resulting in better
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10664
diff changeset
79 compression at the expense of greater memory usage. The default value
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10664
diff changeset
80 is 15. When \var{wbits} is negative, the standard
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10664
diff changeset
81 \program{gzip} header is suppressed; this is an undocumented feature
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10664
diff changeset
82 of the zlib library, used for compatibility with \program{unzip}'s
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10664
diff changeset
83 compression file format.
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10664
diff changeset
84
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10664
diff changeset
85 \var{bufsize} is the initial size of the buffer used to hold
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10664
diff changeset
86 decompressed data. If more space is required, the buffer size will be
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10664
diff changeset
87 increased as needed, so you don't have to get this value exactly
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10664
diff changeset
88 right; tuning it will only save a few calls to \cfunction{malloc()}. The
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10664
diff changeset
89 default size is 16384.
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10664
diff changeset
90
5387
09c58b174989 zlib by AMK
Guido van Rossum <guido@python.org>
parents:
diff changeset
91 \end{funcdesc}
09c58b174989 zlib by AMK
Guido van Rossum <guido@python.org>
parents:
diff changeset
92
09c58b174989 zlib by AMK
Guido van Rossum <guido@python.org>
parents:
diff changeset
93 \begin{funcdesc}{decompressobj}{\optional{wbits}}
17586
c5f7191ce67e Cut-&-paste-o noted by Wolfgang Teschner: decompressobj() returns
Fred Drake <fdrake@acm.org>
parents: 15261
diff changeset
94 Returns a decompression object, to be used for decompressing data
8529
0366daefa23c Somewhat updated, but not checked for everything (just the stuff I was using).
Fred Drake <fdrake@acm.org>
parents: 7932
diff changeset
95 streams that won't fit into memory at once. The \var{wbits}
0366daefa23c Somewhat updated, but not checked for everything (just the stuff I was using).
Fred Drake <fdrake@acm.org>
parents: 7932
diff changeset
96 parameter controls the size of the window buffer.
5387
09c58b174989 zlib by AMK
Guido van Rossum <guido@python.org>
parents:
diff changeset
97 \end{funcdesc}
09c58b174989 zlib by AMK
Guido van Rossum <guido@python.org>
parents:
diff changeset
98
09c58b174989 zlib by AMK
Guido van Rossum <guido@python.org>
parents:
diff changeset
99 Compression objects support the following methods:
09c58b174989 zlib by AMK
Guido van Rossum <guido@python.org>
parents:
diff changeset
100
7819
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
101 \begin{methoddesc}[Compress]{compress}{string}
5387
09c58b174989 zlib by AMK
Guido van Rossum <guido@python.org>
parents:
diff changeset
102 Compress \var{string}, returning a string containing compressed data
09c58b174989 zlib by AMK
Guido van Rossum <guido@python.org>
parents:
diff changeset
103 for at least part of the data in \var{string}. This data should be
09c58b174989 zlib by AMK
Guido van Rossum <guido@python.org>
parents:
diff changeset
104 concatenated to the output produced by any preceding calls to the
7155
30ab39c2b186 Converted to use new macros. This example demonstrate \method{} and, more
Fred Drake <fdrake@acm.org>
parents: 7007
diff changeset
105 \method{compress()} method. Some input may be kept in internal buffers
5387
09c58b174989 zlib by AMK
Guido van Rossum <guido@python.org>
parents:
diff changeset
106 for later processing.
7819
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
107 \end{methoddesc}
5387
09c58b174989 zlib by AMK
Guido van Rossum <guido@python.org>
parents:
diff changeset
108
9739
e6b662a9b709 Document the optional mode argument (Z_FLUSH, Z_SYNC_FLUSH, etc.)
Andrew M. Kuchling <amk@amk.ca>
parents: 8918
diff changeset
109 \begin{methoddesc}[Compress]{flush}{\optional{mode}}
e6b662a9b709 Document the optional mode argument (Z_FLUSH, Z_SYNC_FLUSH, etc.)
Andrew M. Kuchling <amk@amk.ca>
parents: 8918
diff changeset
110 All pending input is processed, and a string containing the remaining
e6b662a9b709 Document the optional mode argument (Z_FLUSH, Z_SYNC_FLUSH, etc.)
Andrew M. Kuchling <amk@amk.ca>
parents: 8918
diff changeset
111 compressed output is returned. \var{mode} can be selected from the
e6b662a9b709 Document the optional mode argument (Z_FLUSH, Z_SYNC_FLUSH, etc.)
Andrew M. Kuchling <amk@amk.ca>
parents: 8918
diff changeset
112 constants \constant{Z_SYNC_FLUSH}, \constant{Z_FULL_FLUSH}, or
e6b662a9b709 Document the optional mode argument (Z_FLUSH, Z_SYNC_FLUSH, etc.)
Andrew M. Kuchling <amk@amk.ca>
parents: 8918
diff changeset
113 \constant{Z_FINISH}, defaulting to \constant{Z_FINISH}. \constant{Z_SYNC_FLUSH} and
e6b662a9b709 Document the optional mode argument (Z_FLUSH, Z_SYNC_FLUSH, etc.)
Andrew M. Kuchling <amk@amk.ca>
parents: 8918
diff changeset
114 \constant{Z_FULL_FLUSH} allow compressing further strings of data and
e6b662a9b709 Document the optional mode argument (Z_FLUSH, Z_SYNC_FLUSH, etc.)
Andrew M. Kuchling <amk@amk.ca>
parents: 8918
diff changeset
115 are used to allow partial error recovery on decompression, while
e6b662a9b709 Document the optional mode argument (Z_FLUSH, Z_SYNC_FLUSH, etc.)
Andrew M. Kuchling <amk@amk.ca>
parents: 8918
diff changeset
116 \constant{Z_FINISH} finishes the compressed stream and
e6b662a9b709 Document the optional mode argument (Z_FLUSH, Z_SYNC_FLUSH, etc.)
Andrew M. Kuchling <amk@amk.ca>
parents: 8918
diff changeset
117 prevents compressing any more data. After calling
e6b662a9b709 Document the optional mode argument (Z_FLUSH, Z_SYNC_FLUSH, etc.)
Andrew M. Kuchling <amk@amk.ca>
parents: 8918
diff changeset
118 \method{flush()} with \var{mode} set to \constant{Z_FINISH}, the
7155
30ab39c2b186 Converted to use new macros. This example demonstrate \method{} and, more
Fred Drake <fdrake@acm.org>
parents: 7007
diff changeset
119 \method{compress()} method cannot be called again; the only realistic
9739
e6b662a9b709 Document the optional mode argument (Z_FLUSH, Z_SYNC_FLUSH, etc.)
Andrew M. Kuchling <amk@amk.ca>
parents: 8918
diff changeset
120 action is to delete the object.
7819
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
121 \end{methoddesc}
5387
09c58b174989 zlib by AMK
Guido van Rossum <guido@python.org>
parents:
diff changeset
122
20466
60e12f83d2d2 [ #403753 ] zlib decompress; uncontrollable memory usage
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 20429
diff changeset
123 Decompression objects support the following methods, and two attributes:
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10664
diff changeset
124
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10664
diff changeset
125 \begin{memberdesc}{unused_data}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10664
diff changeset
126 A string which contains any unused data from the last string fed to
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10664
diff changeset
127 this decompression object. If the whole string turned out to contain
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10664
diff changeset
128 compressed data, this is \code{""}, the empty string.
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10664
diff changeset
129
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10664
diff changeset
130 The only way to determine where a string of compressed data ends is by
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10664
diff changeset
131 actually decompressing it. This means that when compressed data is
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10664
diff changeset
132 contained part of a larger file, you can only find the end of it by
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10664
diff changeset
133 reading data and feeding it into a decompression object's
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10664
diff changeset
134 \method{decompress} method until the \member{unused_data} attribute is
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10664
diff changeset
135 no longer the empty string.
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10664
diff changeset
136 \end{memberdesc}
5387
09c58b174989 zlib by AMK
Guido van Rossum <guido@python.org>
parents:
diff changeset
137
20466
60e12f83d2d2 [ #403753 ] zlib decompress; uncontrollable memory usage
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 20429
diff changeset
138 \begin{memberdesc}{unconsumed_tail}
60e12f83d2d2 [ #403753 ] zlib decompress; uncontrollable memory usage
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 20429
diff changeset
139 A string that contains any data that was not consumed by the last
60e12f83d2d2 [ #403753 ] zlib decompress; uncontrollable memory usage
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 20429
diff changeset
140 \method{decompress} call because it exceeded the limit for the
60e12f83d2d2 [ #403753 ] zlib decompress; uncontrollable memory usage
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 20429
diff changeset
141 uncompressed data buffer.
60e12f83d2d2 [ #403753 ] zlib decompress; uncontrollable memory usage
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 20429
diff changeset
142 \end{memberdesc}
60e12f83d2d2 [ #403753 ] zlib decompress; uncontrollable memory usage
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 20429
diff changeset
143
60e12f83d2d2 [ #403753 ] zlib decompress; uncontrollable memory usage
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 20429
diff changeset
144 \begin{methoddesc}[Decompress]{decompress}{string}{\optional{max_length}}
5387
09c58b174989 zlib by AMK
Guido van Rossum <guido@python.org>
parents:
diff changeset
145 Decompress \var{string}, returning a string containing the
09c58b174989 zlib by AMK
Guido van Rossum <guido@python.org>
parents:
diff changeset
146 uncompressed data corresponding to at least part of the data in
09c58b174989 zlib by AMK
Guido van Rossum <guido@python.org>
parents:
diff changeset
147 \var{string}. This data should be concatenated to the output produced
09c58b174989 zlib by AMK
Guido van Rossum <guido@python.org>
parents:
diff changeset
148 by any preceding calls to the
7155
30ab39c2b186 Converted to use new macros. This example demonstrate \method{} and, more
Fred Drake <fdrake@acm.org>
parents: 7007
diff changeset
149 \method{decompress()} method. Some of the input data may be preserved
5390
b24e84a0f30b Updated web ref and version#. Folded some long lines.
Guido van Rossum <guido@python.org>
parents: 5387
diff changeset
150 in internal buffers for later processing.
20466
60e12f83d2d2 [ #403753 ] zlib decompress; uncontrollable memory usage
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 20429
diff changeset
151
60e12f83d2d2 [ #403753 ] zlib decompress; uncontrollable memory usage
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 20429
diff changeset
152 If the optional parameter \var{max_length} is supplied then the return value
60e12f83d2d2 [ #403753 ] zlib decompress; uncontrollable memory usage
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 20429
diff changeset
153 will be no longer than \var{max_length}. This may mean that not all of the
60e12f83d2d2 [ #403753 ] zlib decompress; uncontrollable memory usage
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 20429
diff changeset
154 compressed input can be processed; and unconsumed data will be stored
60e12f83d2d2 [ #403753 ] zlib decompress; uncontrollable memory usage
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 20429
diff changeset
155 in the attribute \member{unconsumed_tail}. This string must be passed
60e12f83d2d2 [ #403753 ] zlib decompress; uncontrollable memory usage
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 20429
diff changeset
156 to a subsequent call to \method{decompress()} if decompression is to
60e12f83d2d2 [ #403753 ] zlib decompress; uncontrollable memory usage
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 20429
diff changeset
157 continue. If \var{max_length} is not supplied then the whole input is
60e12f83d2d2 [ #403753 ] zlib decompress; uncontrollable memory usage
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 20429
diff changeset
158 decompressed, and \member{unconsumed_tail} is an empty string.
7819
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
159 \end{methoddesc}
5387
09c58b174989 zlib by AMK
Guido van Rossum <guido@python.org>
parents:
diff changeset
160
7819
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
161 \begin{methoddesc}[Decompress]{flush}{}
5387
09c58b174989 zlib by AMK
Guido van Rossum <guido@python.org>
parents:
diff changeset
162 All pending input is processed, and a string containing the remaining
7155
30ab39c2b186 Converted to use new macros. This example demonstrate \method{} and, more
Fred Drake <fdrake@acm.org>
parents: 7007
diff changeset
163 uncompressed output is returned. After calling \method{flush()}, the
30ab39c2b186 Converted to use new macros. This example demonstrate \method{} and, more
Fred Drake <fdrake@acm.org>
parents: 7007
diff changeset
164 \method{decompress()} method cannot be called again; the only realistic
5387
09c58b174989 zlib by AMK
Guido van Rossum <guido@python.org>
parents:
diff changeset
165 action is to delete the object.
7819
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
166 \end{methoddesc}
5387
09c58b174989 zlib by AMK
Guido van Rossum <guido@python.org>
parents:
diff changeset
167
5818
3468ea8645ca AMK's megapatch:
Guido van Rossum <guido@python.org>
parents: 5676
diff changeset
168 \begin{seealso}
15261
bc4f89eefb04 Make all the \seemodule explanations consistent: start with a capitalized
Fred Drake <fdrake@acm.org>
parents: 14622
diff changeset
169 \seemodule{gzip}{Reading and writing \program{gzip}-format files.}
18270
dee498961bfe Updated link to zlib's home page.
Fred Drake <fdrake@acm.org>
parents: 17586
diff changeset
170 \seeurl{http://www.gzip.org/zlib/}{The zlib library home page.}
5818
3468ea8645ca AMK's megapatch:
Guido van Rossum <guido@python.org>
parents: 5676
diff changeset
171 \end{seealso}