summaryrefslogtreecommitdiffstats
path: root/Doc/library
diff options
context:
space:
mode:
authorBenjamin Peterson <benjamin@python.org>2009-03-23 02:38:01 (GMT)
committerBenjamin Peterson <benjamin@python.org>2009-03-23 02:38:01 (GMT)
commit8cad9c777b8f7d963a1af0266e8d785fd42445ba (patch)
tree6b8bdd9854f528bb2464cb2c8ba440692848a768 /Doc/library
parent21e5fcd245e0a683ae437aedafd6c8608373d060 (diff)
downloadcpython-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.rst23
-rw-r--r--Doc/library/io.rst28
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