GzipFile.peek improvements, suggested by Nir Aides.

Doc/library/gzip.rst

@@ -70,6 +70,17 @@ The module defines the following items:
    including iteration and the :keyword:`with` statement.  Only the
    :meth:`truncate` method isn't implemented.
 
+   :class:`GzipFile` also provides the following method:
+
+   .. method:: peek([n])
+
+      Read *n* uncompressed bytes without advancing the file position.
+      At most one single read on the compressed stream is done to satisfy
+      the call.  The number of bytes returned may be more or less than
+      requested.
+
+      .. versionadded:: 3.2
+
    .. versionchanged:: 3.1
       Support for the :keyword:`with` statement was added.
 
@@ -79,9 +90,6 @@ The module defines the following items:
    .. versionchanged:: 3.2
       Support for unseekable files was added.
 
-   .. versionchanged:: 3.2
-      The :meth:`peek` method was implemented.
-
 
 .. function:: open(filename, mode='rb', compresslevel=9)
 

Lib/gzip.py

@@ -342,16 +342,18 @@ class GzipFile(io.BufferedIOBase):
     def peek(self, n):
         if self.mode != READ:
             import errno
-            raise IOError(errno.EBADF, "read() on write-only GzipFile object")
+            raise IOError(errno.EBADF, "peek() on write-only GzipFile object")
 
-        # Do not return ridiculously small buffers
+        # Do not return ridiculously small buffers, for one common idiom
+        # is to call peek(1) and expect more bytes in return.
         if n < 100:
             n = 100
         if self.extrasize == 0:
             if self.fileobj is None:
                 return b''
             try:
-                self._read(max(self.max_read_chunk, n))
+                # 1024 is the same buffering heuristic used in read()
+                self._read(max(n, 1024))
             except EOFError:
                 pass
         offset = self.offset - self.extrastart