[Python-checkins] cpython: Document the rest of zlib.compressobj()'s arguments.

[nadeem.vawda]

http://hg.python.org/cpython/rev/1cfa44cb5af0
changeset:   77559:1cfa44cb5af0
user:        Nadeem Vawda <nadeem.vawda at gmail.com>
date:        Fri Jun 22 01:40:49 2012 +0200
summary:
  Document the rest of zlib.compressobj()'s arguments.

Original patch by Jim Jewett; see issue 14684.

files:
  Doc/library/zlib.rst |  22 ++++++++++++++++++----
  Misc/ACKS            |   1 +
  Modules/zlibmodule.c |  21 +++++++++++++++++----
  3 files changed, 36 insertions(+), 8 deletions(-)


diff --git a/Doc/library/zlib.rst b/Doc/library/zlib.rst
--- a/Doc/library/zlib.rst
+++ b/Doc/library/zlib.rst
@@ -58,14 +58,28 @@
    exception if any error occurs.
 
 
-.. function:: compressobj([level[, method[, wbits[, memlevel[, strategy[, zdict]]]]]])
+.. function:: compressobj(level=-1, method=DEFLATED, wbits=15, memlevel=8, strategy=Z_DEFAULT_STRATEGY, [zdict])
 
    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``.
+   *level* is the compression level -- an integer from ``1`` to ``9``. A value
+   of ``1`` is fastest and produces the least compression, while a value of
+   ``9`` is slowest and produces the most. The default value is ``6``.
+
+   *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.
+
+   *memlevel* controls the amount of memory used for internal compression state.
+   Valid values range from ``1`` to ``9``. Higher values using more memory,
+   but are faster and produce smaller output.
+
+   *strategy* is used to tune the compression algorithm. Possible values are
+   ``Z_DEFAULT_STRATEGY``, ``Z_FILTERED``, and ``Z_HUFFMAN_ONLY``.
 
    *zdict* is a predefined compression dictionary. This is a sequence of bytes
    (such as a :class:`bytes` object) containing subsequences that are expected
diff --git a/Misc/ACKS b/Misc/ACKS
--- a/Misc/ACKS
+++ b/Misc/ACKS
@@ -503,6 +503,7 @@
 Drew Jenkins
 Flemming Kjær Jensen
 MunSic Jeong
+Jim Jewett
 Orjan Johansen
 Fredrik Johansson
 Gregory K. Johnson
diff --git a/Modules/zlibmodule.c b/Modules/zlibmodule.c
--- a/Modules/zlibmodule.c
+++ b/Modules/zlibmodule.c
@@ -81,13 +81,26 @@
 }
 
 PyDoc_STRVAR(compressobj__doc__,
-"compressobj([level[, method[, wbits[, memlevel[, strategy[, zdict]]]]]])\n"
+"compressobj(level=-1, method=DEFLATED, wbits=15, memlevel=8,\n"
+"            strategy=Z_DEFAULT_STRATEGY[, zdict])\n"
 " -- Return a compressor object.\n"
 "\n"
-"Optional arg level is the compression level, in 1-9.\n"
+"level is the compression level (an integer in the range 0-9; default is 6).\n"
+"Higher compression levels are slower, but produce smaller results.\n"
 "\n"
-"Optional arg zdict is the predefined compression dictionary - a sequence of\n"
-"bytes containing subsequences that are likely to occur in the input data.");
+"method is the compression algorithm. If given, this must be DEFLATED.\n"
+"\n"
+"wbits is the base two logarithm of the window size (range: 8..15).\n"
+"\n"
+"memlevel controls the amount of memory used for internal compression state.\n"
+"Valid values range from 1 to 9. Higher values result in higher memory usage,\n"
+"faster compression, and smaller output.\n"
+"\n"
+"strategy is used to tune the compression algorithm. Possible values are\n"
+"Z_DEFAULT_STRATEGY, Z_FILTERED, and Z_HUFFMAN_ONLY.\n"
+"\n"
+"zdict is the predefined compression dictionary - a sequence of bytes\n"
+"containing subsequences that are likely to occur in the input data.");
 
 PyDoc_STRVAR(decompressobj__doc__,
 "decompressobj([wbits[, zdict]]) -- Return a decompressor object.\n"

-- 
Repository URL: http://hg.python.org/cpython