[Python-3000-checkins] r62291 - python/branches/py3k/Doc/library/functions.rst python/branches/py3k/Doc/library/io.rst
benjamin.peterson
python-3000-checkins at python.org
Fri Apr 11 23:17:32 CEST 2008
Author: benjamin.peterson
Date: Fri Apr 11 23:17:32 2008
New Revision: 62291
Modified:
python/branches/py3k/Doc/library/functions.rst
python/branches/py3k/Doc/library/io.rst
Log:
Synced builtin open and io.open documentation, taking the best of each
Modified: python/branches/py3k/Doc/library/functions.rst
==============================================================================
--- python/branches/py3k/Doc/library/functions.rst (original)
+++ python/branches/py3k/Doc/library/functions.rst Fri Apr 11 23:17:32 2008
@@ -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:
-
- * '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 @@
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?
Modified: python/branches/py3k/Doc/library/io.rst
==============================================================================
--- python/branches/py3k/Doc/library/io.rst (original)
+++ python/branches/py3k/Doc/library/io.rst Fri Apr 11 23:17:32 2008
@@ -44,13 +44,23 @@
.. function:: open(file[, mode[, buffering[, encoding[, errors[, newline[, closefd=True]]]]]])
- Open *file* and return a stream.
+ Open *file* and return a stream. If the file cannot be opened, an
+ :exc:`IOError` is raised.
- *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:
+ *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 @@
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.
+
+ *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 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.
-
- *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
+ 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 @@
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.
-
- 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
+ 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.
+
+ :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 @@
: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
More information about the Python-3000-checkins
mailing list