combined patches from http://bugs.python.org/issue3187

Lib/io.py

 """The io module provides the Python interfaces to stream handling. The
 builtin open function is defined in this module.
 
 At the top of the I/O hierarchy is the abstract base class IOBase. It
 defines the basic interface to a stream. Note, however, that there is no
 seperation between reading and writing to streams; implementations are
 allowed to throw an IOError if they do not support a given operation.
 
 Extending IOBase is RawIOBase which deals simply with the reading and
 writing of raw bytes to a stream. FileIO subclasses RawIOBase to provide
@@ skipping 64 matching lines @@
     """Exception raised when I/O would block on a non-blocking I/O stream."""
 
     def __init__(self, errno, strerror, characters_written=0):
         IOError.__init__(self, errno, strerror)
         self.characters_written = characters_written
 
 
 def open(file, mode="r", buffering=None, encoding=None, errors=None,
          newline=None, closefd=True):
 
-    r"""Open file and return a stream. If the file cannot be opened, an IOError is
-    raised.
-
-    file is either a string giving the name (and the path if the file
-    isn't in the current working directory) of the file to be opened or an
-    integer file descriptor of the file to be wrapped. (If a file
-    descriptor is given, it is closed when the returned I/O object is
-    closed, unless closefd is set to False.)
+    r"""Open file and return a stream.  Raise IOError upon failure.
+
+    file is either a text or byte string giving the name (and the path
+    if the file isn't in the current working directory) of the file to
+    be opened or an integer file descriptor of the file to be
+    wrapped. (If a file descriptor is given, it is closed when the
+    returned I/O object is closed, unless closefd is set to False.)
 
     mode is an optional string that specifies the mode in which the file
     is opened. It defaults to 'r' which means open for reading in text
     mode.  Other common values are 'w' for writing (truncating the file if
     it already exists), and 'a' for appending (which on some Unix systems,
     means that all writes append to the end of the file regardless of the
     current seek position). In text mode, if encoding is not specified the
     encoding used is platform dependent. (For reading and writing raw
     bytes use binary mode and leave encoding unspecified.) The available
     modes are:
@@ skipping 70 matching lines @@
     a file in a binary mode, the returned class varies: in read binary
     mode, it returns a BufferedReader; in write binary and append binary
     modes, it returns a BufferedWriter, and in read/write mode, it returns
     a BufferedRandom.
 
     It is also possible to use a string or bytearray as a file for both
     reading and writing. For strings StringIO can be used like a file
     opened in a text mode, and for bytes a BytesIO can be used like a file
     opened in a binary mode.
     """
     if not isinstance(file, (str, bytes, int)):

[GvR, 2008/08/22 19:04:51]

Good catch.  However I'm not sure if the file is allowed to be a bytes instance
on Windows...

         raise TypeError("invalid file: %r" % file)
     if not isinstance(mode, str):
         raise TypeError("invalid mode: %r" % mode)
     if buffering is not None and not isinstance(buffering, int):
         raise TypeError("invalid buffering: %r" % buffering)
     if encoding is not None and not isinstance(encoding, str):
         raise TypeError("invalid encoding: %r" % encoding)
     if errors is not None and not isinstance(errors, str):
         raise TypeError("invalid errors: %r" % errors)
     modes = set(mode)
@@ skipping 1933 matching lines @@
                     ("\r", "\n"),
                     "\r\n",
                     ("\n", "\r\n"),
                     ("\r", "\r\n"),
                     ("\r", "\n", "\r\n")
                    )[self._seennl]
 
 
 except ImportError:
     StringIO = _StringIO