.unused_data is really a red herring; the PyZlib_objdecompress()
loops until zst->avail_in is zero,  so .unused_data must always be zero by definition.  (The attribute is there to support gzip-format files that may contain multiple compressed streams concatenated together.)

I still have no idea what the documentation should say; "don't pass more than 16K of  compressed data when you're expecting a sync-flush."  I can't see a way to explain this coherently without a big long explanation that will confuse people who don't care about this problem.  (Add a special note, or known bugs subsection, maybe?)

A simple C test program should be written, in order to check if it's 
the zlib library itself that's doing this.