mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-08-03 16:39:00 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

Issue #5784: Expand documentation and tests for zlib wbits parameter

Browse source 
Based on documentation by AM Kuchling.
This commit is contained in:
Martin Panter 2016-05-27 07:32:11 +00:00
parent 06198789a2
commit 0fdf41d847
4 changed files with 108 additions and 25 deletions
Download patch file Download diff file Expand all files Collapse all files

62
Doc/library/zlib.rst
View file

@ -69,9 +69,22 @@ The available exception and functions in this module are:
*method* is the compression algorithm. Currently, the only supported value is
``DEFLATED``.
*wbits* is the base two logarithm of the size of the window buffer. This
should be an integer from ``8`` to ``15``. Higher values give better
compression, but use more memory.
The *wbits* argument controls the size of the history buffer (or the
"window size") used when compressing data, and whether a header and
trailer is included in the output. It can take several ranges of values:
* +9 to +15: The base-two logarithm of the window size, which
therefore ranges between 512 and 32768. Larger values produce
better compression at the expense of greater memory usage. The
resulting output will include a zlib-specific header and trailer.
* −9 to −15: Uses the absolute value of *wbits* as the
window size logarithm, while producing a raw output stream with no
header or trailing checksum.
* +25 to +31 = 16 + (9 to 15): Uses the low 4 bits of the value as the
window size logarithm, while including a basic :program:`gzip` header
and trailing checksum in the output.
The *memLevel* argument controls the amount of memory used for the
internal compression state. Valid values range from ``1`` to ``9``.
@ -113,20 +126,39 @@ The available exception and functions in this module are:
.. function:: decompress(data[, wbits[, bufsize]])
Decompresses the bytes in *data*, returning a bytes object containing the
uncompressed data. The *wbits* parameter controls the size of the window
buffer, and is discussed further below.
uncompressed data. The *wbits* parameter depends on
the format of *data*, and is discussed further below.
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. When decompressing a stream, *wbits* must not be smaller
.. _decompress-wbits:
The *wbits* parameter controls the size of the history buffer
(or "window size"), and what header and trailer format is expected.
It is similar to the parameter for :func:`compressobj`, but accepts
more ranges of values:
* +8 to +15: The base-two logarithm of the window size. The input
must include a zlib header and trailer.
* 0: Automatically determine the window size from the zlib header.
* −8 to −15: Uses the absolute value of *wbits* as the window size
logarithm. The input must be a raw stream with no header or trailer.
* +24 to +31 = 16 + (8 to 15): Uses the low 4 bits of the value as
the window size logarithm. The input must include a gzip header and
trailer.
* +40 to +47 = 32 + (8 to 15): Uses the low 4 bits of the value as
the window size logarithm, and automatically accepts either
the zlib or gzip format.
When decompressing a stream, the window size must not be smaller
than the size originally used to compress the stream; using a too-small
value will result in an exception. The default value is therefore the
highest value, 15. When *wbits* is negative, the standard
:program:`gzip` header is suppressed.
value may result in an :exc:`error` exception. The default *wbits* value
is 15, which corresponds to the largest window size and requires a zlib
header and trailer to be included.
*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
@ -139,7 +171,9 @@ The available exception and functions in this module are:
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.
The *wbits* parameter controls the size of the history buffer (or the
"window size"), and what header and trailer format is expected. It has
the same meaning as `described for decompress() <#decompress-wbits>`__.
The *zdict* parameter specifies a predefined compression dictionary. If
provided, this must be the same dictionary as was used by the compressor that