--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/symbian-qemu-0.9.1-12/python-2.6.1/Doc/library/zlib.rst Fri Jul 31 15:01:17 2009 +0100
@@ -0,0 +1,223 @@
+
+:mod:`zlib` --- Compression compatible with :program:`gzip`
+===========================================================
+
+.. module:: zlib
+ :synopsis: Low-level interface to compression and decompression routines compatible with
+ gzip.
+
+
+For applications that require data compression, the functions in this module
+allow compression and decompression, using the zlib library. The zlib library
+has its own home page at http://www.zlib.net. There are known
+incompatibilities between the Python module and versions of the zlib library
+earlier than 1.1.3; 1.1.3 has a security vulnerability, so we recommend using
+1.1.4 or later.
+
+zlib's functions have many options and often need to be used in a particular
+order. This documentation doesn't attempt to cover all of the permutations;
+consult the zlib manual at http://www.zlib.net/manual.html for authoritative
+information.
+
+For reading and writing ``.gz`` files see the :mod:`gzip` module. For
+other archive formats, see the :mod:`bz2`, :mod:`zipfile`, and
+:mod:`tarfile` modules.
+
+The available exception and functions in this module are:
+
+
+.. exception:: error
+
+ Exception raised on compression and decompression errors.
+
+
+.. function:: adler32(string[, value])
+
+ Computes a Adler-32 checksum of *string*. (An Adler-32 checksum is almost as
+ reliable as a CRC32 but can be computed much more quickly.) If *value* is
+ present, it is used as the starting value of the checksum; otherwise, a fixed
+ default value is used. This allows computing a running checksum over the
+ concatenation of several input strings. The algorithm is not cryptographically
+ strong, and should not be used for authentication or digital signatures. Since
+ the algorithm is designed for use as a checksum algorithm, it is not suitable
+ for use as a general hash algorithm.
+
+ This function always returns an integer object.
+
+ .. versionchanged:: 2.6
+ For consistent cross-platform behavior we always return a signed integer.
+ ie: Results in the (2**31)...(2**32-1) range will be negative.
+
+
+.. function:: compress(string[, level])
+
+ Compresses the data in *string*, returning a string contained compressed data.
+ *level* is an integer from ``1`` to ``9`` controlling the level of compression;
+ ``1`` is fastest and produces the least compression, ``9`` is slowest and
+ produces the most. The default value is ``6``. Raises the :exc:`error`
+ exception if any error occurs.
+
+
+.. function:: compressobj([level])
+
+ Returns a compression object, to be used for compressing data streams that won't
+ fit into memory at once. *level* is an integer from ``1`` to ``9`` controlling
+ the level of compression; ``1`` is fastest and produces the least compression,
+ ``9`` is slowest and produces the most. The default value is ``6``.
+
+
+.. function:: crc32(string[, value])
+
+ .. index::
+ single: Cyclic Redundancy Check
+ single: checksum; Cyclic Redundancy Check
+
+ Computes a CRC (Cyclic Redundancy Check) checksum of *string*. If *value* is
+ present, it is used as the starting value of the checksum; otherwise, a fixed
+ default value is used. This allows computing a running checksum over the
+ concatenation of several input strings. The algorithm is not cryptographically
+ strong, and should not be used for authentication or digital signatures. Since
+ the algorithm is designed for use as a checksum algorithm, it is not suitable
+ for use as a general hash algorithm.
+
+ This function always returns an integer object.
+
+ .. versionchanged:: 2.6
+ For consistent cross-platform behavior we always return a signed integer.
+ ie: Results in the (2**31)...(2**32-1) range will be negative.
+
+
+.. function:: decompress(string[, wbits[, bufsize]])
+
+ Decompresses the data in *string*, returning a string containing the
+ uncompressed data. The *wbits* parameter controls the size of the window
+ buffer. If *bufsize* is given, it is used as the initial size of the output
+ buffer. Raises the :exc:`error` exception if any error occurs.
+
+ The absolute value of *wbits* is the base two logarithm of the size of the
+ history buffer (the "window size") used when compressing data. Its absolute
+ value should be between 8 and 15 for the most recent versions of the zlib
+ library, larger values resulting in better compression at the expense of greater
+ memory usage. The default value is 15. When *wbits* is negative, the standard
+ :program:`gzip` header is suppressed; this is an undocumented feature of the
+ zlib library, used for compatibility with :program:`unzip`'s compression file
+ format.
+
+ *bufsize* is the initial size of the buffer used to hold decompressed data. If
+ more space is required, the buffer size will be increased as needed, so you
+ don't have to get this value exactly right; tuning it will only save a few calls
+ to :cfunc:`malloc`. The default size is 16384.
+
+
+.. function:: decompressobj([wbits])
+
+ Returns a decompression object, to be used for decompressing data streams that
+ won't fit into memory at once. The *wbits* parameter controls the size of the
+ window buffer.
+
+Compression objects support the following methods:
+
+
+.. method:: Compress.compress(string)
+
+ Compress *string*, returning a string containing compressed data for at least
+ part of the data in *string*. This data should be concatenated to the output
+ produced by any preceding calls to the :meth:`compress` method. Some input may
+ be kept in internal buffers for later processing.
+
+
+.. method:: Compress.flush([mode])
+
+ All pending input is processed, and a string containing the remaining compressed
+ output is returned. *mode* can be selected from the constants
+ :const:`Z_SYNC_FLUSH`, :const:`Z_FULL_FLUSH`, or :const:`Z_FINISH`,
+ defaulting to :const:`Z_FINISH`. :const:`Z_SYNC_FLUSH` and
+ :const:`Z_FULL_FLUSH` allow compressing further strings of data, while
+ :const:`Z_FINISH` finishes the compressed stream and prevents compressing any
+ more data. After calling :meth:`flush` with *mode* set to :const:`Z_FINISH`,
+ the :meth:`compress` method cannot be called again; the only realistic action is
+ to delete the object.
+
+
+.. method:: Compress.copy()
+
+ Returns a copy of the compression object. This can be used to efficiently
+ compress a set of data that share a common initial prefix.
+
+ .. versionadded:: 2.5
+
+Decompression objects support the following methods, and two attributes:
+
+
+.. attribute:: Decompress.unused_data
+
+ A string which contains any bytes past the end of the compressed data. That is,
+ this remains ``""`` until the last byte that contains compression data is
+ available. If the whole string turned out to contain compressed data, this is
+ ``""``, the empty string.
+
+ The only way to determine where a string of compressed data ends is by actually
+ decompressing it. This means that when compressed data is contained part of a
+ larger file, you can only find the end of it by reading data and feeding it
+ followed by some non-empty string into a decompression object's
+ :meth:`decompress` method until the :attr:`unused_data` attribute is no longer
+ the empty string.
+
+
+.. attribute:: Decompress.unconsumed_tail
+
+ A string that contains any data that was not consumed by the last
+ :meth:`decompress` call because it exceeded the limit for the uncompressed data
+ buffer. This data has not yet been seen by the zlib machinery, so you must feed
+ it (possibly with further data concatenated to it) back to a subsequent
+ :meth:`decompress` method call in order to get correct output.
+
+
+.. method:: Decompress.decompress(string[, max_length])
+
+ Decompress *string*, returning a string containing the uncompressed data
+ corresponding to at least part of the data in *string*. This data should be
+ concatenated to the output produced by any preceding calls to the
+ :meth:`decompress` method. Some of the input data may be preserved in internal
+ buffers for later processing.
+
+ If the optional parameter *max_length* is supplied then the return value will be
+ no longer than *max_length*. This may mean that not all of the compressed input
+ can be processed; and unconsumed data will be stored in the attribute
+ :attr:`unconsumed_tail`. This string must be passed to a subsequent call to
+ :meth:`decompress` if decompression is to continue. If *max_length* is not
+ supplied then the whole input is decompressed, and :attr:`unconsumed_tail` is an
+ empty string.
+
+
+.. method:: Decompress.flush([length])
+
+ All pending input is processed, and a string containing the remaining
+ uncompressed output is returned. After calling :meth:`flush`, the
+ :meth:`decompress` method cannot be called again; the only realistic action is
+ to delete the object.
+
+ The optional parameter *length* sets the initial size of the output buffer.
+
+
+.. method:: Decompress.copy()
+
+ Returns a copy of the decompression object. This can be used to save the state
+ of the decompressor midway through the data stream in order to speed up random
+ seeks into the stream at a future point.
+
+ .. versionadded:: 2.5
+
+
+.. seealso::
+
+ Module :mod:`gzip`
+ Reading and writing :program:`gzip`\ -format files.
+
+ http://www.zlib.net
+ The zlib library home page.
+
+ http://www.zlib.net/manual.html
+ The zlib manual explains the semantics and usage of the library's many
+ functions.
+