traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Update the documentation of the open() builtin function a bit. I believe I 

mostly got the distinction between text and binary modes correct, though
someone should proofread my writing.  I also sort of guessed at the meaning
of the various index:: entries.
This commit is contained in:
Skip Montanaro 2007-09-23 21:13:45 +00:00
parent 1c63960c1b
commit 4d8c19339f
1 changed files with 23 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
Doc/library/functions.rst
View File

@ -708,19 +708,25 @@ available. They are listed here in alphabetical order.
for writing (truncating the file if it already exists), and ``'a'`` for for writing (truncating the file if it already exists), and ``'a'`` for
appending (which on *some* Unix systems means that *all* writes append to 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* the end of the file regardless of the current seek position). If *mode*
is omitted, it defaults to ``'r'``. is omitted, it defaults to ``'r'``. See below for more possible values
of *mode*.
When opening a binary file, you should append ``'b'`` to the *mode* value Python distinguishes between files opened in binary and text modes, even
to open the file in binary mode, which will improve portability. when the underlying operating system doesn't. Files opened in binary
(Appending ``'b'`` is useful even on systems that don't treat binary and mode (appending ``'b'`` to the *mode* argument to :func:``open``) return
text files differently, where it serves as documentation.) See below for contents as bytes objects without any decoding. In text mode (the
more possible values of *mode*. 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 the encoding specified by :func:`sys.getfilesystemencoding`.
.. index:: .. index::
single: line-buffered I/O single: line-buffered I/O
single: unbuffered I/O single: unbuffered I/O
single: buffer size, I/O single: buffer size, I/O
single: I/O control; buffering single: I/O control; buffering
single: binary mode
single: text mode
module: sys
The optional *bufsize* argument specifies the file's desired buffer size: The optional *bufsize* argument specifies the file's desired buffer size:
0 means unbuffered, 1 means line buffered, any other positive value means 0 means unbuffered, 1 means line buffered, any other positive value means
@ -730,28 +736,20 @@ available. They are listed here in alphabetical order.
used. [#]_ used. [#]_
Modes ``'r+'``, ``'w+'`` and ``'a+'`` open the file for updating (note Modes ``'r+'``, ``'w+'`` and ``'a+'`` open the file for updating (note
that ``'w+'`` truncates the file). Append ``'b'`` to the mode to open that ``'w+'`` truncates the file).
the file in binary mode, on systems that differentiate between binary and
text files; on systems that don't have this distinction, adding the
``'b'`` has no effect.
In addition to the standard :cfunc:`fopen` values *mode* may be ``'U'`` When a file is opened in text mode it is also opened in universal
or ``'rU'``. Python is usually built with universal newline support; newlines mode. Unlike earlier versions of Python it's no longer
supplying ``'U'`` opens the file as a text file, but lines may be necessary to add a ``'U'`` value to the *mode* argument to enable this
terminated by any of the following: the Unix end-of-line convention mode. Consequently, in files opened in text mode lines may be terminated
``'\n'``, the Macintosh convention ``'\r'``, or the Windows convention with ``'\n'``, ``'\r'``, or ``'\r\n'``. All three external
``'\r\n'``. All of these external representations are seen as ``'\n'`` by representations are seen as ``'\n'`` by the Python program. File objects
the Python program. If Python is built without universal newline support opened in text mode also have a :attr:`newlines` attribute which has a
a *mode* with ``'U'`` is the same as normal text mode. Note that file value of ``None`` (if no newlines have been seen yet), ``'\n'``,
objects so opened also have an attribute called :attr:`newlines` which
has a value of ``None`` (if no newlines have yet been seen), ``'\n'``,
``'\r'``, ``'\r\n'``, or a tuple containing all the newline types seen. ``'\r'``, ``'\r\n'``, or a tuple containing all the newline types seen.
Python enforces that the mode, after stripping ``'U'``, begins with See also the :mod:`fileinput` module, the file-related functions in the
``'r'``, ``'w'`` or ``'a'``. :mod:`os` module, and the :mod:`os.path` module.
See also the :mod:`fileinput` module, the :mod:`os` module, and the
:mod:`os.path` module.
.. function:: ord(c) .. function:: ord(c)