While trying to implement some decompression code,
(from reading the docs), I believed this was appropriate
code:

    dco = zlib.decompressionobj()
    for bytes in compressed_data:
        s = dco.decompress(bytes, limit)
        while s:
             handle_some_data(s)
             s = dco.decompress('', limit)

After eventually chasing back through the test_zlib.py
code, I now believe the proper analog of this code 
should be:

    dco = zlib.decompressionobj()
    for bytes in compressed_data:
        s = dco.decompress(bytes, limit)
        while s:
             handle_some_data(s)
             s = dco.decompress(
                      dco.unconsumed_tail,
                      limit)

The meaning of both unconsumed_tail and 
unused_data need a it of explanation in the docs.

Logged In: YES 
user_id=493818

Here is some alternative text, with a bit more explanation.

\begin{memberdesc}{unused_data}
A string which contains any bytes past the end of the
compressed data.
That is, this remains \code{""} until the last byte that
contains compression data is available.  If the whole string
turned
out to contain compressed data, this is \code{""}, 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 \method{decompress} method until the 
\member{unused_data} attribute is no longer the empty string.  
\end{memberdesc}

\begin{memberdesc}{unconsumed_tail}
A string that contains any data that was not consumed by the
last
\method{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 \method{decompress}
method 
call in order to get correct output.
\end{memberdesc}

Logged In: YES 
user_id=357491

I don't see much of a difference between the current docs for unused_data 
and the ones Scott posted here.  unused_tail does seem to be more 
informative.  I have no issue addding the extra info that Scott added in his 
version.  Anyone else think it is worth adding?

Since the comment basically has a patch, I am making this tracker item a 
patch.

Logged In: YES 
user_id=21627

Thanks for the patch, committed as libzlib.tex 1.28.