[Python-checkins] Improve the io module documentation (GH-15099)
Carol Willing
webhook-mailer at python.org
Wed Sep 11 10:55:16 EDT 2019
https://github.com/python/cpython/commit/3b58a70d9cf1c0f963adce9b07060116b2775687
commit: 3b58a70d9cf1c0f963adce9b07060116b2775687
branch: master
author: Géry Ogam <gery.ogam at gmail.com>
committer: Carol Willing <carolcode at willingconsulting.com>
date: 2019-09-11T15:55:13+01:00
summary:
Improve the io module documentation (GH-15099)
* Update io.rst
* Apply suggestions from code review
Co-Authored-By: Ashwin Ramaswami <aramaswamis at gmail.com>
Co-Authored-By: Carol Willing <carolcode at willingconsulting.com>
files:
M Doc/library/io.rst
diff --git a/Doc/library/io.rst b/Doc/library/io.rst
index 70e01153d419..f0987da9b6a4 100644
--- a/Doc/library/io.rst
+++ b/Doc/library/io.rst
@@ -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:`TextIOBase` ABC, another subclass of :class:`IOBase`, deals with
+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 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.
More information about the Python-checkins
mailing list