Stowage/cpython
2
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-12-08 06:10:17 +00:00
Code Issues Projects Releases Packages Wiki Activity

[3.13] zlib.rst: Link to constants and deduplicate text (GH-140115) (GH-140350)

Browse source 
* Link to compression setting constants from compression functions
* De-duplicate descriptions of the constants
(cherry picked from commit 091e8513bb)

Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
Co-authored-by: Victor Stinner <vstinner@python.org>
This commit is contained in:
Emma Smith 2025-10-21 14:45:02 -07:00 • committed by GitHub
parent cd6b272f7a
commit df35beb6de
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 16 additions and 18 deletions
Download patch file Download diff file Expand all files Collapse all files

34
Doc/library/zlib.rst
View file

@ -44,21 +44,20 @@ The available exception and functions in this module are:
.. versionchanged:: 3.0 .. versionchanged:: 3.0
The result is always unsigned. The result is always unsigned.
.. function:: compress(data, /, level=-1, wbits=MAX_WBITS) .. function:: compress(data, /, level=Z_DEFAULT_COMPRESSION, wbits=MAX_WBITS)
Compresses the bytes in *data*, returning a bytes object containing compressed data. Compresses the bytes in *data*, returning a bytes object containing compressed data.
*level* is an integer from ``0`` to ``9`` or ``-1`` controlling the level of compression; *level* is an integer from ``0`` to ``9`` or ``-1`` controlling the level of compression;
``1`` (Z_BEST_SPEED) is fastest and produces the least compression, ``9`` (Z_BEST_COMPRESSION) See :const:`Z_BEST_SPEED` (``1``), :const:`Z_BEST_COMPRESSION` (``9``),
is slowest and produces the most. ``0`` (Z_NO_COMPRESSION) is no compression. :const:`Z_NO_COMPRESSION` (``0``), and the default,
The default value is ``-1`` (Z_DEFAULT_COMPRESSION). Z_DEFAULT_COMPRESSION represents a default :const:`Z_DEFAULT_COMPRESSION` (``-1``) for more information about these values.
compromise between speed and compression (currently equivalent to level 6).
.. _compress-wbits: .. _compress-wbits:
The *wbits* argument controls the size of the history buffer (or the The *wbits* argument controls the size of the history buffer (or the
"window size") used when compressing data, and whether a header and "window size") used when compressing data, and whether a header and
trailer is included in the output. It can take several ranges of values, trailer is included in the output. It can take several ranges of values,
defaulting to ``15`` (MAX_WBITS): defaulting to ``15`` (:const:`MAX_WBITS`):
* +9 to +15: The base-two logarithm of the window size, which * +9 to +15: The base-two logarithm of the window size, which
therefore ranges between 512 and 32768. Larger values produce therefore ranges between 512 and 32768. Larger values produce
@ -82,17 +81,15 @@ The available exception and functions in this module are:
The *wbits* parameter is now available to set window bits and The *wbits* parameter is now available to set window bits and
compression type. compression type.
.. function:: compressobj(level=-1, method=DEFLATED, wbits=MAX_WBITS, memLevel=DEF_MEM_LEVEL, strategy=Z_DEFAULT_STRATEGY[, zdict]) .. function:: compressobj(level=Z_DEFAULT_COMPRESSION, method=DEFLATED, wbits=MAX_WBITS, memLevel=DEF_MEM_LEVEL, strategy=Z_DEFAULT_STRATEGY[, zdict])
Returns a compression object, to be used for compressing data streams that won't Returns a compression object, to be used for compressing data streams that won't
fit into memory at once. fit into memory at once.
*level* is the compression level -- an integer from ``0`` to ``9`` or ``-1``. *level* is the compression level -- an integer from ``0`` to ``9`` or ``-1``.
A value of ``1`` (Z_BEST_SPEED) is fastest and produces the least compression, See :const:`Z_BEST_SPEED` (``1``), :const:`Z_BEST_COMPRESSION` (``9``),
while a value of ``9`` (Z_BEST_COMPRESSION) is slowest and produces the most. :const:`Z_NO_COMPRESSION` (``0``), and the default,
``0`` (Z_NO_COMPRESSION) is no compression. The default value is ``-1`` (Z_DEFAULT_COMPRESSION). :const:`Z_DEFAULT_COMPRESSION` (``-1``) for more information about these values.
Z_DEFAULT_COMPRESSION represents a default compromise between speed and compression
(currently equivalent to level 6).
*method* is the compression algorithm. Currently, the only supported value is *method* is the compression algorithm. Currently, the only supported value is
:const:`DEFLATED`. :const:`DEFLATED`.
@ -107,7 +104,7 @@ The available exception and functions in this module are:
*strategy* is used to tune the compression algorithm. Possible values are *strategy* is used to tune the compression algorithm. Possible values are
:const:`Z_DEFAULT_STRATEGY`, :const:`Z_FILTERED`, :const:`Z_HUFFMAN_ONLY`, :const:`Z_DEFAULT_STRATEGY`, :const:`Z_FILTERED`, :const:`Z_HUFFMAN_ONLY`,
:const:`Z_RLE` (zlib 1.2.0.1) and :const:`Z_FIXED` (zlib 1.2.2.2). :const:`Z_RLE` and :const:`Z_FIXED`.
*zdict* is a predefined compression dictionary. This is a sequence of bytes *zdict* is a predefined compression dictionary. This is a sequence of bytes
(such as a :class:`bytes` object) containing subsequences that are expected (such as a :class:`bytes` object) containing subsequences that are expected
@ -221,7 +218,7 @@ Compression objects support the following methods:
All pending input is processed, and a bytes object containing the remaining compressed All pending input is processed, and a bytes object containing the remaining compressed
output is returned. *mode* can be selected from the constants output is returned. *mode* can be selected from the constants
:const:`Z_NO_FLUSH`, :const:`Z_PARTIAL_FLUSH`, :const:`Z_SYNC_FLUSH`, :const:`Z_NO_FLUSH`, :const:`Z_PARTIAL_FLUSH`, :const:`Z_SYNC_FLUSH`,
:const:`Z_FULL_FLUSH`, :const:`Z_BLOCK` (zlib 1.2.3.4), or :const:`Z_FINISH`, :const:`Z_FULL_FLUSH`, :const:`Z_BLOCK`, or :const:`Z_FINISH`,
defaulting to :const:`Z_FINISH`. Except :const:`Z_FINISH`, all constants defaulting to :const:`Z_FINISH`. Except :const:`Z_FINISH`, all constants
allow compressing further bytestrings of data, while :const:`Z_FINISH` finishes the allow compressing further bytestrings of data, while :const:`Z_FINISH` finishes the
compressed stream and prevents compressing any more data. After calling :meth:`flush` compressed stream and prevents compressing any more data. After calling :meth:`flush`
@ -339,24 +336,25 @@ behavior:
.. data:: Z_NO_COMPRESSION .. data:: Z_NO_COMPRESSION
Compression level ``0``. Compression level ``0``; no compression.
.. versionadded:: 3.6 .. versionadded:: 3.6
.. data:: Z_BEST_SPEED .. data:: Z_BEST_SPEED
Compression level ``1``. Compression level ``1``; fastest and produces the least compression.
.. data:: Z_BEST_COMPRESSION .. data:: Z_BEST_COMPRESSION
Compression level ``9``. Compression level ``9``; slowest and produces the most compression.
.. data:: Z_DEFAULT_COMPRESSION .. data:: Z_DEFAULT_COMPRESSION
Default compression level (``-1``). Default compression level (``-1``); a compromise between speed and
compression. Currently equivalent to compression level ``6``.
.. data:: Z_DEFAULT_STRATEGY .. data:: Z_DEFAULT_STRATEGY