Synced builtin open and io.open documentation, taking the best of each

2 files changed, 121 insertions, 102 deletions

diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index af66267..8fa027c 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -698,94 +698,89 @@ available.  They are listed here in alphabetical order.
    :meth:`__index__` method that returns an integer.
 
 
-.. function:: open(filename[, mode='r'[, buffering=None[, encoding=None[, errors=None[, newline=None[, closefd=True]]]]]])
+.. function:: open(file[, mode='r'[, buffering=None[, encoding=None[, errors=None[, newline=None[, closefd=True]]]]]])
 
-   Open a file, returning an object of the :class:`file` type described in
-   section :ref:`bltin-file-objects`.  If the file cannot be opened,
-   :exc:`IOError` is raised.  When opening a file, it's preferable to use
-   :func:`open` instead of invoking the :class:`file` constructor directly.
+   Open a file.  If the file cannot be opened, :exc:`IOError` is raised.
    
-   *filename* 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``.)
+   *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``.)
 
    *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:
-
-   * 'r' open for reading (default)
-   * 'w' open for writing, truncating the file first
-   * 'a' open for writing, appending to the end if the file exists
-   * 'b' binary mode
-   * 't' text mode (default)
-   * '+' open the file for updating (implies both reading and writing)
-   * 'U' universal newline mode (for backwards compatibility;
-     unnecessary in new code)
-
-   The most commonly-used values of *mode* are ``'r'`` for reading, ``'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).  If *mode* is omitted, it
-   defaults to ``'r'``.  The default is to use text mode, which may convert
-   ``'\n'`` characters to a platform-specific representation on writing and back
-   on reading.  Thus, when opening a binary file, you should append ``'b'`` to
-   the *mode* value to open the file in binary mode, which will improve
-   portability.  (Appending ``'b'`` is useful even on systems that don't treat
-   binary and text files differently, where it serves as documentation.)  See below
-   for more possible values of *mode*.
+   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:
+
+   ========= ===============================================================
+   Character Meaning
+   --------- ---------------------------------------------------------------
+   ``'r'``   open for reading (default)
+   ``'w'``   open for writing, truncating the file first
+   ``'a'``   open for writing, appending to the end of the file if it exists
+   ``'b'``   binary mode
+   ``'t'``   text mode (default)
+   ``'+'``   open a disk file for updating (reading and writing)
+   ``'U'``   universal newline mode (for backwards compatibility; unneeded
+             for new code)
+   ========= ===============================================================
+
+   The default mode is ``'rt'`` (open for reading text).  For binary random
+   access, the mode ``'w+b'`` opens and truncates the file to 0 bytes, while
+   ``'r+b'`` opens the file without truncation.
 
    Python distinguishes between files opened in binary and text modes, even
    when the underlying operating system doesn't.  Files opened in binary
    mode (appending ``'b'`` to the *mode* argument) return contents as
-   ``bytes`` objects without any decoding.  In text mode (the default,
-   or when ``'t'`` is appended to the *mode* argument) the contents of
+   ``bytes`` objects without any decoding.  In text mode (the default, or when
+   ``'t'`` is appended to the *mode* argument) the contents of
    the file are returned as strings, the bytes having been first decoded
    using a platform-dependent encoding or using the specified *encoding*
    if given.
 
-   *buffering* is an optional integer used to set the buffering policy. By
-   default full buffering is on. Pass 0 to switch buffering off (only
-   allowed in binary mode), 1 to set line buffering, and an integer > 1
-   for full buffering.
+   *buffering* is an optional integer used to set the buffering policy.  By
+   default full buffering is on. Pass 0 to switch buffering off (only allowed in
+   binary mode), 1 to set line buffering, and an integer > 1 for full buffering.
     
-   *encoding* is an optional string that specifies the file's encoding when
-   reading or writing in text mode---this argument should not be used in
-   binary mode. The default encoding is platform dependent, but any encoding
-   supported by Python can be used. (See the :mod:`codecs` module for
-   the list of supported encodings.)
+   *encoding* is the name of the encoding used to decode or encode the file.
+   This should only be used in text mode.  The default encoding is platform
+   dependent, but any encoding supported by Python can be passed.  See the
+   :mod:`codecs` module for the list of supported encodings.
 
    *errors* is an optional string that specifies how encoding errors are to be
-   handled---this argument should not be used in binary mode. Pass
-   ``'strict'`` to raise a :exc:`ValueError` exception if there is an encoding
-   error (the default of ``None`` has the same effect), or pass ``'ignore'``
-   to ignore errors. (Note that ignoring encoding errors can lead to
-   data loss.) See the documentation for :func:`codecs.register` for a
-   list of the permitted encoding error strings.
-
-   *newline* is an optional string that specifies the newline character(s).
-   When reading, if *newline* is ``None``, universal newlines mode is enabled.
-   Lines read in univeral newlines mode can end in ``'\n'``, ``'\r'``,
-   or ``'\r\n'``, and these are translated into ``'\n'``. If *newline*
-   is ``''``, universal newline mode is enabled, but line endings are
-   not translated. If any other string is given, lines are assumed to be
-   terminated by that string, and no translating is done. When writing,
-   if *newline* is ``None``, any ``'\n'`` characters written are
-   translated to the system default line separator, :attr:`os.linesep`.
-   If *newline* is ``''``, no translation takes place. If *newline* is
-   any of the other standard values, any ``'\n'`` characters written are
-   translated to the given string.
-
-   *closefd* is an optional Boolean which specifies whether to keep the
-   underlying file descriptor open. It must be ``True`` (the default) if
-   a filename is given.
+   handled---this argument should not be used in binary mode. Pass ``'strict'``
+   to raise a :exc:`ValueError` exception if there is an encoding error (the
+   default of ``None`` has the same effect), or pass ``'ignore'`` to ignore
+   errors. (Note that ignoring encoding errors can lead to data loss.) See the
+   documentation for :func:`codecs.register` for a list of the permitted
+   encoding error strings.
+
+   *newline* controls how universal newlines works (it only applies to text
+   mode).  It can be ``None``, ``''``, ``'\n'``, ``'\r'``, and ``'\r\n'``.  It
+   works as follows:
+
+   * On input, if *newline* is ``None``, universal newlines mode is enabled.
+     Lines in the input can end in ``'\n'``, ``'\r'``, or ``'\r\n'``, and these
+     are translated into ``'\n'`` before being returned to the caller.  If it is
+     ``''``, universal newline mode is enabled, but line endings are returned to
+     the caller untranslated.  If it has any of the other legal values, input
+     lines are only terminated by the given string, and the line ending is
+     returned to the caller untranslated.
+
+   * On output, if *newline* is ``None``, any ``'\n'`` characters written are
+     translated to the system default line separator, :data:`os.linesep`.  If
+     *newline* is ``''``, no translation takes place.  If *newline* is any of
+     the other legal values, any ``'\n'`` characters written are translated to
+     the given string.
+
+   If *closefd* is ``False``, the underlying file descriptor will be kept open
+   when the file is closed.  This does not work when a file name is given and
+   must be ``True`` in that case.
 
    .. index::
       single: line-buffered I/O
@@ -796,9 +791,9 @@ available.  They are listed here in alphabetical order.
       single: text mode
       module: sys
 
-   See also the file handling modules, such as,
-   :mod:`fileinput`, :mod:`os`, :mod:`os.path`, :mod:`tempfile`, and
-   :mod:`shutil`.
+   See also the file handling modules, such as, :mod:`fileinput`, :mod:`io`
+   (where :func:`open()` is declared), :mod:`os`, :mod:`os.path`,
+   :mod:`tempfile`, and :mod:`shutil`.
 
 
 .. XXX works for bytes too, but should it?
diff --git a/Doc/library/io.rst b/Doc/library/io.rst
index a3e492e..224738f 100644
--- a/Doc/library/io.rst
+++ b/Doc/library/io.rst
@@ -44,13 +44,23 @@ Module Interface
 
 .. function:: open(file[, mode[, buffering[, encoding[, errors[, newline[, closefd=True]]]]]])
 
-   Open *file* and return a stream.
-
-   *file* is a string giving the name of the file, or an integer file descriptor
-   of the file to be wrapped.
-
-   The optional *mode* string determines how the file is opened and consists of
-   a combination of the following characters:
+   Open *file* and return a stream.  If the file cannot be opened, an
+   :exc:`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``.)
+
+   *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:
 
    ========= ===============================================================
    Character Meaning
@@ -69,18 +79,31 @@ Module Interface
    access, the mode ``'w+b'`` opens and truncates the file to 0 bytes, while
    ``'r+b'`` opens the file without truncation.
 
-   *buffering* is an optional argument controling the buffering of the returned
-   stream.  A value of ``0`` means no buffering, ``1`` means line buffered, and
-   a greater value means full buffering with the given buffer size.  Buffering
-   cannot be disabled in text mode.
+   Python distinguishes between files opened in binary and text modes, even
+   when the underlying operating system doesn't.  Files opened in binary
+   mode (appending ``'b'`` to the *mode* argument) return contents as
+   ``bytes`` objects without any decoding.  In text mode (the default, or when
+   ``'t'`` is appended to the *mode* argument) the contents of
+   the file are returned as strings, the bytes having been first decoded
+   using a platform-dependent encoding or using the specified *encoding*
+   if given.
 
-   *encoding* is the name of the encoding used to decode or encode the file.
-   This may only be used in text mode.  Any encoding available in the
-   :mod:`codecs` module registry can be used.
+   *buffering* is an optional integer used to set the buffering policy.  By
+   default full buffering is on. Pass 0 to switch buffering off (only allowed in
+   binary mode), 1 to set line buffering, and an integer > 1 for full buffering.
 
-   *errors* specifies how the encoding should treat errors.  "strict", the
-   default raises a :exc:`ValueError` on problems.  See the *errors* argument
-   of :func:`codecs.open` for more information. XXX
+   *encoding* is the name of the encoding used to decode or encode the file.
+   This should only be used in text mode.  The default encoding is platform
+   dependent, but any encoding supported by Python can be passed.  See the
+   :mod:`codecs` module for the list of supported encodings.
+
+   *errors* is an optional string that specifies how encoding errors are to be
+   handled---this argument should not be used in binary mode.  Pass ``'strict'``
+   to raise a :exc:`ValueError` exception if there is an encoding error (the
+   default of ``None`` has the same effect), or pass ``'ignore'`` to ignore
+   errors.  (Note that ignoring encoding errors can lead to data loss.)  See the
+   documentation for :func:`codecs.register` for a list of the permitted
+   encoding error strings.
 
    *newline* controls how universal newlines works (it only applies to text
    mode).  It can be ``None``, ``''``, ``'\n'``, ``'\r'``, and ``'\r\n'``.  It
@@ -100,13 +123,14 @@ Module Interface
      the other legal values, any ``'\n'`` characters written are translated to
      the given string.
 
-   If *closefd* is :keyword:`False`, the underlying file descriptor will be kept
-   open when the file is closed.  This does not work when a file name is given.
+   If *closefd* is ``False``, the underlying file descriptor will be kept open
+   when the file is closed.  This does not work when a file name is given and
+   must be ``True`` in that case.
 
-   The :func:`open` function returns a file object whose type depends on the
-   mode, and through which the standard file operations such as reading and
-   writing are performed.  When :func:`open` is used to open a file in a text
-   mode (``'w'``, ``'r'``, ``'wt'``, ``'rt'``, etc.), it returns a
+   :func:`open()` returns a file object whose type depends on the mode, and
+   through which the standard file operations such as reading and writing are
+   performed.  When :func:`open()` is used to open a file in a text mode
+   (``'w'``, ``'r'``, ``'wt'``, ``'rt'``, etc.), it returns a
    :class:`TextIOWrapper`.  When used to open a file in a binary mode, the
    returned class varies: in read binary mode, it returns a
    :class:`BufferedReader`; in write binary and append binary modes, it returns
@@ -114,9 +138,9 @@ Module Interface
    :class:`BufferedRandom`.
 
    It is also possible to use a string or bytearray as a file for both reading
-   and writing.  For strings :class:`io.StringIO` can be used like a file opened
-   in a text mode, and for bytes a :class:`io.BytesIO` can be used like a file
-   opened in a binary mode.
+   and writing.  For strings :class:`StringIO` can be used like a file opened in
+   a text mode, and for bytes a :class:`BytesIO` can be used like a file opened
+   in a binary mode.
 
 
 .. exception:: BlockingIOError