Issue #13989: Document that GzipFile does not support text mode.

Also, give a more helpful error message when opened with an invalid mode string.

diff --git a/Doc/library/gzip.rst b/Doc/library/gzip.rst
index 8aca2dd95641974afa369a7193ac1a6419a01f06..9422ea9943a217208fd76606afd84a085dbe2084 100644 (file)
--- a/Doc/library/gzip.rst
+++ b/Doc/library/gzip.rst
@@ -44,9 +44,11 @@ The module defines the following items:
 
    The *mode* argument can be any of ``'r'``, ``'rb'``, ``'a'``, ``'ab'``, ``'w'``,
    or ``'wb'``, depending on whether the file will be read or written.  The default
-   is the mode of *fileobj* if discernible; otherwise, the default is ``'rb'``. If
-   not given, the 'b' flag will be added to the mode to ensure the file is opened
-   in binary mode for cross-platform portability.
+   is the mode of *fileobj* if discernible; otherwise, the default is ``'rb'``.
+
+   Note that the file is always opened in binary mode; text mode is not
+   supported. If you need to read a compressed file in text mode, wrap your
+   :class:`GzipFile` with an :class:`io.TextIOWrapper`.
 
    The *compresslevel* argument is an integer from ``1`` to ``9`` controlling the
    level of compression; ``1`` is fastest and produces the least compression, and

diff --git a/Lib/gzip.py b/Lib/gzip.py
index 4462187116df35bb4629a659fcf9936a40b9fbc5..1de23b6972f203c954c712da504d757838adfc58 100644 (file)
--- a/Lib/gzip.py
+++ b/Lib/gzip.py
@@ -105,6 +105,9 @@ class GzipFile(io.BufferedIOBase):
     """The GzipFile class simulates most of the methods of a file object with
     the exception of the readinto() and truncate() methods.
 
+    This class only supports opening files in binary mode. If you need to open a
+    compressed file in text mode, wrap your GzipFile with an io.TextIOWrapper.
+
     """
 
     myfileobj = None
@@ -131,8 +134,8 @@ class GzipFile(io.BufferedIOBase):
         The mode argument can be any of 'r', 'rb', 'a', 'ab', 'w', or 'wb',
         depending on whether the file will be read or written.  The default
         is the mode of fileobj if discernible; otherwise, the default is 'rb'.
-        Be aware that only the 'rb', 'ab', and 'wb' values should be used
-        for cross-platform portability.
+        A mode of 'r' is equivalent to one of 'rb', and similarly for 'w' and
+        'wb', and 'a' and 'ab'.
 
         The compresslevel argument is an integer from 1 to 9 controlling the
         level of compression; 1 is fastest and produces the least compression,
@@ -149,8 +152,8 @@ class GzipFile(io.BufferedIOBase):
 
         """
 
-        # guarantee the file is opened in binary mode on platforms
-        # that care about that sort of thing
+        if mode and ('t' in mode or 'U' in mode):
+            raise IOError("Mode " + mode + " not supported")
         if mode and 'b' not in mode:
             mode += 'b'
         if fileobj is None:

diff --git a/Misc/NEWS b/Misc/NEWS
index da90e9e16bb7c57a01a9f9347c38c77a1d2721a8..f45da7596eb34ccb471e1c46714a33f78d059991 100644 (file)
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -113,6 +113,9 @@ Core and Builtins
 Library
 -------
 
+- Issue #13989: Document that GzipFile does not support text mode, and give a
+  more helpful error message when opened with an invalid mode string.
+
 - Issue #13590: On OS X 10.7 and 10.6 with Xcode 4.2, building
   Distutils-based packages with C extension modules may fail because
   Apple has removed gcc-4.2, the version used to build python.org