A lot of small detailed revisions to the io module's doc.

1 files changed, 137 insertions, 117 deletions

diff --git a/Doc/library/io.rst b/Doc/library/io.rst
index 6280adc..d0f82a3 100644
--- a/Doc/library/io.rst
+++ b/Doc/library/io.rst
@@ -18,19 +18,22 @@ to throw an :exc:`IOError` if they do not support a given operation.
 
 Extending :class:`IOBase` is :class:`RawIOBase` which deals simply with the
 reading and writing of raw bytes to a stream.  :class:`FileIO` subclasses
-:class:`RawIOBase` to provide an interface to OS files.
+:class:`RawIOBase` to provide an interface to files in the machine's
+file system.
 
 :class:`BufferedIOBase` 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 respectively.  :class:`BufferedRandom` provides a
-buffered interface to random access streams.  :class:`BytesIO` is a simple
-stream of in-memory bytes.
+readable, writable, and both readable and writable.
+:class:`BufferedRandom` provides a buffered interface to random access
+streams.  :class:`BytesIO` is a simple stream of in-memory bytes.
 
-Another :class:`IOBase` subclass, :class:`TextIOBase`, deals with the encoding
-and decoding of streams into text.  :class:`TextIOWrapper`, which extends it, is
-a buffered text interface to a buffered raw stream (:class:`BufferedIOBase`).
-Finally, :class:`StringIO` is a in-memory stream for text.
+Another :class:`IOBase` subclass, :class:`TextIOBase`, deals with
+streams whose bytes represent text, and handles encoding and decoding
+from and to strings. :class:`TextIOWrapper`, which extends it, 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
 :func:`open` are intended to be used as keyword arguments.
@@ -51,10 +54,10 @@ Module Interface
    :exc:`IOError` is raised.
 
    *file* is either a string giving the name (and the path if the file isn't in
-   the current working directory) of the file to be opened or an integer file
-   descriptor of the file to be wrapped.  (If a file descriptor is given, it is
-   closed when the returned I/O object is closed, unless *closefd* is set to
-   ``False``.)
+   the current working directory) of the file to be opened or a file
+   descriptor of the file to be opened.  (If a file descriptor is given,
+   for example, from :func:`os.fdopen`, it is closed when the returned
+   I/O object is closed, unless *closefd* is set to ``False``.)
 
    *mode* is an optional string that specifies the mode in which the file is
    opened.  It defaults to ``'r'`` which means open for reading in text mode.
@@ -74,8 +77,8 @@ Module Interface
    ``'b'``   binary mode
    ``'t'``   text mode (default)
    ``'+'``   open a disk file for updating (reading and writing)
-   ``'U'``   universal newline mode (for backwards compatibility; unneeded
-             for new code)
+   ``'U'``   universal newline mode (for backwards compatibility; should
+             not be used in new code)
    ========= ===============================================================
 
    The default mode is ``'rt'`` (open for reading text).  For binary random
@@ -84,9 +87,9 @@ Module Interface
 
    Python distinguishes between files opened in binary and text modes, even when
    the underlying operating system doesn't.  Files opened in binary mode
-   (appending ``'b'`` to the *mode* argument) return contents as ``bytes``
+   (including ``'b'`` in the *mode* argument) return contents as ``bytes``
    objects without any decoding.  In text mode (the default, or when ``'t'`` is
-   appended to the *mode* argument), the contents of the file are returned as
+   included in the *mode* argument), the contents of the file are returned as
    strings, the bytes having been first decoded using a platform-dependent
    encoding or using the specified *encoding* if given.
 
@@ -97,7 +100,7 @@ Module Interface
 
    *encoding* is the name of the encoding used to decode or encode the file.
    This should only be used in text mode.  The default encoding is platform
-   dependent, but any encoding supported by Python can be passed.  See the
+   dependent, but any encoding supported by Python can be used.  See the
    :mod:`codecs` module for the list of supported encodings.
 
    *errors* is an optional string that specifies how encoding and decoding
@@ -129,23 +132,24 @@ Module Interface
      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 but must be ``True`` (the default).
 
-   :func:`open` returns a file object whose type depends on the mode, and
-   through which the standard file operations such as reading and writing are
-   performed.  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`.
+   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`.
 
    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
-   a text mode, and for bytes a :class:`BytesIO` can be used like a file opened
-   in a binary mode.
+   a text mode, and for bytearrays a :class:`BytesIO` can be used like a
+   file opened in a binary mode.
 
 
 .. exception:: BlockingIOError
@@ -176,9 +180,10 @@ I/O Base Classes
    The abstract base class for all I/O classes, acting on streams of bytes.
    There is no public constructor.
 
-   This class provides dummy implementations for many methods that derived
-   classes can override selectively; the default implementations represent a
-   file that cannot be read, written or seeked.
+   This class provides empty abstract implementations for many methods
+   that derived classes can override selectively; the default
+   implementations represent a file that cannot be read, written or
+   seeked.
 
    Even though :class:`IOBase` does not declare :meth:`read`, :meth:`readinto`,
    or :meth:`write` because their signatures will vary, implementations and
@@ -188,8 +193,8 @@ I/O Base Classes
 
    The basic type used for binary data read from or written to a file is
    :class:`bytes`.  :class:`bytearray`\s are accepted too, and in some cases
-   (such as :class:`readinto`) needed.  Text I/O classes work with :class:`str`
-   data.
+   (such as :class:`readinto`) required.  Text I/O classes work with
+   :class:`str` data.
 
    Note that calling any method (even inquiries) on a closed stream is
    undefined.  Implementations may raise :exc:`IOError` in this case.
@@ -197,13 +202,14 @@ 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.
 
-   IOBase also supports the :keyword:`with` statement.  In this example, *fp* is
-   closed after the suite of the with statment is complete::
+   IOBase is also a context manager and therefore supports the
+   :keyword:`with` statement.  In this example, *file* is closed after the
+   :keyword:`with` statement's suite is finished---even if an exception occurs::
 
-      with open('spam.txt', 'r') as fp:
-          fp.write('Spam and eggs!')
+      with open('spam.txt', 'w') as file:
+          file.write('Spam and eggs!')
 
-   :class:`IOBase` provides these methods:
+   :class:`IOBase` provides these data attributes and methods:
 
    .. method:: close()
 
@@ -227,17 +233,18 @@ I/O Base Classes
 
    .. method:: isatty()
 
-      Tell if a stream is interactive (connected to a terminal/tty device).
+      Returns ``True`` if the stream is interactive (i.e., connected to
+      a terminal/tty device).
 
    .. method:: readable()
 
-      Tell if a stream can be read from.  If False, :meth:`read` will raise
-      :exc:`IOError`.
+      Returns ``True`` if the stream can be read from.  If False,
+      :meth:`read` will raise :exc:`IOError`.
 
    .. method:: readline([limit])
 
-      Read and return a line from the stream.  If *limit* is specified, at most
-      *limit* bytes will be read.
+      Reads and returns one line from the stream.  If *limit* is
+      specified, at most *limit* bytes will be read.
 
       The line terminator is always ``b'\n'`` for binary files; for text files,
       the *newlines* argument to :func:`open` can be used to select the line
@@ -245,45 +252,47 @@ I/O Base Classes
 
    .. method:: readlines([hint])
 
-      Return a list of lines from the stream.  *hint* can be specified to
+      Returns a list of lines from the stream.  *hint* can be specified to
       control the number of lines read: no more lines will be read if the total
       size (in bytes/characters) of all lines so far exceeds *hint*.
 
    .. method:: seek(offset[, whence])
 
-      Change the stream position to byte offset *offset*.  *offset* is
+      Change the stream position to the given byte *offset*.  *offset* is
       interpreted relative to the position indicated by *whence*.  Values for
       *whence* are:
 
-      * ``0`` -- start of stream (the default); *pos* should be zero or positive
-      * ``1`` -- current stream position; *pos* may be negative
-      * ``2`` -- end of stream; *pos* is usually negative
+      * ``0`` -- start of the stream (the default); *offset* should be zero or positive
+      * ``1`` -- current stream position; *offset* may be negative
+      * ``2`` -- end of the stream; *offset* is usually negative
 
-      Return the new absolute position.
+      Returns the new absolute position.
 
    .. method:: seekable()
 
-      Tell if a stream supports random IO access.  If ``False``, :meth:`seek`,
-      :meth:`tell` and :meth:`truncate` will raise :exc:`IOError`.
+      Returns ``True`` if the stream supports random access.  If
+      ``False``, :meth:`seek`, :meth:`tell` and :meth:`truncate` will
+      raise :exc:`IOError`.
 
    .. method:: tell()
 
-      Return an integer indicating the current stream position.
+      Returns the current stream position.
 
-   .. method:: truncate([pos])
+   .. method:: truncate([size])
 
-      Truncate the file to at most *pos* bytes.  *pos* defaults to the current
+      Truncates the file to at most *size* bytes.  *size* defaults to the current
       file position, as returned by :meth:`tell`.
 
    .. method:: writable()
 
-      Tell if a stream supports writing.  If ``False``, :meth:`write` and
-      :meth:`truncate` will raise :exc:`IOError`.
+      Returns ``True`` if the stream supports writing.  If ``False``,
+      :meth:`write` and :meth:`truncate` will raise :exc:`IOError`.
 
    .. method:: writelines(lines)
 
-      Write a list of lines to the stream.  The lines will not be altered; they
-      must contain line separators.
+      Writes a list of lines to the stream.  Line separators are not
+      added, so it is usual for each of the lines provided to have a
+      line separator at the end.
 
 
 .. class:: RawIOBase
@@ -291,30 +300,32 @@ I/O Base Classes
    Base class for raw binary I/O.  It inherits :class:`IOBase`.  There is no
    public constructor.
 
-   RawIOBase provides or overrides these methods in addition to those from
-   :class:`IOBase`:
+   In addition to the attributes and methods from :class:`IOBase`,
+   RawIOBase provides the following methods:
 
    .. method:: read([n])
 
-      Read and return all bytes from the stream until EOF, or if *n* is
+      Reads and returns all the bytes from the stream until EOF, or if *n* is
       specified, up to *n* bytes.  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()
 
-      Read and return all bytes from the stream until EOF, using multiple calls
-      to the stream.
+      Reads and returns all the bytes from the stream until EOF, using
+      multiple calls to the stream if necessary.
 
    .. method:: readinto(b)
 
-      Read up to len(b) bytes into bytearray *b* and return the number of bytes
-      read.
+      Reads up to len(b) bytes into bytearray *b* and returns the number
+      of bytes read.
 
    .. method:: write(b)
 
-      Write the given bytes, *b*, to the underlying raw stream and return the
-      number of bytes written (never less than ``len(b)``).
+      Writes the given bytes or bytearray object, *b*, to the underlying
+      raw stream and returns the number of bytes written (never less
+      than ``len(b)``, since if the write fails an :exc:`IOError` will
+      be raised).
 
 
 Raw File I/O
@@ -322,7 +333,7 @@ Raw File I/O
 
 .. class:: FileIO(name[, mode])
 
-   :class:`FileIO` represents an OS file containing bytes data.  It implements
+   :class:`FileIO` represents a file containing bytes data.  It implements
    the :class:`RawIOBase` interface (and therefore the :class:`IOBase`
    interface, too).
 
@@ -331,8 +342,9 @@ Raw File I/O
    writing or appending; it will be truncated when opened for writing.  Add a
    ``'+'`` to the mode to allow simultaneous reading and writing.
 
-   :class:`FileIO` provides or overrides these methods in addition to those from
-   :class:`RawIOBase` and :class:`IOBase`:
+   In addition to the attributes and methods from :class:`IOBase` and
+   :class:`RawIOBase`, :class:`FileIO` provides the following data
+   attributes and methods:
 
    .. attribute:: mode
 
@@ -344,24 +356,27 @@ Raw File I/O
 
    .. method:: read([n])
 
-      Read and return bytes at most *n* bytes.  Only one system call is made, so
-      less data than requested may be returned.  In non-blocking mode, ``None``
-      is returned when no data is available.
+      Reads and returns at most *n* bytes.  Only one system call is made, so
+      it is possible that less data than was requested is returned. Call
+      :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 as bytes all the data from the file.  As much as
-      immediately available is returned in non-blocking mode.  If the EOF has
-      been reached, ``b''`` is returned.
-
-   .. method:: readinto(bytearray)
-
-      This method should not be used on :class:`FileIO` objects.
+      Reads and returns 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 *b* to the file, and return the number actually written.
-      Only one system call is made, so not all of the data may be written.
+      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.
+
+   Note that the inherited ``readinto()`` method should not be used on
+   :class:`FileIO` objects.
 
 
 Buffered Streams
@@ -390,7 +405,7 @@ Buffered Streams
 
    .. method:: read([n])
 
-      Read and return up to *n* bytes.  If the argument is omitted, ``None``, or
+      Reads and returns up to *n* bytes.  If the argument is omitted, ``None``, or
       negative, data is read and returned until EOF is reached.  An empty bytes
       object is returned if the stream is already at EOF.
 
@@ -405,7 +420,7 @@ Buffered Streams
 
    .. method:: readinto(b)
 
-      Read up to len(b) bytes into bytearray *b* and return the number of bytes
+      Reads up to len(b) bytes into bytearray *b* and returns the number of bytes
       read.
 
       Like :meth:`read`, multiple reads may be issued to the underlying raw
@@ -416,8 +431,10 @@ Buffered Streams
 
    .. method:: write(b)
 
-      Write the given bytes, *b*, to the underlying raw stream and return the
-      number of bytes written (never less than ``len(b)``).
+      Writes the given bytes or bytearray object, *b*, to the underlying
+      raw stream and returns the number of bytes written (never less than
+      ``len(b)``, since if the write fails an :exc:`IOError` will
+      be raised).
 
       A :exc:`BlockingIOError` is raised if the buffer is full, and the
       underlying raw stream cannot accept more data at the moment.
@@ -435,15 +452,16 @@ Buffered Streams
 
    .. method:: getvalue()
 
-      Return the bytes value of the buffer.
+      Returns a bytes object containing the entire contents of the
+      buffer.
 
    .. method:: read1()
 
       In :class:`BytesIO`, this is the same as :meth:`read`.
 
-   .. method:: truncate([pos])
+   .. method:: truncate([size])
 
-      Truncate the file to at most *pos* bytes.  *pos* defaults to the current
+      Truncates the buffer to at most *size* bytes.  *size* defaults to the current
       stream position, as returned by :meth:`tell`.
 
 
@@ -461,19 +479,20 @@ Buffered Streams
 
    .. method:: peek([n])
 
-      Return bytes from a buffer without advancing the position.  The argument
-      indicates a desired minimal number of bytes; only one read on the raw
-      stream is done to satisfy it.  More than the buffer's size is never
-      returned.
+      Returns 1 (or *n* if specified) bytes from a buffer without
+      advancing the position.  Only a single read on the raw stream is done to
+      satisfy the call. The number of bytes returned may be less than
+      requested since at most all the buffer's bytes from the current
+      position to the end are returned.
 
    .. method:: read([n])
 
-      Read and return *n* bytes, or if *n* is not given or negative, until EOF
+      Reads and returns *n* bytes, or if *n* is not given or negative, until EOF
       or if the read call would block in non-blocking mode.
 
    .. method:: read1(n)
 
-      Read and return up to *n* bytes with only one call on the raw stream.  If
+      Reads and returns up to *n* bytes with only one call on the raw stream.  If
       at least one byte is buffered, only buffered bytes are returned.
       Otherwise, one raw stream read call is made.
 
@@ -494,20 +513,21 @@ Buffered Streams
    .. method:: flush()
 
       Force bytes held in the buffer into the raw stream.  A
-      :exc:`BlockingIOError` is be raised if the raw stream blocks.
+      :exc:`BlockingIOError` should be raised if the raw stream blocks.
 
    .. method:: write(b)
 
-      Write bytes *b* onto the raw stream and return the number written.  A
-      :exc:`BlockingIOError` is raised when the raw stream blocks.
+      Writes the bytes or bytearray object, *b*, onto the raw stream and
+      returns the number of bytes written.  A :exc:`BlockingIOError` is
+      raised when the raw stream blocks.
 
 
 .. class:: BufferedRWPair(reader, writer[, buffer_size[, max_buffer_size]])
 
-   A buffered writer and reader object together for a raw stream that can be
-   written and read from.  It has and supports both :meth:`read`, :meth:`write`,
-   and their variants.  This is useful for such applications such as sockets and
-   two-way pipes.  It inherits :class:`BufferedIOBase`.
+   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`.
 
    *reader* and *writer* are :class:`RawIOBase` objects that are readable and
    writeable respectively.  If the *buffer_size* is omitted it defaults to
@@ -541,33 +561,33 @@ Text I/O
    Python's character strings are immutable.  It inherits :class:`IOBase`.
    There is no public constructor.
 
-   :class:`TextIOBase` provides or overrides these methods in addition to those
-   from :class:`IOBase`:
+   :class:`TextIOBase` provides or overrides these data attributes and
+   methods in addition to those from :class:`IOBase`:
 
    .. attribute:: encoding
 
-      Return the name of the encoding used to decode the stream's bytes into
+      The name of the encoding used to decode the stream's bytes into
       strings, and to encode strings into bytes.
 
    .. attribute:: newlines
 
-      Return a string, tuple of strings, or ``None`` indicating the newlines
+      A string, a tuple of strings, or ``None``, indicating the newlines
       translated so far.
 
    .. method:: read(n)
 
-      Read and return at most *n* characters from the stream.  If *n* is
-      negative or ``None``, read to EOF.
+      Reads and returns at most *n* characters from the stream as a
+      single :class:`str`.  If *n* is negative or ``None``, reads to EOF.
 
    .. method:: readline()
 
-      Read until newline or EOF and return.  If the stream is already at EOF, an
-      empty stream is returned.
+      Reads until newline or EOF and returns a single :class:`str`.  If
+      the stream is already at EOF, an empty string is returned.
 
    .. method:: write(s)
 
-      Write string *s* to the stream and return the number of characters
-      written.
+      Writes the string *s* to the stream and returns the number of
+      characters written.
 
 
 .. class:: TextIOWrapper(buffer[, encoding[, errors[, newline[, line_buffering]]]])
@@ -601,7 +621,7 @@ Text I/O
    If *line_buffering* is ``True``, :meth:`flush` is implied when a call to
    write contains a newline character.
 
-   :class:`TextIOWrapper` provides these methods in addition to those of
+   :class:`TextIOWrapper` provides these data attributes in addition to those of
    :class:`TextIOBase` and its parents:
 
    .. attribute:: errors
@@ -621,12 +641,12 @@ Text I/O
    and newline setting.  See :class:`TextIOWrapper`\'s constructor for more
    information.
 
-   :class:`StringIO` provides these methods in addition to those from
+   :class:`StringIO` provides this method in addition to those from
    :class:`TextIOWrapper` and its parents:
 
    .. method:: getvalue()
 
-      Return a str representation of the contents of the internal buffer.
+      Returns a :class:`str` containing the entire contents of the buffer.
 
 
 .. class:: IncrementalNewlineDecoder