@@ -195,18 +195,18 @@ The :class:`RawIOBase` ABC extends :class:`IOBase`. It deals with the reading
195
195
and writing of bytes to a stream. :class: `FileIO ` subclasses :class: `RawIOBase `
196
196
to provide an interface to files in the machine's file system.
197
197
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
207
207
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,
210
210
:class: `StringIO ` is an in-memory stream for text.
211
211
212
212
Argument names are not part of the specification, and only the arguments of
@@ -391,15 +391,16 @@ I/O Base Classes
391
391
392
392
.. class :: RawIOBase
393
393
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
395
395
public constructor.
396
396
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).
400
401
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 ` :
403
404
404
405
.. method :: read(size=-1)
405
406
@@ -463,8 +464,8 @@ I/O Base Classes
463
464
:class: `RawIOBase ` implementation, but wrap one, like
464
465
:class: `BufferedWriter ` and :class: `BufferedReader ` do.
465
466
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 `:
468
469
469
470
.. attribute :: raw
470
471
@@ -557,9 +558,8 @@ Raw File I/O
557
558
558
559
.. class :: FileIO(name, mode='r', closefd=True, opener=None)
559
560
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 `.
563
563
564
564
The *name * can be one of two things:
565
565
@@ -600,9 +600,8 @@ Raw File I/O
600
600
.. versionchanged :: 3.4
601
601
The file is now non-inheritable.
602
602
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 `:
606
605
607
606
.. attribute :: mode
608
607
@@ -622,7 +621,7 @@ than raw I/O does.
622
621
623
622
.. class :: BytesIO([initial_bytes])
624
623
625
- A stream implementation using an in-memory bytes buffer. It inherits
624
+ A binary stream using an in-memory bytes buffer. It inherits
626
625
:class: `BufferedIOBase `. The buffer is discarded when the
627
626
:meth: `~IOBase.close ` method is called.
628
627
@@ -670,8 +669,10 @@ than raw I/O does.
670
669
671
670
.. class :: BufferedReader(raw, buffer_size=DEFAULT_BUFFER_SIZE)
672
671
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
+
675
676
When reading data from this object, a larger amount of data may be
676
677
requested from the underlying raw stream, and kept in an internal buffer.
677
678
The buffered data can then be returned directly on subsequent reads.
@@ -706,8 +707,10 @@ than raw I/O does.
706
707
707
708
.. class :: BufferedWriter(raw, buffer_size=DEFAULT_BUFFER_SIZE)
708
709
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
+
711
714
When writing to this object, data is normally placed into an internal
712
715
buffer. The buffer will be written out to the underlying :class: `RawIOBase `
713
716
object under various conditions, including:
@@ -739,8 +742,9 @@ than raw I/O does.
739
742
740
743
.. class :: BufferedRandom(raw, buffer_size=DEFAULT_BUFFER_SIZE)
741
744
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 `.
744
748
745
749
The constructor creates a reader and writer for a seekable raw stream, given
746
750
in the first argument. If the *buffer_size * is omitted it defaults to
@@ -753,9 +757,9 @@ than raw I/O does.
753
757
754
758
.. class :: BufferedRWPair(reader, writer, buffer_size=DEFAULT_BUFFER_SIZE)
755
759
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 `.
759
763
760
764
*reader * and *writer * are :class: `RawIOBase ` objects that are readable and
761
765
writeable respectively. If the *buffer_size * is omitted it defaults to
@@ -778,8 +782,8 @@ Text I/O
778
782
.. class :: TextIOBase
779
783
780
784
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.
783
787
784
788
:class: `TextIOBase ` provides or overrides these data attributes and
785
789
methods in addition to those from :class: `IOBase `:
@@ -867,8 +871,9 @@ Text I/O
867
871
.. class :: TextIOWrapper(buffer, encoding=None, errors=None, newline=None, \
868
872
line_buffering=False, write_through=False)
869
873
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 `.
872
877
873
878
*encoding * gives the name of the encoding that the stream will be decoded or
874
879
encoded with. It defaults to
@@ -896,11 +901,11 @@ Text I/O
896
901
* When reading input from the stream, if *newline * is ``None ``,
897
902
:term: `universal newlines ` mode is enabled. Lines in the input can end in
898
903
``'\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.
904
909
905
910
* When writing output to the stream, if *newline * is ``None ``, any ``'\n' ``
906
911
characters written are translated to the system default line separator,
@@ -924,8 +929,8 @@ Text I/O
924
929
locale encoding using :func: `locale.setlocale `, use the current locale
925
930
encoding instead of the user preferred encoding.
926
931
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 ` :
929
934
930
935
.. attribute :: line_buffering
931
936
@@ -960,22 +965,23 @@ Text I/O
960
965
961
966
.. class :: StringIO(initial_value='', newline='\\n')
962
967
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.
965
973
966
974
The initial value of the buffer can be set by providing *initial_value *.
967
975
If newline translation is enabled, newlines will be encoded as if by
968
976
:meth: `~TextIOBase.write `. The stream is positioned at the start of
969
977
the buffer.
970
978
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.
976
982
977
983
:class: `StringIO ` provides this method in addition to those from
978
- :class: `TextIOBase ` and its parents :
984
+ :class: `TextIOBase ` and :class: ` IOBase ` :
979
985
980
986
.. method :: getvalue()
981
987
@@ -1066,5 +1072,5 @@ buffered object.
1066
1072
1067
1073
The above implicitly extends to text files, since the :func: `open() ` function
1068
1074
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
1070
1076
well.
0 commit comments