Synced builtin open and io.open documentation, taking the best of each
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 @@
: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:
+ 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)
+ ========= ===============================================================
+ 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 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*.
+ 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.
+ 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.
+ *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:
- *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.
+ * 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 @@
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?