Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 4e4ffb1

Browse files
benjaminpbenjaminp
committed
sync open() doc
1 parent b530e14 commit 4e4ffb1

1 file changed

Lines changed: 52 additions & 39 deletions

File tree

‎Doc/library/functions.rst‎

Lines changed: 52 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -683,51 +683,65 @@ are always available. They are listed here in alphabetical order.
683683
Open *file* and return a corresponding stream. If the file cannot be opened,
684684
an :exc:`IOError` is raised.
685685

686-
*file* is either a string or bytes object giving the name (and the path if
687-
the file isn't in the current working directory) of the file to be opened or
686+
*file* is either a string or bytes object giving the pathname (absolute or
687+
relative to the current working directory) of the file to be opened or
688688
an integer file descriptor of the file to be wrapped. (If a file descriptor
689689
is given, it is closed when the returned I/O object is closed, unless
690690
*closefd* is set to ``False``.)
691691

692692
*mode* is an optional string that specifies the mode in which the file is
693-
opened. The available modes are:
693+
opened. It defaults to ``'r'`` which means open for reading in text mode.
694+
Other common values are ``'w'`` for writing (truncating the file if it
695+
already exists), and ``'a'`` for appending (which on *some* Unix systems,
696+
means that *all* writes append to the end of the file regardless of the
697+
current seek position). In text mode, if *encoding* is not specified the
698+
encoding used is platform dependent. (For reading and writing raw bytes use
699+
binary mode and leave *encoding* unspecified.) The available modes are:
694700

695701
========= ===============================================================
696702
Character Meaning
697703
--------- ---------------------------------------------------------------
698704
``'r'`` open for reading (default)
699-
``'w'`` open for writing, truncating the file first if it exists
705+
``'w'`` open for writing, truncating the file first
700706
``'a'`` open for writing, appending to the end of the file if it exists
701-
========= ===============================================================
702-
703-
Several characters can be appended that modify the given mode:
704-
705-
========= ===============================================================
706-
``'t'`` text mode (default)
707707
``'b'`` binary mode
708-
``'+'`` open for updating (reading and writing)
708+
``'t'`` text mode (default)
709+
``'+'`` open a disk file for updating (reading and writing)
709710
``'U'`` universal newline mode (for backwards compatibility; should
710711
not be used in new code)
711712
========= ===============================================================
712713

713-
The mode ``'w+'`` opens and truncates the file to 0 bytes, while ``'r+'``
714-
opens the file without truncation. On *some* Unix systems, append mode means
715-
that *all* writes append to the end of the file regardless of the current
716-
seek position.
717-
718-
Python distinguishes between files opened in binary and text modes, even when
719-
the underlying operating system doesn't. Files opened in binary mode
720-
(including ``'b'`` in the *mode* argument) return contents as ``bytes``
721-
objects without any decoding. In text mode (the default, or when ``'t'`` is
722-
included in the *mode* argument), the contents of the file are returned as
723-
strings, the bytes having been first decoded using the specified *encoding*.
724-
If *encoding* is not specified, a platform-dependent default encoding is
725-
used, see below.
726-
727-
*buffering* is an optional integer used to set the buffering policy. By
728-
default full buffering is on. Pass 0 to switch buffering off (only allowed
729-
in binary mode), 1 to set line buffering, and an integer > 1 to indicate the
730-
size of the buffer.
714+
The default mode is ``'r'`` (open for reading text, synonym of ``'rt'``).
715+
For binary read-write access, the mode ``'w+b'`` opens and truncates the
716+
file to 0 bytes, while ``'r+b'`` opens the file without truncation.
717+
718+
As mentioned in the `overview`_, Python distinguishes between binary
719+
and text I/O. Files opened in binary mode (including ``'b'`` in the
720+
*mode* argument) return contents as :class:`bytes` objects without
721+
any decoding. In text mode (the default, or when ``'t'``
722+
is included in the *mode* argument), the contents of the file are
723+
returned as strings, the bytes having been first decoded using a
724+
platform-dependent encoding or using the specified *encoding* if given.
725+
726+
.. note::
727+
Python doesn't depend on the underlying operating system's notion
728+
of text files; all the the processing is done by Python itself, and
729+
is therefore platform-independent.
730+
731+
*buffering* is an optional integer used to set the buffering policy.
732+
Pass 0 to switch buffering off (only allowed in binary mode), 1 to select
733+
line buffering (only usable in text mode), and an integer > 1 to indicate
734+
the size of a fixed-size chunk buffer. When no *buffering* argument is
735+
given, the default buffering policy works as follows:
736+
737+
* Binary files are buffered in fixed-size chunks; the size of the buffer
738+
is chosen using a heuristic trying to determine the underlying device's
739+
"block size" and falling back on :attr:`DEFAULT_BUFFER_SIZE`.
740+
On many systems, the buffer will typically be 4096 or 8192 bytes long.
741+
742+
* "Interactive" text files (files for which :meth:`isatty` returns True)
743+
use line buffering. Other text files use the policy described above
744+
for binary files.
731745

732746
*encoding* is the name of the encoding used to decode or encode the file.
733747
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.
770784
closed. If a filename is given *closefd* has no effect and must be ``True``
771785
(the default).
772786

773-
The type of file object returned by the :func:`open` function depends on the
774-
mode. When :func:`open` is used to open a file in a text mode (``'w'``,
787+
The type of file object returned by the :func:`.open` function depends on the
788+
mode. When :func:`.open` is used to open a file in a text mode (``'w'``,
775789
``'r'``, ``'wt'``, ``'rt'``, etc.), it returns a subclass of
776-
:class:`io.TextIOBase` (specifically :class:`io.TextIOWrapper`). When used
777-
to open a file in a binary mode with buffering, the returned class is a
778-
subclass of :class:`io.BufferedIOBase`. The exact class varies: in read
779-
binary mode, it returns a :class:`io.BufferedReader`; in write binary and
780-
append binary modes, it returns a :class:`io.BufferedWriter`, and in
781-
read/write mode, it returns a :class:`io.BufferedRandom`. When buffering is
782-
disabled, the raw stream, a subclass of :class:`io.RawIOBase`,
783-
:class:`io.FileIO`, is returned.
790+
:class:`TextIOBase` (specifically :class:`TextIOWrapper`). When used to open
791+
a file in a binary mode with buffering, the returned class is a subclass of
792+
:class:`BufferedIOBase`. The exact class varies: in read binary mode, it
793+
returns a :class:`BufferedReader`; in write binary and append binary modes,
794+
it returns a :class:`BufferedWriter`, and in read/write mode, it returns a
795+
:class:`BufferedRandom`. When buffering is disabled, the raw stream, a
796+
subclass of :class:`RawIOBase`, :class:`FileIO`, is returned.
784797

785798
.. index::
786799
single: line-buffered I/O

0 commit comments

Comments
 (0)