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
.. 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)
: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
.. 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:
.. 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
.. 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.
.. 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.
.. 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:
.. 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
.. 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
.. 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`:
.. 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
* 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,
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
.. 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()
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.
projects / python / commitdiff