mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-11-03 11:23:31 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

#5061: improve open() docs a bit.

Browse source
This commit is contained in:
Georg Brandl 2009-04-27 06:13:55 +00:00
parent 47a7d70002
commit 7b6ca4ab7f
1 changed files with 16 additions and 15 deletions
Download patch file Download diff file Expand all files Collapse all files

31
Doc/library/functions.rst
View file

@ -676,38 +676,39 @@ are always available. They are listed here in alphabetical order.
*closefd* is set to ``False``.) *closefd* is set to ``False``.)
*mode* is an optional string that specifies the mode in which the file is *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. opened. The available modes are:
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 Character Meaning
--------- --------------------------------------------------------------- --------- ---------------------------------------------------------------
``'r'`` open for reading (default) ``'r'`` open for reading (default)
``'w'`` open for writing, truncating the file first ``'w'`` open for writing, truncating the file first if it exists
``'a'`` open for writing, appending to the end of the file if it exists ``'a'`` open for writing, appending to the end of the file if it exists
``'b'`` binary mode ========= ===============================================================
Several characters can be appended that modify the given mode:
========= ===============================================================
``'t'`` text mode (default) ``'t'`` text mode (default)
``'+'`` open a disk file for updating (reading and writing) ``'b'`` binary mode
``'+'`` open for updating (reading and writing)
``'U'`` universal newline mode (for backwards compatibility; should ``'U'`` universal newline mode (for backwards compatibility; should
not be used in new code) not be used in new code)
========= =============================================================== ========= ===============================================================
The default mode is ``'rt'`` (open for reading text). For binary random The mode ``'w+'`` opens and truncates the file to 0 bytes, while ``'r+'``
access, the mode ``'w+b'`` opens and truncates the file to 0 bytes, while opens the file without truncation. On *some* Unix systems, append mode means
``'r+b'`` opens the file without truncation. that *all* writes append to the end of the file regardless of the current
seek position.
Python distinguishes between files opened in binary and text modes, even when Python distinguishes between files opened in binary and text modes, even when
the underlying operating system doesn't. Files opened in binary mode the underlying operating system doesn't. Files opened in binary mode
(including ``'b'`` in the *mode* argument) return contents as ``bytes`` (including ``'b'`` in the *mode* argument) return contents as ``bytes``
objects without any decoding. In text mode (the default, or when ``'t'`` is objects without any decoding. In text mode (the default, or when ``'t'`` is
included in the *mode* argument), the contents of the file are returned as included in the *mode* argument), the contents of the file are returned as
strings, the bytes having been first decoded using a platform-dependent strings, the bytes having been first decoded using the specified *encoding*.
encoding or using the specified *encoding* if given. If *encoding* is not specified, a platform-dependent default encoding is
used, see below.
*buffering* is an optional integer used to set the buffering policy. By *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 default full buffering is on. Pass 0 to switch buffering off (only allowed