8000 Improve the io module documentation (GH-15099) · python/cpython@3b58a70 · GitHub
[go: up one dir, main page]

Skip to content

Commit 3b58a70

Browse files
geryogamwillingc
andcommitted
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>
1 parent 574b324 commit 3b58a70

File tree

1 file changed

+61
-55
lines changed

1 file changed

+61
-55
lines changed

Doc/library/io.rst

Lines changed: 61 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -195,18 +195,18 @@ The :class:`RawIOBase` ABC extends :class:`IOBase`. It deals with the reading
195195
and writing of bytes to a stream. :class:`FileIO` subclasses :class:`RawIOBase`
196196
to provide an interface to files in the machine's file system.
197197

198-
The :class:`BufferedIOBase` ABC deals with buffering on a raw byte stream
199-
(:class:`RawIOBase`). Its subclasses, :class:`BufferedWriter`,
200-
:class:`BufferedReader`, and :class:`BufferedRWPair` buffer streams that are
201-
readable, writable, and both readable and writable. :class:`BufferedRandom`
202-
provides a buffered interface to random access streams. Another
203-
:class:`BufferedIOBase` subclass, :class:`BytesIO`, is a stream of in-memory
204-
bytes.
205-
206-
The :class:`TextIOBase` ABC, another subclass of :class:`IOBase`, deals with
198+
The :class:`BufferedIOBase` ABC extends :class:`IOBase`. It deals with
199+
buffering on a raw binary stream (:class:`RawIOBase`). Its subclasses,
200+
:class:`BufferedWriter`, :class:`BufferedReader`, and :class:`BufferedRWPair`
201+
buffer raw binary streams that are readable, writable, and both readable and writable,
202+
respectively. :class:`BufferedRandom` provides a buffered interface to seekable streams.
203+
Another :class:`BufferedIOBase` subclass, :class:`BytesIO`, is a stream of
204+
in-memory bytes.
205+
206+
The :class:`TextIOBase` ABC extends :class:`IOBase`. It deals with
207207
streams whose bytes represent text, and handles encoding and decoding to and
208-
from strings. :class:`TextIOWrapper`, which extends it, is a buffered text
209-
interface to a buffered raw stream (:class:`BufferedIOBase`). Finally,
208+
from strings. :class:`TextIOWrapper`, which extends :class:`TextIOBase`, is a buffered text
209+
interface to a buffered raw stream (:class:`BufferedIOBase`). Finally,
210210
:class:`StringIO` is an in-memory stream for text.
211211

212212
Argument names are not part of the specification, and only the arguments of
@@ -391,15 +391,16 @@ I/O Base Classes
391391

392392
.. class:: RawIOBase
393393

394-
Base class for raw binary I/O. It inherits :class:`IOBase`. There is no
394+
Base class for raw binary streams. It inherits :class:`IOBase`. There is no
395395
public constructor.
396396

397-
Raw binary I/O typically provides low-level access to an underlying OS
398-
device or API, and does not try to encapsulate it in high-level primitives
399-
(this is left to Buffered I/O and Text I/O, described later in this page).
397+
Raw binary streams typically provide low-level access to an underlying OS
398+
device or API, and do not try to encapsulate it in high-level primitives
399+
(this functionality is done at a higher-level in buffered binary streams and text streams, described later
400+
in this page).
400401

401-
In addition to the attributes and methods from :class:`IOBase`,
402-
:class:`RawIOBase` provides the following methods:
402+
:class:`RawIOBase` provides these methods in addition to those from
403+
:class:`IOBase`:
403404

404405
.. method:: read(size=-1)
405406

@@ -463,8 +464,8 @@ I/O Base Classes
463464
:class:`RawIOBase` implementation, but wrap one, like
464465
:class:`BufferedWriter` and :class:`BufferedReader` do.
465466

466-
:class:`BufferedIOBase` provides or overrides these methods and attribute in
467-
addition to those from :class:`IOBase`:
467+
:class:`BufferedIOBase` provides or overrides these data attributes and
468+
methods in addition to those from :class:`IOBase`:
468469

469470
.. attribute:: raw
470471

@@ -557,9 +558,8 @@ Raw File I/O
557558

558559
.. class:: FileIO(name, mode='r', closefd=True, opener=None)
559560

560-
:class:`FileIO` represents an OS-level file containing bytes data.
561-
It implements the :class:`RawIOBase` interface (and therefore the
562-
:class:`IOBase` interface, too).
561+
A raw binary stream representing an OS-level file containing bytes data. It
562+
inherits :class:`RawIOBase`.
563563

564564
The *name* can be one of two things:
565565

@@ -600,9 +600,8 @@ Raw File I/O
600600
.. versionchanged:: 3.4
601601
The file is now non-inheritable.
602602

603-
In addition to the attributes and methods from :class:`IOBase` and
604-
:class:`RawIOBase`, :class:`FileIO` provides the following data
605-
attributes:
603+
:class:`FileIO` provides these data attributes in addition to those from
604+
:class:`RawIOBase` and :class:`IOBase`:
606605

607606
.. attribute:: mode
608607

@@ -622,7 +621,7 @@ than raw I/O does.
622621

623622
.. class:: BytesIO([initial_bytes])
624623

625-
A stream implementation using an in-memory bytes buffer. It inherits
624+
A binary stream using an in-memory bytes buffer. It inherits
626625
:class:`BufferedIOBase`. The buffer is discarded when the
627626
:meth:`~IOBase.close` method is called.
628627

@@ -670,8 +669,10 @@ than raw I/O does.
670669

671670
.. class:: BufferedReader(raw, buffer_size=DEFAULT_BUFFER_SIZE)
672671

673-
A buffer providing higher-level access to a readable, sequential
674-
:class:`RawIOBase` object. It inherits :class:`BufferedIOBase`.
672+
A buffered binary stream providing higher-level access to a readable, non
673+
seekable :class:`RawIOBase` raw binary stream. It inherits
674+
:class:`BufferedIOBase`.
675+
675676
When reading data from this object, a larger amount of data may be
676677
requested from the underlying raw stream, and kept in an internal buffer.
677678
The buffered data can then be returned directly on subsequent reads.
@@ -706,8 +707,10 @@ than raw I/O does.
706707

707708
.. class:: BufferedWriter(raw, buffer_size=DEFAULT_BUFFER_SIZE)
708709

709-
A buffer providing higher-level access to a writeable, sequential
710-
:class:`RawIOBase` object. It inherits :class:`BufferedIOBase`.
710+
A buffered binary stream providing higher-level access to a writeable, non
711+
seekable :class:`RawIOBase` raw binary stream. It inherits
712+
:class:`BufferedIOBase`.
713+
711714
When writing to this object, data is normally placed into an internal
712715
buffer. The buffer will be written out to the underlying :class:`RawIOBase`
713716
object under various conditions, including:
@@ -739,8 +742,9 @@ than raw I/O does.
739742

740743
.. class:: BufferedRandom(raw, buffer_size=DEFAULT_BUFFER_SIZE)
741744

742-
A buffered interface to random access streams. It inherits
743-
:class:`BufferedReader` and :class:`BufferedWriter`.
745+
A buffered binary stream providing higher-level access to a seekable
746+
:class:`RawIOBase` raw binary stream. It inherits :class:`BufferedReader`
747+
and :class:`BufferedWriter`.
744748

745749
The constructor creates a reader and writer for a seekable raw stream, given
746750
in the first argument. If the *buffer_size* is omitted it defaults to
@@ -753,9 +757,9 @@ than raw I/O does.
753757

754758
.. class:: BufferedRWPair(reader, writer, buffer_size=DEFAULT_BUFFER_SIZE)
755759

756-
A buffered I/O object combining two unidirectional :class:`RawIOBase`
757-
objects -- one readable, the other writeable -- into a single bidirectional
758-
endpoint. It inherits :class:`BufferedIOBase`.
760+
A buffered binary stream providing higher-level access to two non seekable
761+
:class:`RawIOBase` raw binary streams---one readable, the other writeable.
762+
It inherits :class:`BufferedIOBase`.
759763

760764
*reader* and *writer* are :class:`RawIOBase` objects that are readable and
761765
writeable respectively. If the *buffer_size* is omitted it defaults to
@@ -778,8 +782,8 @@ Text I/O
778782
.. class:: TextIOBase
779783

780784
Base class for text streams. This class provides a character and line based
781-
interface to stream I/O. It inherits :class:`IOBase`.
782-
There is no public constructor.
785+
interface to stream I/O. It inherits :class:`IOBase`. There is no public
786+
constructor.
783787

784788
:class:`TextIOBase` provides or overrides these data attributes and
785789
methods in addition to those from :class:`IOBase`:
@@ -867,8 +871,9 @@ Text I/O
867871
.. class:: TextIOWrapper(buffer, encoding=None, errors=None, newline=None, \
868872
line_buffering=False, write_through=False)
869873

870-
A buffered text stream over a :class:`BufferedIOBase` binary stream.
871-
It inherits :class:`TextIOBase`.
874+
A buffered text stream providing higher-level access to a
875+
:class:`BufferedIOBase` buffered binary stream. It inherits
876+
:class:`TextIOBase`.
872877

873878
*encoding* gives the name of the encoding that the stream will be decoded or
874879
encoded with. It defaults to
@@ -896,11 +901,11 @@ Text I/O
896901
* When reading input from the stream, if *newline* is ``None``,
897902
:term:`universal newlines` mode is enabled. Lines in the input can end in
898903
``'\n'``, ``'\r'``, or ``'\r\n'``, and these are translated into ``'\n'``
899-
before being returned to the caller. If it is ``''``, universal newlines
900-
mode is enabled, but line endings are returned to the caller untranslated.
901-
If it has any of the other legal values, input lines are only terminated
902-
by the given string, and the line ending is returned to the caller
903-
untranslated.
904+
before being returned to the caller. If *newline* is ``''``, universal
905+
newlines mode is enabled, but line endings are returned to the caller
906+
untranslated. If *newline* has any of the other legal values, input lines
907+
are only terminated by the given string, and the line ending is returned to
908+
the caller untranslated.
904909

905910
* When writing output to the stream, if *newline* is ``None``, any ``'\n'``
906911
characters written are translated to the system default line separator,
@@ -924,8 +929,8 @@ Text I/O
924929
locale encoding using :func:`locale.setlocale`, use the current locale
925930
encoding instead of the user preferred encoding.
926931

927-
:class:`TextIOWrapper` provides these members in addition to those of
928-
:class:`TextIOBase` and its parents:
932+
:class:`TextIOWrapper` provides these data attributes and methods in
933+
addition to those from :class:`TextIOBase` and :class:`IOBase`:
929934

930935
.. attribute:: line_buffering
931936

@@ -960,22 +965,23 @@ Text I/O
960965

961966
.. class:: StringIO(initial_value='', newline='\\n')
962967

963-
An in-memory stream for text I/O. The text buffer is discarded when the
964-
:meth:`~IOBase.close` method is called.
968+
A text stream using an in-memory text buffer. It inherits
969+
:class:`TextIOBase`.
970+
971+
The text buffer is discarded when the :meth:`~IOBase.close` method is
972+
called.
965973

966974
The initial value of the buffer can be set by providing *initial_value*.
967975
If newline translation is enabled, newlines will be encoded as if by
968976
:meth:`~TextIOBase.write`. The stream is positioned at the start of
969977
the buffer.
970978

971-
The *newline* argument works like that of :class:`TextIOWrapper`.
972-
The default is to consider only ``\n`` characters as ends of lines and
973-
to do no newline translation. If *newline* is set to ``None``,
974-
newlines are written as ``\n`` on all platforms, but universal
975-
newline decoding is still performed when reading.
979+
The *newline* argument works like that of :class:`TextIOWrapper`,
980+
except that when writing output to the stream, if *newline* is ``None``,
981+
newlines are written as ``\n`` on all platforms.
976982

977983
:class:`StringIO` provides this method in addition to those from
978-
:class:`TextIOBase` and its parents:
984+
:class:`TextIOBase` and :class:`IOBase`:
979985

980986
.. method:: getvalue()
981987

@@ -1066,5 +1072,5 @@ buffered object.
10661072

10671073
The above implicitly extends to text files, since the :func:`open()` function
10681074
will wrap a buffered object inside a :class:`TextIOWrapper`. This includes
1069-
standard streams and therefore affects the built-in function :func:`print()` as
1075+
standard streams and therefore affects the built-in :func:`print()` function as
10701076
well.

0 commit comments

Comments
 (0)
0