From the documentation for GzipFile.peek():

    At most one single read on the compressed stream is done to satisfy the call.

If "compressed stream" means the underlying file object, then this is not true. The method tries to return at least one byte, unless the stream is at EOF. It is possible to create arbitrarily long compressed stream that would decompress to nothing, and the implementation would read the entire stream in this case. Because the length of the stream is not known in advance, several reads may be required for this.

Perhaps the documentation for GzipFile.peek() should be made the same as that for BZ2File.peek() and LZMAFile.peek().

The "compressed stream" is not the underlying file object but _GzipReader. And actually the "at most one single reader" is the characteristic of io.BufferedReader.peek, you can see it in the doc. Maybe it needs multiple reads on the file object in a single peek, but they are all encapsulated in the _GzipReader.read. So at the point of GzipFile.peek, it's still a single read.

The peek() method was originally added by Issue 9962, where Antoine was trying to imitate the BufferedReader.peek() API. However because “the number of bytes returned may be more or less than requested”, I never understood what this methods were good for; see also Issue 5811.

I think we could at least remove the claim about “at most one single read”. That is just describing an internal detail.

The documentation for bzip and LZMA is slightly more useful IMO because it says “at least one byte of data will be returned, unless EOF has been reached”. This guarantee is actually missing from the underlying BufferedReader.peek() documentation, though I think both io and _pyio implement it.