Clarify `max_length` in zstd & zlib decompressor documentation (#143805)

Also provide examples of how to decompress data using max_length for zstd and zlib.

Co-authored-by: Emma Smith <emma@emmatyping.dev>

diff --git a/Doc/library/compression.zstd.rst b/Doc/library/compression.zstd.rst
index 7ca843f27f5e9a602f5b63a313358e81f86c8cac..6d99e36e1e5bb6502d46c8f93a4d84d0f610b24b 100644 (file)
--- a/Doc/library/compression.zstd.rst
+++ b/Doc/library/compression.zstd.rst
@@ -331,10 +331,14 @@ Compressing and decompressing data in memory
 
       If *max_length* is non-negative, the method returns at most *max_length*
       bytes of decompressed data. If this limit is reached and further
-      output can be produced, the :attr:`~.needs_input` attribute will
-      be set to ``False``. In this case, the next call to
+      output can be produced (or EOF is reached), the :attr:`~.needs_input`
+      attribute will be set to ``False``. In this case, the next call to
       :meth:`~.decompress` may provide *data* as ``b''`` to obtain
-      more of the output.
+      more of the output. The full content can thus be read like::
+
+        process_output(d.decompress(data, max_length))
+        while not d.eof and not d.needs_input:
+            process_output(d.decompress(b"", max_length))
 
       If all of the input data was decompressed and returned (either
       because this was less than *max_length* bytes, or because

diff --git a/Doc/library/zlib.rst b/Doc/library/zlib.rst
index ce0a22b9456d0b1f7d1793cf1582647238a35691..f043915c0f4b94ed7fcd62e5a77c380513db981b 100644 (file)
--- a/Doc/library/zlib.rst
+++ b/Doc/library/zlib.rst
@@ -308,6 +308,11 @@ Decompression objects support the following methods and attributes:
    :attr:`unconsumed_tail`. This bytestring must be passed to a subsequent call to
    :meth:`decompress` if decompression is to continue.  If *max_length* is zero
    then the whole input is decompressed, and :attr:`unconsumed_tail` is empty.
+   For example, the full content could be read like::
+
+     process_output(d.decompress(data, max_length))
+     while chunk := d.decompress(d.unconsumed_tail, max_length):
+         process_output(chunk)
 
    .. versionchanged:: 3.6
       *max_length* can be used as a keyword argument.