Update io.rst

python · willingc · Sep 11, 2019 · Aug 3, 2019 · Aug 7, 2019 · Aug 24, 2019
commit 22138cec80b95d4ccef45b5eeea7d9861d76b5f7
diff --git a/Doc/library/io.rst b/Doc/library/io.rst
@@ -273,7 +273,7 @@ I/O Base Classes
       with open('spam.txt', 'w') as file:
           file.write('Spam and eggs!')
 
-   :class:`IOBase` provides these data attributes and methods:
+   :class:`IOBase` provides these data attribute and methods:
 
    .. method:: close()
 
@@ -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 is left to 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 attribute 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,9 @@ 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 over a readable, sequential :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 +706,9 @@ 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 over a writeable, sequential :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 +740,8 @@ 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 over 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 +754,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 over two unidirectional :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 +779,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,7 +868,7 @@ 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.
+   A buffered text stream over a :class:`BufferedIOBase` buffered binary stream.
    It inherits :class:`TextIOBase`.
 
    *encoding* gives the name of the encoding that the stream will be decoded or
@@ -896,11 +897,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 +925,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 method in
+   addition to those from :class:`TextIOBase` and :class:`IOBase`:
 
    .. attribute:: line_buffering
 
@@ -960,22 +961,25 @@ 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 if *newline* is set to ``None``, newlines are written as
+   ``\n`` on all platforms, but universal newline decoding is still
+   performed when reading.  The default is to consider only ``\n``
+   characters as ends of lines and to do no newline translation.
 
    :class:`StringIO` provides this method in addition to those from
-   :class:`TextIOBase` and its parents:
+   :class:`TextIOBase` and :class:`IOBase`:
 
    .. method:: getvalue()