Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

Improve the io module documentation (GH-15099) 

* Update io.rst

* Apply suggestions from code review

Co-Authored-By: Ashwin Ramaswami <aramaswamis@gmail.com>

Co-Authored-By: Carol Willing <carolcode@willingconsulting.com>
This commit is contained in:
Géry Ogam 2019-09-11 16:55:13 +02:00 committed by Carol Willing
parent 574b324bdc
commit 3b58a70d9c
1 changed files with 60 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

114
Doc/library/io.rst
View File

@ -195,18 +195,18 @@ The :class:`RawIOBase` ABC extends :class:`IOBase`. It deals with the reading
and writing of bytes to a stream. :class:`FileIO` subclasses :class:`RawIOBase`
to provide an interface to files in the machine's file system.
The :class:`BufferedIOBase` ABC deals with buffering on a raw byte stream
(:class:`RawIOBase`). Its subclasses, :class:`BufferedWriter`,
:class:`BufferedReader`, and :class:`BufferedRWPair` buffer streams that are
readable, writable, and both readable and writable. :class:`BufferedRandom`
provides a buffered interface to random access streams. Another
:class:`BufferedIOBase` subclass, :class:`BytesIO`, is a stream of in-memory
bytes.
The :class:`BufferedIOBase` ABC extends :class:`IOBase`. It deals with
buffering on a raw binary stream (:class:`RawIOBase`). Its subclasses,
:class:`BufferedWriter`, :class:`BufferedReader`, and :class:`BufferedRWPair`
buffer raw binary streams that are readable, writable, and both readable and writable,
respectively. :class:`BufferedRandom` provides a buffered interface to seekable streams.
Another :class:`BufferedIOBase` subclass, :class:`BytesIO`, is a stream of
in-memory bytes.
The :class:`TextIOBase` ABC, another subclass of :class:`IOBase`, deals with
The :class:`TextIOBase` ABC extends :class:`IOBase`. It deals with
streams whose bytes represent text, and handles encoding and decoding to and
from strings. :class:`TextIOWrapper`, which extends it, is a buffered text
interface to a buffered raw stream (:class:`BufferedIOBase`). Finally,
from strings. :class:`TextIOWrapper`, which extends :class:`TextIOBase`, is a buffered text
interface to a buffered raw stream (:class:`BufferedIOBase`). Finally,
:class:`StringIO` is an in-memory stream for text.
Argument names are not part of the specification, and only the arguments of
@ -391,15 +391,16 @@ I/O Base Classes
.. class:: RawIOBase
Base class for raw binary I/O. It inherits :class:`IOBase`. There is no
Base class for raw binary streams. It inherits :class:`IOBase`. There is no
public constructor.
Raw binary I/O typically provides low-level access to an underlying OS
device or API, and does not try to encapsulate it in high-level primitives
(this is left to Buffered I/O and Text I/O, described later in this page).
Raw binary streams typically provide low-level access to an underlying OS
device or API, and do not try to encapsulate it in high-level primitives
(this functionality is done at a higher-level in buffered binary streams and text streams, described later
in this page).
In addition to the attributes and methods from :class:`IOBase`,
:class:`RawIOBase` provides the following methods:
:class:`RawIOBase` provides these methods in addition to those from
:class:`IOBase`:
.. method:: read(size=-1)
@ -463,8 +464,8 @@ I/O Base Classes
:class:`RawIOBase` implementation, but wrap one, like
:class:`BufferedWriter` and :class:`BufferedReader` do.
:class:`BufferedIOBase` provides or overrides these methods and attribute in
addition to those from :class:`IOBase`:
:class:`BufferedIOBase` provides or overrides these data attributes and
methods in addition to those from :class:`IOBase`:
.. attribute:: raw
@ -557,9 +558,8 @@ Raw File I/O
.. class:: FileIO(name, mode='r', closefd=True, opener=None)
:class:`FileIO` represents an OS-level file containing bytes data.
It implements the :class:`RawIOBase` interface (and therefore the
:class:`IOBase` interface, too).
A raw binary stream representing an OS-level file containing bytes data. It
inherits :class:`RawIOBase`.
The *name* can be one of two things:
@ -600,9 +600,8 @@ Raw File I/O
.. versionchanged:: 3.4
The file is now non-inheritable.
In addition to the attributes and methods from :class:`IOBase` and
:class:`RawIOBase`, :class:`FileIO` provides the following data
attributes:
:class:`FileIO` provides these data attributes in addition to those from
:class:`RawIOBase` and :class:`IOBase`:
.. attribute:: mode
@ -622,7 +621,7 @@ than raw I/O does.
.. class:: BytesIO([initial_bytes])
A stream implementation using an in-memory bytes buffer. It inherits
A binary stream using an in-memory bytes buffer. It inherits
:class:`BufferedIOBase`. The buffer is discarded when the
:meth:`~IOBase.close` method is called.
@ -670,8 +669,10 @@ than raw I/O does.
.. class:: BufferedReader(raw, buffer_size=DEFAULT_BUFFER_SIZE)
A buffer providing higher-level access to a readable, sequential
:class:`RawIOBase` object. It inherits :class:`BufferedIOBase`.
A buffered binary stream providing higher-level access to a readable, non
seekable :class:`RawIOBase` raw binary stream. It inherits
:class:`BufferedIOBase`.
When reading data from this object, a larger amount of data may be
requested from the underlying raw stream, and kept in an internal buffer.
The buffered data can then be returned directly on subsequent reads.
@ -706,8 +707,10 @@ than raw I/O does.
.. class:: BufferedWriter(raw, buffer_size=DEFAULT_BUFFER_SIZE)
A buffer providing higher-level access to a writeable, sequential
:class:`RawIOBase` object. It inherits :class:`BufferedIOBase`.
A buffered binary stream providing higher-level access to a writeable, non
seekable :class:`RawIOBase` raw binary stream. It inherits
:class:`BufferedIOBase`.
When writing to this object, data is normally placed into an internal
buffer. The buffer will be written out to the underlying :class:`RawIOBase`
object under various conditions, including:
@ -739,8 +742,9 @@ than raw I/O does.
.. class:: BufferedRandom(raw, buffer_size=DEFAULT_BUFFER_SIZE)
A buffered interface to random access streams. It inherits
:class:`BufferedReader` and :class:`BufferedWriter`.
A buffered binary stream providing higher-level access to a seekable
:class:`RawIOBase` raw binary stream. It inherits :class:`BufferedReader`
and :class:`BufferedWriter`.
The constructor creates a reader and writer for a seekable raw stream, given
in the first argument. If the *buffer_size* is omitted it defaults to
@ -753,9 +757,9 @@ than raw I/O does.
.. class:: BufferedRWPair(reader, writer, buffer_size=DEFAULT_BUFFER_SIZE)
A buffered I/O object combining two unidirectional :class:`RawIOBase`
objects -- one readable, the other writeable -- into a single bidirectional
endpoint. It inherits :class:`BufferedIOBase`.
A buffered binary stream providing higher-level access to two non seekable
:class:`RawIOBase` raw binary streams---one readable, the other writeable.
It inherits :class:`BufferedIOBase`.
*reader* and *writer* are :class:`RawIOBase` objects that are readable and
writeable respectively. If the *buffer_size* is omitted it defaults to
@ -778,8 +782,8 @@ Text I/O
.. class:: TextIOBase
Base class for text streams. This class provides a character and line based
interface to stream I/O. It inherits :class:`IOBase`.
There is no public constructor.
interface to stream I/O. It inherits :class:`IOBase`. There is no public
constructor.
:class:`TextIOBase` provides or overrides these data attributes and
methods in addition to those from :class:`IOBase`:
@ -867,8 +871,9 @@ Text I/O
.. class:: TextIOWrapper(buffer, encoding=None, errors=None, newline=None, \
line_buffering=False, write_through=False)
A buffered text stream over a :class:`BufferedIOBase` binary stream.
It inherits :class:`TextIOBase`.
A buffered text stream providing higher-level access to a
:class:`BufferedIOBase` buffered binary stream. It inherits
:class:`TextIOBase`.
*encoding* gives the name of the encoding that the stream will be decoded or
encoded with. It defaults to
@ -896,11 +901,11 @@ Text I/O
* When reading input from the stream, if *newline* is ``None``,
:term:`universal newlines` mode is enabled. Lines in the input can end in
``'\n'``, ``'\r'``, or ``'\r\n'``, and these are translated into ``'\n'``
before being returned to the caller. If it is ``''``, universal newlines
mode is enabled, but line endings are returned to the caller untranslated.
If it has any of the other legal values, input lines are only terminated
by the given string, and the line ending is returned to the caller
untranslated.
before being returned to the caller. If *newline* is ``''``, universal
newlines mode is enabled, but line endings are returned to the caller
untranslated. If *newline* has any of the other legal values, input lines
are only terminated by the given string, and the line ending is returned to
the caller untranslated.
* When writing output to the stream, if *newline* is ``None``, any ``'\n'``
characters written are translated to the system default line separator,
@ -924,8 +929,8 @@ Text I/O
locale encoding using :func:`locale.setlocale`, use the current locale
encoding instead of the user preferred encoding.
:class:`TextIOWrapper` provides these members in addition to those of
:class:`TextIOBase` and its parents:
:class:`TextIOWrapper` provides these data attributes and methods in
addition to those from :class:`TextIOBase` and :class:`IOBase`:
.. attribute:: line_buffering
@ -960,22 +965,23 @@ Text I/O
.. class:: StringIO(initial_value='', newline='\\n')
An in-memory stream for text I/O. The text buffer is discarded when the
:meth:`~IOBase.close` method is called.
A text stream using an in-memory text buffer. It inherits
:class:`TextIOBase`.
The text buffer is discarded when the :meth:`~IOBase.close` method is
called.
The initial value of the buffer can be set by providing *initial_value*.
If newline translation is enabled, newlines will be encoded as if by
:meth:`~TextIOBase.write`. The stream is positioned at the start of
the buffer.
The *newline* argument works like that of :class:`TextIOWrapper`.
The default is to consider only ``\n`` characters as ends of lines and
to do no newline translation. If *newline* is set to ``None``,
newlines are written as ``\n`` on all platforms, but universal
newline decoding is still performed when reading.
The *newline* argument works like that of :class:`TextIOWrapper`,
except that when writing output to the stream, if *newline* is ``None``,
newlines are written as ``\n`` on all platforms.
:class:`StringIO` provides this method in addition to those from
:class:`TextIOBase` and its parents:
:class:`TextIOBase` and :class:`IOBase`:
.. method:: getvalue()
@ -1066,5 +1072,5 @@ buffered object.
The above implicitly extends to text files, since the :func:`open()` function
will wrap a buffered object inside a :class:`TextIOWrapper`. This includes
standard streams and therefore affects the built-in function :func:`print()` as
standard streams and therefore affects the built-in :func:`print()` function as
well.