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

Skip to content

Commit 52c3bf1

Browse files
benjaminpbenjaminp
committed
sync open() docs more
1 parent 8cad9c7 commit 52c3bf1

2 files changed

Lines changed: 52 additions & 49 deletions

File tree

‎Doc/library/functions.rst‎

Lines changed: 32 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -666,7 +666,8 @@ are always available. They are listed here in alphabetical order.
666666

667667
.. function:: open(file[, mode='r'[, buffering=None[, encoding=None[, errors=None[, newline=None[, closefd=True]]]]]])
668668

669-
Open a file. If the file cannot be opened, :exc:`IOError` is raised.
669+
Open *file* and return a corresponding stream. If the file cannot be opened,
670+
an :exc:`IOError` is raised.
670671

671672
*file* is either a string or bytes object giving the name (and the path if
672673
the file isn't in the current working directory) of the file to be opened or
@@ -679,14 +680,9 @@ are always available. They are listed here in alphabetical order.
679680
Other common values are ``'w'`` for writing (truncating the file if it
680681
already exists), and ``'a'`` for appending (which on *some* Unix systems,
681682
means that *all* writes append to the end of the file regardless of the
682-
current seek position).
683-
684-
In text mode, if *encoding* is not specified the encoding used is the same as
685-
returned by :func:`locale.getpreferredencoding`, if the :mod:`locale` module
686-
is available, else ASCII. For reading and writing raw bytes, use binary mode
687-
and leave *encoding* unspecified.
688-
689-
The available modes are:
683+
current seek position). In text mode, if *encoding* is not specified the
684+
encoding used is platform dependent. (For reading and writing raw bytes use
685+
binary mode and leave *encoding* unspecified.) The available modes are:
690686

691687
========= ===============================================================
692688
Character Meaning
@@ -697,39 +693,44 @@ are always available. They are listed here in alphabetical order.
697693
``'b'`` binary mode
698694
``'t'`` text mode (default)
699695
``'+'`` open a disk file for updating (reading and writing)
700-
``'U'`` universal newline mode (for backwards compatibility; unneeded
701-
for new code)
696+
``'U'`` universal newline mode (for backwards compatibility; should
697+
not be used in new code)
702698
========= ===============================================================
703699

704700
The default mode is ``'rt'`` (open for reading text). For binary random
705701
access, the mode ``'w+b'`` opens and truncates the file to 0 bytes, while
706702
``'r+b'`` opens the file without truncation.
707703

708-
Python distinguishes between files opened in binary and text modes, even
709-
when the underlying operating system doesn't. Files opened in binary
710-
mode (appending ``'b'`` to the *mode* argument) return contents as
711-
``bytes`` objects without any decoding. In text mode (the default, or when
712-
``'t'`` is appended to the *mode* argument) the contents of
713-
the file are returned as strings, the bytes having been first decoded
714-
using a platform-dependent encoding or using the specified *encoding*
715-
if given.
704+
Python distinguishes between files opened in binary and text modes, even when
705+
the underlying operating system doesn't. Files opened in binary mode
706+
(including ``'b'`` in the *mode* argument) return contents as ``bytes``
707+
objects without any decoding. In text mode (the default, or when ``'t'`` is
708+
included in the *mode* argument), the contents of the file are returned as
709+
strings, the bytes having been first decoded using a platform-dependent
710+
encoding or using the specified *encoding* if given.
716711

717712
*buffering* is an optional integer used to set the buffering policy. By
718-
default full buffering is on. Pass 0 to switch buffering off (only allowed in
719-
binary mode), 1 to set line buffering, and an integer > 1 for full buffering.
713+
default full buffering is on. Pass 0 to switch buffering off (only allowed
714+
in binary mode), 1 to set line buffering, and an integer > 1 for full
715+
buffering.
720716

721717
*encoding* is the name of the encoding used to decode or encode the file.
722718
This should only be used in text mode. The default encoding is platform
723-
dependent, but any encoding supported by Python can be passed. See the
724-
:mod:`codecs` module for the list of supported encodings.
725-
726-
*errors* is an optional string that specifies how encoding errors are to be
727-
handled---this argument should not be used in binary mode. Pass ``'strict'``
728-
to raise a :exc:`ValueError` exception if there is an encoding error (the
729-
default of ``None`` has the same effect), or pass ``'ignore'`` to ignore
730-
errors. (Note that ignoring encoding errors can lead to data loss.) See the
731-
documentation for :func:`codecs.register` for a list of the permitted
732-
encoding error strings.
719+
dependent (whatever :func:`locale.getpreferredencoding` returns), but any
720+
encoding supported by Python can be used. See the :mod:`codecs` module for
721+
the list of supported encodings.
722+
723+
*errors* is an optional string that specifies how encoding and decoding
724+
errors are to be handled--this cannot be used in binary mode. Pass
725+
``'strict'`` to raise a :exc:`ValueError` exception if there is an encoding
726+
error (the default of ``None`` has the same effect), or pass ``'ignore'`` to
727+
ignore errors. (Note that ignoring encoding errors can lead to data loss.)
728+
``'replace'`` causes a replacement marker (such as ``'?'``) to be inserted
729+
where there is malformed data. When writing, ``'xmlcharrefreplace'``
730+
(replace with the appropriate XML character reference) or
731+
``'backslashreplace'`` (replace with backslashed escape sequences) can be
732+
used. Any other error handling name that has been registered with
733+
:func:`codecs.register_error` is also valid.
733734

734735
*newline* controls how universal newlines works (it only applies to text
735736
mode). It can be ``None``, ``''``, ``'\n'``, ``'\r'``, and ``'\r\n'``. It

‎Doc/library/io.rst‎

Lines changed: 20 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -52,14 +52,14 @@ Module Interface
5252

5353
.. function:: open(file[, mode[, buffering[, encoding[, errors[, newline[, closefd=True]]]]]])
5454

55-
Open *file* and return a stream. If the file cannot be opened, an
56-
:exc:`IOError` is raised.
55+
Open *file* and return a corresponding stream. If the file cannot be opened,
56+
an :exc:`IOError` is raised.
5757

58-
*file* is either a string giving the name (and the path if the file isn't in
59-
the current working directory) of the file to be opened or a file
60-
descriptor of the file to be opened. (If a file descriptor is given,
61-
for example, from :func:`os.fdopen`, it is closed when the returned
62-
I/O object is closed, unless *closefd* is set to ``False``.)
58+
*file* is either a string or bytes object giving the name (and the path if
59+
the file isn't in the current working directory) of the file to be opened or
60+
an integer file descriptor of the file to be wrapped. (If a file descriptor
61+
is given, it is closed when the returned I/O object is closed, unless
62+
*closefd* is set to ``False``.)
6363

6464
*mode* is an optional string that specifies the mode in which the file is
6565
opened. It defaults to ``'r'`` which means open for reading in text mode.
@@ -102,19 +102,21 @@ Module Interface
102102

103103
*encoding* is the name of the encoding used to decode or encode the file.
104104
This should only be used in text mode. The default encoding is platform
105-
dependent, but any encoding supported by Python can be used. See the
106-
:mod:`codecs` module for the list of supported encodings.
105+
dependent (whatever :func:`locale.getpreferredencoding` returns), but any
106+
encoding supported by Python can be used. See the :mod:`codecs` module for
107+
the list of supported encodings.
107108

108109
*errors* is an optional string that specifies how encoding and decoding
109-
errors are to be handled. Pass ``'strict'`` to raise a :exc:`ValueError`
110-
exception if there is an encoding error (the default of ``None`` has the same
111-
effect), or pass ``'ignore'`` to ignore errors. (Note that ignoring encoding
112-
errors can lead to data loss.) ``'replace'`` causes a replacement marker
113-
(such as ``'?'``) to be inserted where there is malformed data. When
114-
writing, ``'xmlcharrefreplace'`` (replace with the appropriate XML character
115-
reference) or ``'backslashreplace'`` (replace with backslashed escape
116-
sequences) can be used. Any other error handling name that has been
117-
registered with :func:`codecs.register_error` is also valid.
110+
errors are to be handled--this cannot be used in binary mode. Pass
111+
``'strict'`` to raise a :exc:`ValueError` exception if there is an encoding
112+
error (the default of ``None`` has the same effect), or pass ``'ignore'`` to
113+
ignore errors. (Note that ignoring encoding errors can lead to data loss.)
114+
``'replace'`` causes a replacement marker (such as ``'?'``) to be inserted
115+
where there is malformed data. When writing, ``'xmlcharrefreplace'``
116+
(replace with the appropriate XML character reference) or
117+
``'backslashreplace'`` (replace with backslashed escape sequences) can be
118+
used. Any other error handling name that has been registered with
119+
:func:`codecs.register_error` is also valid.
118120

119121
*newline* controls how universal newlines works (it only applies to text
120122
mode). It can be ``None``, ``''``, ``'\n'``, ``'\r'``, and ``'\r\n'``. It

0 commit comments

Comments
 (0)