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

sync open() doc

Browse source
This commit is contained in:
Benjamin Peterson 2010-08-30 12:46:09 +00:00
parent b530e1438b
commit 4e4ffb1181
1 changed files with 50 additions and 37 deletions
Download patch file Download diff file Expand all files Collapse all files

87
Doc/library/functions.rst
View file

@ -683,51 +683,65 @@ are always available. They are listed here in alphabetical order.
Open *file* and return a corresponding stream. If the file cannot be opened, Open *file* and return a corresponding stream. If the file cannot be opened,
an :exc:`IOError` is raised. an :exc:`IOError` is raised.
*file* is either a string or bytes object giving the name (and the path if *file* is either a string or bytes object giving the pathname (absolute or
the file isn't in the current working directory) of the file to be opened or relative to 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 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 is given, it is closed when the returned I/O object is closed, unless
*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. 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:
========= =============================================================== ========= ===============================================================
Character Meaning Character Meaning
--------- --------------------------------------------------------------- --------- ---------------------------------------------------------------
``'r'`` open for reading (default) ``'r'`` open for reading (default)
``'w'`` open for writing, truncating the file first if it exists ``'w'`` open for writing, truncating the file first
``'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
========= ===============================================================
Several characters can be appended that modify the given mode:
========= ===============================================================
``'t'`` text mode (default)
``'b'`` binary mode ``'b'`` binary mode
``'+'`` open for updating (reading and writing) ``'t'`` text mode (default)
``'+'`` open a disk file 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 mode ``'w+'`` opens and truncates the file to 0 bytes, while ``'r+'`` The default mode is ``'r'`` (open for reading text, synonym of ``'rt'``).
opens the file without truncation. On *some* Unix systems, append mode means For binary read-write access, the mode ``'w+b'`` opens and truncates the
that *all* writes append to the end of the file regardless of the current file to 0 bytes, while ``'r+b'`` opens the file without truncation.
seek position.
Python distinguishes between files opened in binary and text modes, even when As mentioned in the `overview`_, Python distinguishes between binary
the underlying operating system doesn't. Files opened in binary mode and text I/O. Files opened in binary mode (including ``'b'`` in the
(including ``'b'`` in the *mode* argument) return contents as ``bytes`` *mode* argument) return contents as :class:`bytes` objects without
objects without any decoding. In text mode (the default, or when ``'t'`` is any decoding. In text mode (the default, or when ``'t'``
included in the *mode* argument), the contents of the file are returned as is included in the *mode* argument), the contents of the file are
strings, the bytes having been first decoded using the specified *encoding*. returned as strings, the bytes having been first decoded using a
If *encoding* is not specified, a platform-dependent default encoding is platform-dependent encoding or using the specified *encoding* if given.
used, see below.
*buffering* is an optional integer used to set the buffering policy. By .. note::
default full buffering is on. Pass 0 to switch buffering off (only allowed Python doesn't depend on the underlying operating system's notion
in binary mode), 1 to set line buffering, and an integer > 1 to indicate the of text files; all the the processing is done by Python itself, and
size of the buffer. is therefore platform-independent.
*buffering* is an optional integer used to set the buffering policy.
Pass 0 to switch buffering off (only allowed in binary mode), 1 to select
line buffering (only usable in text mode), and an integer > 1 to indicate
the size of a fixed-size chunk buffer. When no *buffering* argument is
given, the default buffering policy works as follows:
* Binary files are buffered in fixed-size chunks; the size of the buffer
is chosen using a heuristic trying to determine the underlying device's
"block size" and falling back on :attr:`DEFAULT_BUFFER_SIZE`.
On many systems, the buffer will typically be 4096 or 8192 bytes long.
* "Interactive" text files (files for which :meth:`isatty` returns True)
use line buffering. Other text files use the policy described above
for binary files.
*encoding* is the name of the encoding used to decode or encode the file. *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 This should only be used in text mode. The default encoding is platform
@ -770,17 +784,16 @@ are always available. They are listed here in alphabetical order.
closed. If a filename is given *closefd* has no effect and must be ``True`` closed. If a filename is given *closefd* has no effect and must be ``True``
(the default). (the default).
The type of file object returned by the :func:`open` function depends on the The type of file object returned by the :func:`.open` function depends on the
mode. When :func:`open` is used to open a file in a text mode (``'w'``, mode. When :func:`.open` is used to open a file in a text mode (``'w'``,
``'r'``, ``'wt'``, ``'rt'``, etc.), it returns a subclass of ``'r'``, ``'wt'``, ``'rt'``, etc.), it returns a subclass of
:class:`io.TextIOBase` (specifically :class:`io.TextIOWrapper`). When used :class:`TextIOBase` (specifically :class:`TextIOWrapper`). When used to open
to open a file in a binary mode with buffering, the returned class is a a file in a binary mode with buffering, the returned class is a subclass of
subclass of :class:`io.BufferedIOBase`. The exact class varies: in read :class:`BufferedIOBase`. The exact class varies: in read binary mode, it
binary mode, it returns a :class:`io.BufferedReader`; in write binary and returns a :class:`BufferedReader`; in write binary and append binary modes,
append binary modes, it returns a :class:`io.BufferedWriter`, and in it returns a :class:`BufferedWriter`, and in read/write mode, it returns a
read/write mode, it returns a :class:`io.BufferedRandom`. When buffering is :class:`BufferedRandom`. When buffering is disabled, the raw stream, a
disabled, the raw stream, a subclass of :class:`io.RawIOBase`, subclass of :class:`RawIOBase`, :class:`FileIO`, is returned.
:class:`io.FileIO`, is returned.
.. index:: .. index::
single: line-buffered I/O single: line-buffered I/O