Issue #6929: fix a couple of statements and clarify a lot of things in the IO docs.

Doc/library/io.rst

@@ -208,6 +208,9 @@ I/O Base Classes
 
    IOBase (and its subclasses) support the iterator protocol, meaning that an
    :class:`IOBase` object can be iterated over yielding the lines in a stream.
+   Lines are defined slightly differently depending on whether the stream is
+   a binary stream (yielding bytes), or a text stream (yielding character
+   strings).  See :meth:`readline` below.
 
    IOBase is also a context manager and therefore supports the
    :keyword:`with` statement.  In this example, *file* is closed after the
@@ -314,15 +317,20 @@ I/O Base Classes
    Base class for raw binary I/O.  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).
+
    In addition to the attributes and methods from :class:`IOBase`,
    RawIOBase provides the following methods:
 
    .. method:: read(n=-1)
 
-      Read and return all the bytes from the stream until EOF, or if *n* is
-      specified, up to *n* bytes.  Only one system call is ever made.  An empty
-      bytes object is returned on EOF; ``None`` is returned if the object is set
-      not to block and has no data to read.
+      Read and return up to *n* bytes from the stream.  As a convenience, if
+      *n* is unspecified or -1, :meth:`readall` is called.  Otherwise,
+      only one system call is ever made.  An empty bytes object is returned
+      on EOF; ``None`` is returned if the object is set not to block and has
+      no data to read.
 
    .. method:: readall()
 
@@ -337,27 +345,34 @@ I/O Base Classes
    .. method:: write(b)
 
       Write the given bytes or bytearray object, *b*, to the underlying raw
-      stream and return the number of bytes written (This is never less than
-      ``len(b)``, since if the write fails, an :exc:`IOError` will be raised).
+      stream and return the number of bytes written.  This can be less than
+      ``len(b)``, depending on specifics of the underlying raw stream, and
+      especially if it is in non-blocking mode.  ``None`` is returned if the
+      raw stream is set not to block and no single byte could be readily
+      written to it.
 
 
 .. class:: BufferedIOBase
 
-   Base class for streams that support buffering.  It inherits :class:`IOBase`.
-   There is no public constructor.
+   Base class for binary streams that support some kind of buffering.
+   It inherits :class:`IOBase`. There is no public constructor.
 
-   The main difference with :class:`RawIOBase` is that the :meth:`read` method
-   supports omitting the *size* argument, and does not have a default
-   implementation that defers to :meth:`readinto`.
+   The main difference with :class:`RawIOBase` is that methods :meth:`read`,
+   :meth:`readinto` and :meth:`write` will try (respectively) to read as much
+   input as requested or to consume all given output, at the expense of
+   making perhaps more than one system call.
 
-   In addition, :meth:`read`, :meth:`readinto`, and :meth:`write` may raise
-   :exc:`BlockingIOError` if the underlying raw stream is in non-blocking mode
-   and not ready; unlike their raw counterparts, they will never return
-   ``None``.
+   In addition, those methods can raise :exc:`BlockingIOError` if the
+   underlying raw stream is in non-blocking mode and cannot take or give
+   enough data; unlike their :class:`RawIOBase` counterparts, they will
+   never return ``None``.
 
-   A typical implementation should not inherit from a :class:`RawIOBase`
-   implementation, but wrap one like :class:`BufferedWriter` and
-   :class:`BufferedReader`.
+   Besides, the :meth:`read` method does not have a default
+   implementation that defers to :meth:`readinto`.
+
+   A typical :class:`BufferedIOBase` implementation should not inherit from a
+   :class:`RawIOBase` implementation, but wrap one, like
+   :class:`BufferedWriter` and :class:`BufferedReader` do.
 
    :class:`BufferedIOBase` provides or overrides these members in addition to
    those from :class:`IOBase`:
@@ -393,13 +408,15 @@ I/O Base Classes
       one raw read will be issued, and a short result does not imply that EOF is
       imminent.
 
-      A :exc:`BlockingIOError` is raised if the underlying raw stream has no
-      data at the moment.
+      A :exc:`BlockingIOError` is raised if the underlying raw stream is in
+      non blocking-mode, and has no data available at the moment.
 
    .. method:: read1(n=-1)
 
       Read and return up to *n* bytes, with at most one call to the underlying
-      raw stream's :meth:`~RawIOBase.read` method.
+      raw stream's :meth:`~RawIOBase.read` method.  This can be useful if you
+      are implementing your own buffering on top of a :class:`BufferedIOBase`
+      object.
 
    .. method:: readinto(b)
 
@@ -407,19 +424,22 @@ I/O Base Classes
       read.
 
       Like :meth:`read`, multiple reads may be issued to the underlying raw
-      stream, unless the latter is 'interactive.'
+      stream, unless the latter is 'interactive'.
 
-      A :exc:`BlockingIOError` is raised if the underlying raw stream has no
-      data at the moment.
+      A :exc:`BlockingIOError` is raised if the underlying raw stream is in
+      non blocking-mode, and has no data available at the moment.
 
    .. method:: write(b)
 
-      Write the given bytes or bytearray object, *b*, to the underlying raw
-      stream and return the number of bytes written (never less than ``len(b)``,
-      since if the write fails an :exc:`IOError` will be raised).
+      Write the given bytes or bytearray object, *b* and return the number
+      of bytes written (never less than ``len(b)``, since if the write fails
+      an :exc:`IOError` will be raised).  Depending on the actual
+      implementation, these bytes may be readily written to the underlying
+      stream, or held in a buffer for performance and latency reasons.
 
-      A :exc:`BlockingIOError` is raised if the buffer is full, and the
-      underlying raw stream cannot accept more data at the moment.
+      When in non-blocking mode, a :exc:`BlockingIOError` is raised if the
+      data needed to be written to the raw stream but it couldn't accept
+      all the data without blocking.
 
 
 Raw File I/O
@@ -427,15 +447,25 @@ Raw File I/O
 
 .. class:: FileIO(name, mode='r', closefd=True)
 
-   :class:`FileIO` represents a file containing bytes data.  It implements
-   the :class:`RawIOBase` interface (and therefore the :class:`IOBase`
-   interface, too).
+   :class:`FileIO` represents an OS-level file containing bytes data.
+   It implements the :class:`RawIOBase` interface (and therefore the
+   :class:`IOBase` interface, too).
+
+   The *name* can be one of two things:
+
+   * a character string or bytes object representing the path to the file
+     which will be opened;
+   * an integer representing the number of an existing OS-level file descriptor
+     to which the resulting :class:`FileIO` object will give access.
 
    The *mode* can be ``'r'``, ``'w'`` or ``'a'`` for reading (default), writing,
    or appending.  The file will be created if it doesn't exist when opened for
    writing or appending; it will be truncated when opened for writing.  Add a
    ``'+'`` to the mode to allow simultaneous reading and writing.
 
+   The :meth:`read` (when called with a positive argument), :meth:`readinto`
+   and :meth:`write` methods on this class will only make one system call.
+
    In addition to the attributes and methods from :class:`IOBase` and
    :class:`RawIOBase`, :class:`FileIO` provides the following data
    attributes and methods:
@@ -449,29 +479,13 @@ Raw File I/O
       The file name.  This is the file descriptor of the file when no name is
       given in the constructor.
 
-   .. method:: read(n=-1)
-
-      Read and return at most *n* bytes.  Only one system call is made, so it is
-      possible that less data than was requested is returned.  Use :func:`len`
-      on the returned bytes object to see how many bytes were actually returned.
-      (In non-blocking mode, ``None`` is returned when no data is available.)
-
-   .. method:: readall()
-
-      Read and return the entire file's contents in a single bytes object.  As
-      much as immediately available is returned in non-blocking mode.  If the
-      EOF has been reached, ``b''`` is returned.
-
-   .. method:: write(b)
-
-      Write the bytes or bytearray object, *b*, to the file, and return
-      the number actually written. Only one system call is made, so it
-      is possible that only some of the data is written.
-
 
 Buffered Streams
 ----------------
 
+In many situations, buffered I/O streams will provide higher performance
+(bandwidth and latency) than raw I/O streams.  Their API is also more usable.
+
 .. class:: BytesIO([initial_bytes])
 
    A stream implementation using an in-memory bytes buffer.  It inherits
@@ -498,8 +512,11 @@ Buffered Streams
 
 .. class:: BufferedReader(raw, buffer_size=DEFAULT_BUFFER_SIZE)
 
-   A buffer for a readable, sequential :class:`RawIOBase` object.  It inherits
-   :class:`BufferedIOBase`.
+   A buffer providing higher-level access to a readable, sequential
+   :class:`RawIOBase` object.  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.
 
    The constructor creates a :class:`BufferedReader` for the given readable
    *raw* stream and *buffer_size*.  If *buffer_size* is omitted,
@@ -528,8 +545,16 @@ Buffered Streams
 
 .. class:: BufferedWriter(raw, buffer_size=DEFAULT_BUFFER_SIZE)
 
-   A buffer for a writeable sequential RawIO object.  It inherits
-   :class:`BufferedIOBase`.
+   A buffer providing higher-level access to a writeable, sequential
+   :class:`RawIOBase` object.  It inherits :class:`BufferedIOBase`.
+   When writing to this object, data is normally held into an internal
+   buffer.  The buffer will be written out to the underlying :class:`RawIOBase`
+   object under various conditions, including:
+
+   * when the buffer gets too small for all pending data;
+   * when :meth:`flush()` is called;
+   * when a :meth:`seek()` is requested (for :class:`BufferedRandom` objects);
+   * when the :class:`BufferedWriter` object is closed or destroyed.
 
    The constructor creates a :class:`BufferedWriter` for the given writeable
    *raw* stream.  If the *buffer_size* is not given, it defaults to
@@ -547,17 +572,17 @@ Buffered Streams
 
    .. method:: write(b)
 
-      Write the bytes or bytearray object, *b*, onto the raw stream and return
-      the number of bytes written.  A :exc:`BlockingIOError` is raised when the
-      raw stream blocks.
+      Write the bytes or bytearray object, *b* and return the number of bytes
+      written.  When in non-blocking mode, a :exc:`BlockingIOError` is raised
+      if the buffer needs to be written out but the raw stream blocks.
 
 
-.. class:: BufferedRWPair(reader, writer, buffer_size, max_buffer_size=DEFAULT_BUFFER_SIZE)
+.. class:: BufferedRWPair(reader, writer, buffer_size=DEFAULT_BUFFER_SIZE)
 
-   A combined buffered writer and reader object for a raw stream that can be
-   written to and read from.  It has and supports both :meth:`read`, :meth:`write`,
-   and their variants.  This is useful for sockets and two-way pipes.
-   It inherits :class:`BufferedIOBase`.
+   A buffered I/O object giving a combined, higher-level access to two
+   sequential :class:`RawIOBase` objects: one readable, the other writeable.
+   It is useful for pairs of unidirectional communication channels
+   (pipes, for instance).  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
@@ -574,7 +599,8 @@ Buffered Streams
 .. class:: BufferedRandom(raw, buffer_size=DEFAULT_BUFFER_SIZE)
 
    A buffered interface to random access streams.  It inherits
-   :class:`BufferedReader` and :class:`BufferedWriter`.
+   :class:`BufferedReader` and :class:`BufferedWriter`, and further supports
+   :meth:`seek` and :meth:`tell` functionality.
 
    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
@@ -611,7 +637,8 @@ Text I/O
    .. attribute:: newlines
 
       A string, a tuple of strings, or ``None``, indicating the newlines
-      translated so far.
+      translated so far.  Depending on the implementation and the initial
+      constructor flags, this may not be available.
 
    .. attribute:: buffer
 
@@ -621,7 +648,8 @@ Text I/O
 
    .. method:: detach()
 
-      Separate the underlying buffer from the :class:`TextIOBase` and return it.
+      Separate the underlying binary buffer from the :class:`TextIOBase` and
+      return it.
 
       After the underlying buffer has been detached, the :class:`TextIOBase` is
       in an unusable state.
@@ -635,7 +663,7 @@ Text I/O
    .. method:: read(n)
 
       Read and return at most *n* characters from the stream as a single
-      :class:`str`.  If *n* is negative or ``None``, reads to EOF.
+      :class:`str`.  If *n* is negative or ``None``, reads until EOF.
 
    .. method:: readline()
 
@@ -650,7 +678,7 @@ Text I/O
 
 .. class:: TextIOWrapper(buffer, encoding=None, errors=None, newline=None, line_buffering=False)
 
-   A buffered text stream over a :class:`BufferedIOBase` raw stream, *buffer*.
+   A buffered text stream over a :class:`BufferedIOBase` binary stream.
    It inherits :class:`TextIOBase`.
 
    *encoding* gives the name of the encoding that the stream will be decoded or