diff options
author | Benjamin Peterson <benjamin@python.org> | 2009-03-23 02:38:01 (GMT) |
---|---|---|
committer | Benjamin Peterson <benjamin@python.org> | 2009-03-23 02:38:01 (GMT) |
commit | 8cad9c777b8f7d963a1af0266e8d785fd42445ba (patch) | |
tree | 6b8bdd9854f528bb2464cb2c8ba440692848a768 /Doc/library | |
parent | 21e5fcd245e0a683ae437aedafd6c8608373d060 (diff) | |
download | cpython-8cad9c777b8f7d963a1af0266e8d785fd42445ba.zip cpython-8cad9c777b8f7d963a1af0266e8d785fd42445ba.tar.gz cpython-8cad9c777b8f7d963a1af0266e8d785fd42445ba.tar.bz2 |
fix docs about open's return value #5539
(how annoying to have the same docs in two places)
(three if you count the docstring...)
Diffstat (limited to 'Doc/library')
-rw-r--r-- | Doc/library/functions.rst | 23 | ||||
-rw-r--r-- | Doc/library/io.rst | 28 |
2 files changed, 33 insertions, 18 deletions
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 4d8a845..df05d2f 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -749,9 +749,22 @@ are always available. They are listed here in alphabetical order. the other legal values, any ``'\n'`` characters written are translated to the given string. - If *closefd* is ``False``, the underlying file descriptor will be kept open - when the file is closed. This does not work when a file name is given and - must be ``True`` in that case. + If *closefd* is ``False`` and a file descriptor rather than a filename was + given, the underlying file descriptor will be kept open when the file is + closed. If a filename is given *closefd* has no effect and must be ``True`` + (the default). + + 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'``, + ``'r'``, ``'wt'``, ``'rt'``, etc.), it returns a subclass of + :class:`io.TextIOBase` (specifically :class:`io.TextIOWrapper`). When used + to open a file in a binary mode with buffering, the returned class is a + subclass of :class:`io.BufferedIOBase`. The exact class varies: in read + binary mode, it returns a :class:`io.BufferedReader`; in write binary and + append binary modes, it returns a :class:`io.BufferedWriter`, and in + read/write mode, it returns a :class:`io.BufferedRandom`. When buffering is + disabled, the raw stream, a subclass of :class:`io.RawIOBase`, + :class:`io.FileIO`, is returned. .. index:: single: line-buffered I/O @@ -763,8 +776,8 @@ are always available. They are listed here in alphabetical order. module: sys See also the file handling modules, such as, :mod:`fileinput`, :mod:`io` - (where :func:`open()` is declared), :mod:`os`, :mod:`os.path`, - :mod:`tempfile`, and :mod:`shutil`. + (where :func:`open` is declared), :mod:`os`, :mod:`os.path`, :mod:`tempfile`, + and :mod:`shutil`. .. XXX works for bytes too, but should it? diff --git a/Doc/library/io.rst b/Doc/library/io.rst index 6ce28d0..b491cbd 100644 --- a/Doc/library/io.rst +++ b/Doc/library/io.rst @@ -134,19 +134,21 @@ Module Interface the other legal values, any ``'\n'`` characters written are translated to the given string. - If *closefd* is ``False`` and a file descriptor rather than a - filename was given, the underlying file descriptor will be kept open - when the file is closed. If a filename is given *closefd* has no - effect but must be ``True`` (the default). - - 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'``, ``'r'``, ``'wt'``, ``'rt'``, etc.), it returns a - :class:`TextIOWrapper`. When used to open a file in a binary mode, - the returned class varies: in read binary mode, it returns a - :class:`BufferedReader`; in write binary and append binary modes, it - returns a :class:`BufferedWriter`, and in read/write mode, it returns - a :class:`BufferedRandom`. + If *closefd* is ``False`` and a file descriptor rather than a filename was + given, the underlying file descriptor will be kept open when the file is + closed. If a filename is given *closefd* has no effect and must be ``True`` + (the default). + + 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'``, + ``'r'``, ``'wt'``, ``'rt'``, etc.), it returns a subclass of + :class:`TextIOBase` (specifically :class:`TextIOWrapper`). When used to open + a file in a binary mode with buffering, the returned class is a subclass of + :class:`BufferedIOBase`. The exact class varies: in read binary mode, it + returns a :class:`BufferedReader`; in write binary and append binary modes, + it returns a :class:`BufferedWriter`, and in read/write mode, it returns a + :class:`BufferedRandom`. When buffering is disabled, the raw stream, a + subclass of :class:`RawIOBase`, :class:`FileIO`, is returned. It is also possible to use a string or bytearray as a file for both reading and writing. For strings :class:`StringIO` can be used like a file opened in |