Doc/library/io.rst

   1 :mod:`io` --- Core tools for working with streams
   2 =================================================
   3
   4 .. module:: io
   5    :synopsis: Core tools for working with streams.
   6 .. moduleauthor:: Guido van Rossum <guido@python.org>
   7 .. moduleauthor:: Mike Verdone <mike.verdone@gmail.com>
   8 .. moduleauthor:: Mark Russell <mark.russell@zen.co.uk>
   9 .. sectionauthor:: Benjamin Peterson
  10 .. versionadded:: 2.6
  11
  12 The :mod:`io` module provides the Python interfaces to stream handling.  The
  13 builtin :func:`open` function is defined in this module.
  14
  15 At the top of the I/O hierarchy is the abstract base class :class:`IOBase`.  It
  16 defines the basic interface to a stream.  Note, however, that there is no
  17 seperation between reading and writing to streams; implementations are allowed
  18 to throw an :exc:`IOError` if they do not support a given operation.
  19
  20 Extending :class:`IOBase` is :class:`RawIOBase` which deals simply with the
  21 reading and writing of raw bytes to a stream.  :class:`FileIO` subclasses
  22 :class:`RawIOBase` to provide an interface to files in the machine's
  23 file system.
  24
  25 :class:`BufferedIOBase` deals with buffering on a raw byte stream
  26 (:class:`RawIOBase`).  Its subclasses, :class:`BufferedWriter`,
  27 :class:`BufferedReader`, and :class:`BufferedRWPair` buffer streams that are
  28 readable, writable, and both readable and writable.
  29 :class:`BufferedRandom` provides a buffered interface to random access
  30 streams.  :class:`BytesIO` is a simple stream of in-memory bytes.
  31
  32 Another :class:`IOBase` subclass, :class:`TextIOBase`, deals with
  33 streams whose bytes represent text, and handles encoding and decoding
  34 from and to strings. :class:`TextIOWrapper`, which extends it, is a
  35 buffered text interface to a buffered raw stream
  36 (:class:`BufferedIOBase`). Finally, :class:`StringIO` is an in-memory
  37 stream for text.
  38
  39 Argument names are not part of the specification, and only the arguments of
  40 :func:`open` are intended to be used as keyword arguments.
  41
  42
  43 Module Interface
  44 ----------------
  45
  46 .. data:: DEFAULT_BUFFER_SIZE
  47
  48    An int containing the default buffer size used by the module's buffered I/O
  49    classes.  :func:`open` uses the file's blksize (as obtained by
  50    :func:`os.stat`) if possible.
  51
  52 .. function:: open(file[, mode[, buffering[, encoding[, errors[, newline[, closefd=True]]]]]])
  53
  54    Open *file* and return a stream.  If the file cannot be opened, an
  55    :exc:`IOError` is raised.
  56
  57    *file* is either a string giving the name (and the path if the file isn't in
  58    the current working directory) of the file to be opened or a file
  59    descriptor of the file to be opened.  (If a file descriptor is given,
  60    for example, from :func:`os.fdopen`, it is closed when the returned
  61    I/O object is closed, unless *closefd* is set to ``False``.)
  62
  63    *mode* is an optional string that specifies the mode in which the file is
  64    opened.  It defaults to ``'r'`` which means open for reading in text mode.
  65    Other common values are ``'w'`` for writing (truncating the file if it
  66    already exists), and ``'a'`` for appending (which on *some* Unix systems,
  67    means that *all* writes append to the end of the file regardless of the
  68    current seek position).  In text mode, if *encoding* is not specified the
  69    encoding used is platform dependent. (For reading and writing raw bytes use
  70    binary mode and leave *encoding* unspecified.)  The available modes are:
  71
  72    ========= ===============================================================
  73    Character Meaning
  74    --------- ---------------------------------------------------------------
  75    ``'r'``   open for reading (default)
  76    ``'w'``   open for writing, truncating the file first
  77    ``'a'``   open for writing, appending to the end of the file if it exists
  78    ``'b'``   binary mode
  79    ``'t'``   text mode (default)
  80    ``'+'``   open a disk file for updating (reading and writing)
  81    ``'U'``   universal newline mode (for backwards compatibility; should
  82              not be used in new code)
  83    ========= ===============================================================
  84
  85    The default mode is ``'rt'`` (open for reading text).  For binary random
  86    access, the mode ``'w+b'`` opens and truncates the file to 0 bytes, while
  87    ``'r+b'`` opens the file without truncation.
  88
  89    Python distinguishes between files opened in binary and text modes, even when
  90    the underlying operating system doesn't.  Files opened in binary mode
  91    (including ``'b'`` in the *mode* argument) return contents as ``bytes``
  92    objects without any decoding.  In text mode (the default, or when ``'t'`` is
  93    included in the *mode* argument), the contents of the file are returned as
  94    strings, the bytes having been first decoded using a platform-dependent
  95    encoding or using the specified *encoding* if given.
  96
  97    *buffering* is an optional integer used to set the buffering policy.  By
  98    default full buffering is on.  Pass 0 to switch buffering off (only allowed
  99    in binary mode), 1 to set line buffering, and an integer > 1 for full
 100    buffering.
 101
 102    *encoding* is the name of the encoding used to decode or encode the file.
 103    This should only be used in text mode.  The default encoding is platform
 104    dependent, but any encoding supported by Python can be used.  See the
 105    :mod:`codecs` module for the list of supported encodings.
 106
 107    *errors* is an optional string that specifies how encoding and decoding
 108    errors are to be handled.  Pass ``'strict'`` to raise a :exc:`ValueError`
 109    exception if there is an encoding error (the default of ``None`` has the same
 110    effect), or pass ``'ignore'`` to ignore errors.  (Note that ignoring encoding
 111    errors can lead to data loss.)  ``'replace'`` causes a replacement marker
 112    (such as ``'?'``) to be inserted where there is malformed data.  When
 113    writing, ``'xmlcharrefreplace'`` (replace with the appropriate XML character
 114    reference) or ``'backslashreplace'`` (replace with backslashed escape
 115    sequences) can be used.  Any other error handling name that has been
 116    registered with :func:`codecs.register_error` is also valid.
 117
 118    *newline* controls how universal newlines works (it only applies to text
 119    mode).  It can be ``None``, ``''``, ``'\n'``, ``'\r'``, and ``'\r\n'``.  It
 120    works as follows:
 121
 122    * On input, if *newline* is ``None``, universal newlines mode is enabled.
 123      Lines in the input can end in ``'\n'``, ``'\r'``, or ``'\r\n'``, and these
 124      are translated into ``'\n'`` before being returned to the caller.  If it is
 125      ``''``, universal newline mode is enabled, but line endings are returned to
 126      the caller untranslated.  If it has any of the other legal values, input
 127      lines are only terminated by the given string, and the line ending is
 128      returned to the caller untranslated.
 129
 130    * On output, if *newline* is ``None``, any ``'\n'`` characters written are
 131      translated to the system default line separator, :data:`os.linesep`.  If
 132      *newline* is ``''``, no translation takes place.  If *newline* is any of
 133      the other legal values, any ``'\n'`` characters written are translated to
 134      the given string.
 135
 136    If *closefd* is ``False`` and a file descriptor rather than a
 137    filename was given, the underlying file descriptor will be kept open
 138    when the file is closed.  If a filename is given *closefd* has no
 139    effect but must be ``True`` (the default).
 140
 141    The type of file object returned by the :func:`open` function depends
 142    on the mode.  When :func:`open` is used to open a file in a text mode
 143    (``'w'``, ``'r'``, ``'wt'``, ``'rt'``, etc.), it returns a
 144    :class:`TextIOWrapper`. When used to open a file in a binary mode,
 145    the returned class varies: in read binary mode, it returns a
 146    :class:`BufferedReader`; in write binary and append binary modes, it
 147    returns a :class:`BufferedWriter`, and in read/write mode, it returns
 148    a :class:`BufferedRandom`.
 149
 150    It is also possible to use a string or bytearray as a file for both reading
 151    and writing.  For strings :class:`StringIO` can be used like a file opened in
 152    a text mode, and for bytearrays a :class:`BytesIO` can be used like a
 153    file opened in a binary mode.
 154
 155
 156 .. exception:: BlockingIOError
 157
 158    Error raised when blocking would occur on a non-blocking stream.  It inherits
 159    :exc:`IOError`.
 160
 161    In addition to those of :exc:`IOError`, :exc:`BlockingIOError` has one
 162    attribute:
 163
 164    .. attribute:: characters_written
 165
 166       An integer containing the number of characters written to the stream
 167       before it blocked.
 168
 169
 170 .. exception:: UnsupportedOperation
 171
 172    An exception inheriting :exc:`IOError` and :exc:`ValueError` that is raised
 173    when an unsupported operation is called on a stream.
 174
 175
 176 I/O Base Classes
 177 ----------------
 178
 179 .. class:: IOBase
 180
 181    The abstract base class for all I/O classes, acting on streams of bytes.
 182    There is no public constructor.
 183
 184    This class provides empty abstract implementations for many methods
 185    that derived classes can override selectively; the default
 186    implementations represent a file that cannot be read, written or
 187    seeked.
 188
 189    Even though :class:`IOBase` does not declare :meth:`read`, :meth:`readinto`,
 190    or :meth:`write` because their signatures will vary, implementations and
 191    clients should consider those methods part of the interface.  Also,
 192    implementations may raise a :exc:`IOError` when operations they do not
 193    support are called.
 194
 195    The basic type used for binary data read from or written to a file is
 196    :class:`bytes`.  :class:`bytearray`\s are accepted too, and in some cases
 197    (such as :class:`readinto`) required.  Text I/O classes work with
 198    :class:`str` data.
 199
 200    Note that calling any method (even inquiries) on a closed stream is
 201    undefined.  Implementations may raise :exc:`IOError` in this case.
 202
 203    IOBase (and its subclasses) support the iterator protocol, meaning that an
 204    :class:`IOBase` object can be iterated over yielding the lines in a stream.
 205
 206    IOBase is also a context manager and therefore supports the
 207    :keyword:`with` statement.  In this example, *file* is closed after the
 208    :keyword:`with` statement's suite is finished---even if an exception occurs::
 209
 210       with open('spam.txt', 'w') as file:
 211           file.write('Spam and eggs!')
 212
 213    :class:`IOBase` provides these data attributes and methods:
 214
 215    .. method:: close()
 216
 217       Flush and close this stream.  This method has no effect if the file is
 218       already closed.
 219
 220    .. attribute:: closed
 221
 222       True if the stream is closed.
 223
 224    .. method:: fileno()
 225
 226       Return the underlying file descriptor (an integer) of the stream if it
 227       exists.  An :exc:`IOError` is raised if the IO object does not use a file
 228       descriptor.
 229
 230    .. method:: flush()
 231
 232       Flush the write buffers of the stream if applicable.  This does nothing
 233       for read-only and non-blocking streams.
 234
 235    .. method:: isatty()
 236
 237       Return ``True`` if the stream is interactive (i.e., connected to
 238       a terminal/tty device).
 239
 240    .. method:: readable()
 241
 242       Return ``True`` if the stream can be read from.  If False, :meth:`read`
 243       will raise :exc:`IOError`.
 244
 245    .. method:: readline([limit])
 246
 247       Read and return one line from the stream.  If *limit* is specified, at
 248       most *limit* bytes will be read.
 249
 250       The line terminator is always ``b'\n'`` for binary files; for text files,
 251       the *newlines* argument to :func:`open` can be used to select the line
 252       terminator(s) recognized.
 253
 254    .. method:: readlines([hint])
 255
 256       Read and return a list of lines from the stream.  *hint* can be specified
 257       to control the number of lines read: no more lines will be read if the
 258       total size (in bytes/characters) of all lines so far exceeds *hint*.
 259
 260    .. method:: seek(offset[, whence])
 261
 262       Change the stream position to the given byte *offset*.  *offset* is
 263       interpreted relative to the position indicated by *whence*.  Values for
 264       *whence* are:
 265
 266       * ``0`` -- start of the stream (the default); *offset* should be zero or positive
 267       * ``1`` -- current stream position; *offset* may be negative
 268       * ``2`` -- end of the stream; *offset* is usually negative
 269
 270       Return the new absolute position.
 271
 272    .. method:: seekable()
 273
 274       Return ``True`` if the stream supports random access.  If ``False``,
 275       :meth:`seek`, :meth:`tell` and :meth:`truncate` will raise :exc:`IOError`.
 276
 277    .. method:: tell()
 278
 279       Return the current stream position.
 280
 281    .. method:: truncate([size])
 282
 283       Truncate the file to at most *size* bytes.  *size* defaults to the current
 284       file position, as returned by :meth:`tell`.
 285
 286    .. method:: writable()
 287
 288       Return ``True`` if the stream supports writing.  If ``False``,
 289       :meth:`write` and :meth:`truncate` will raise :exc:`IOError`.
 290
 291    .. method:: writelines(lines)
 292
 293       Write a list of lines to the stream.  Line separators are not added, so it
 294       is usual for each of the lines provided to have a line separator at the
 295       end.
 296
 297
 298 .. class:: RawIOBase
 299
 300    Base class for raw binary I/O.  It inherits :class:`IOBase`.  There is no
 301    public constructor.
 302
 303    In addition to the attributes and methods from :class:`IOBase`,
 304    RawIOBase provides the following methods:
 305
 306    .. method:: read([n])
 307
 308       Read and return all the bytes from the stream until EOF, or if *n* is
 309       specified, up to *n* bytes.  Only one system call is ever made.  An empty
 310       bytes object is returned on EOF; ``None`` is returned if the object is set
 311       not to block and has no data to read.
 312
 313    .. method:: readall()
 314
 315       Read and return all the bytes from the stream until EOF, using multiple
 316       calls to the stream if necessary.
 317
 318    .. method:: readinto(b)
 319
 320       Read up to len(b) bytes into bytearray *b* and return the number of bytes
 321       read.
 322
 323    .. method:: write(b)
 324
 325       Write the given bytes or bytearray object, *b*, to the underlying raw
 326       stream and return the number of bytes written (This is never less than
 327       ``len(b)``, since if the write fails, an :exc:`IOError` will be raised).
 328
 329
 330 Raw File I/O
 331 ------------
 332
 333 .. class:: FileIO(name[, mode])
 334
 335    :class:`FileIO` represents a file containing bytes data.  It implements
 336    the :class:`RawIOBase` interface (and therefore the :class:`IOBase`
 337    interface, too).
 338
 339    The *mode* can be ``'r'``, ``'w'`` or ``'a'`` for reading (default), writing,
 340    or appending.  The file will be created if it doesn't exist when opened for
 341    writing or appending; it will be truncated when opened for writing.  Add a
 342    ``'+'`` to the mode to allow simultaneous reading and writing.
 343
 344    In addition to the attributes and methods from :class:`IOBase` and
 345    :class:`RawIOBase`, :class:`FileIO` provides the following data
 346    attributes and methods:
 347
 348    .. attribute:: mode
 349
 350       The mode as given in the constructor.
 351
 352    .. attribute:: name
 353
 354       The file name.  This is the file descriptor of the file when no name is
 355       given in the constructor.
 356
 357    .. method:: read([n])
 358
 359       Read and return at most *n* bytes.  Only one system call is made, so it is
 360       possible that less data than was requested is returned.  Use :func:`len`
 361       on the returned bytes object to see how many bytes were actually returned.
 362       (In non-blocking mode, ``None`` is returned when no data is available.)
 363
 364    .. method:: readall()
 365
 366       Read and return the entire file's contents in a single bytes object.  As
 367       much as immediately available is returned in non-blocking mode.  If the
 368       EOF has been reached, ``b''`` is returned.
 369
 370    .. method:: write(b)
 371
 372       Write the bytes or bytearray object, *b*, to the file, and return
 373       the number actually written. Only one system call is made, so it
 374       is possible that only some of the data is written.
 375
 376    Note that the inherited ``readinto()`` method should not be used on
 377    :class:`FileIO` objects.
 378
 379
 380 Buffered Streams
 381 ----------------
 382
 383 .. class:: BufferedIOBase
 384
 385    Base class for streams that support buffering.  It inherits :class:`IOBase`.
 386    There is no public constructor.
 387
 388    The main difference with :class:`RawIOBase` is that the :meth:`read` method
 389    supports omitting the *size* argument, and does not have a default
 390    implementation that defers to :meth:`readinto`.
 391
 392    In addition, :meth:`read`, :meth:`readinto`, and :meth:`write` may raise
 393    :exc:`BlockingIOError` if the underlying raw stream is in non-blocking mode
 394    and not ready; unlike their raw counterparts, they will never return
 395    ``None``.
 396
 397    A typical implementation should not inherit from a :class:`RawIOBase`
 398    implementation, but wrap one like :class:`BufferedWriter` and
 399    :class:`BufferedReader`.
 400
 401    :class:`BufferedIOBase` provides or overrides these methods in addition to
 402    those from :class:`IOBase`:
 403
 404    .. method:: read([n])
 405
 406       Read and return up to *n* bytes.  If the argument is omitted, ``None``, or
 407       negative, data is read and returned until EOF is reached.  An empty bytes
 408       object is returned if the stream is already at EOF.
 409
 410       If the argument is positive, and the underlying raw stream is not
 411       interactive, multiple raw reads may be issued to satisfy the byte count
 412       (unless EOF is reached first).  But for interactive raw streams, at most
 413       one raw read will be issued, and a short result does not imply that EOF is
 414       imminent.
 415
 416       A :exc:`BlockingIOError` is raised if the underlying raw stream has no
 417       data at the moment.
 418
 419    .. method:: readinto(b)
 420
 421       Read up to len(b) bytes into bytearray *b* and return the number of bytes
 422       read.
 423
 424       Like :meth:`read`, multiple reads may be issued to the underlying raw
 425       stream, unless the latter is 'interactive.'
 426
 427       A :exc:`BlockingIOError` is raised if the underlying raw stream has no
 428       data at the moment.
 429
 430    .. method:: write(b)
 431
 432       Write the given bytes or bytearray object, *b*, to the underlying raw
 433       stream and return the number of bytes written (never less than ``len(b)``,
 434       since if the write fails an :exc:`IOError` will be raised).
 435
 436       A :exc:`BlockingIOError` is raised if the buffer is full, and the
 437       underlying raw stream cannot accept more data at the moment.
 438
 439
 440 .. class:: BytesIO([initial_bytes])
 441
 442    A stream implementation using an in-memory bytes buffer.  It inherits
 443    :class:`BufferedIOBase`.
 444
 445    The argument *initial_bytes* is an optional initial bytearray.
 446
 447    :class:`BytesIO` provides or overrides these methods in addition to those
 448    from :class:`BufferedIOBase` and :class:`IOBase`:
 449
 450    .. method:: getvalue()
 451
 452       Return ``bytes`` containing the entire contents of the buffer.
 453
 454    .. method:: read1()
 455
 456       In :class:`BytesIO`, this is the same as :meth:`read`.
 457
 458    .. method:: truncate([size])
 459
 460       Truncate the buffer to at most *size* bytes.  *size* defaults to the
 461       current stream position, as returned by :meth:`tell`.
 462
 463
 464 .. class:: BufferedReader(raw[, buffer_size])
 465
 466    A buffer for a readable, sequential :class:`RawIOBase` object.  It inherits
 467    :class:`BufferedIOBase`.
 468
 469    The constructor creates a :class:`BufferedReader` for the given readable
 470    *raw* stream and *buffer_size*.  If *buffer_size* is omitted,
 471    :data:`DEFAULT_BUFFER_SIZE` is used.
 472
 473    :class:`BufferedReader` provides or overrides these methods in addition to
 474    those from :class:`BufferedIOBase` and :class:`IOBase`:
 475
 476    .. method:: peek([n])
 477
 478       Return 1 (or *n* if specified) bytes from a buffer without advancing the
 479       position.  Only a single read on the raw stream is done to satisfy the
 480       call. The number of bytes returned may be less than requested since at
 481       most all the buffer's bytes from the current position to the end are
 482       returned.
 483
 484    .. method:: read([n])
 485
 486       Read and return *n* bytes, or if *n* is not given or negative, until EOF
 487       or if the read call would block in non-blocking mode.
 488
 489    .. method:: read1(n)
 490
 491       Read and return up to *n* bytes with only one call on the raw stream.  If
 492       at least one byte is buffered, only buffered bytes are returned.
 493       Otherwise, one raw stream read call is made.
 494
 495
 496 .. class:: BufferedWriter(raw[, buffer_size[, max_buffer_size]])
 497
 498    A buffer for a writeable sequential RawIO object.  It inherits
 499    :class:`BufferedIOBase`.
 500
 501    The constructor creates a :class:`BufferedWriter` for the given writeable
 502    *raw* stream.  If the *buffer_size* is not given, it defaults to
 503    :data:`DEAFULT_BUFFER_SIZE`.  If *max_buffer_size* is omitted, it defaults to
 504    twice the buffer size.
 505
 506    :class:`BufferedWriter` provides or overrides these methods in addition to
 507    those from :class:`BufferedIOBase` and :class:`IOBase`:
 508
 509    .. method:: flush()
 510
 511       Force bytes held in the buffer into the raw stream.  A
 512       :exc:`BlockingIOError` should be raised if the raw stream blocks.
 513
 514    .. method:: write(b)
 515
 516       Write the bytes or bytearray object, *b*, onto the raw stream and return
 517       the number of bytes written.  A :exc:`BlockingIOError` is raised when the
 518       raw stream blocks.
 519
 520
 521 .. class:: BufferedRWPair(reader, writer[, buffer_size[, max_buffer_size]])
 522
 523    A combined buffered writer and reader object for a raw stream that can be
 524    written to and read from.  It has and supports both :meth:`read`, :meth:`write`,
 525    and their variants.  This is useful for sockets and two-way pipes.
 526    It inherits :class:`BufferedIOBase`.
 527
 528    *reader* and *writer* are :class:`RawIOBase` objects that are readable and
 529    writeable respectively.  If the *buffer_size* is omitted it defaults to
 530    :data:`DEFAULT_BUFFER_SIZE`.  The *max_buffer_size* (for the buffered writer)
 531    defaults to twice the buffer size.
 532
 533    :class:`BufferedRWPair` implements all of :class:`BufferedIOBase`\'s methods.
 534
 535
 536 .. class:: BufferedRandom(raw[, buffer_size[, max_buffer_size]])
 537
 538    A buffered interface to random access streams.  It inherits
 539    :class:`BufferedReader` and :class:`BufferedWriter`.
 540
 541    The constructor creates a reader and writer for a seekable raw stream, given
 542    in the first argument.  If the *buffer_size* is omitted it defaults to
 543    :data:`DEFAULT_BUFFER_SIZE`.  The *max_buffer_size* (for the buffered writer)
 544    defaults to twice the buffer size.
 545
 546    :class:`BufferedRandom` is capable of anything :class:`BufferedReader` or
 547    :class:`BufferedWriter` can do.
 548
 549
 550 Text I/O
 551 --------
 552
 553 .. class:: TextIOBase
 554
 555    Base class for text streams.  This class provides a character and line based
 556    interface to stream I/O.  There is no :meth:`readinto` method because
 557    Python's character strings are immutable.  It inherits :class:`IOBase`.
 558    There is no public constructor.
 559
 560    :class:`TextIOBase` provides or overrides these data attributes and
 561    methods in addition to those from :class:`IOBase`:
 562
 563    .. attribute:: encoding
 564
 565       The name of the encoding used to decode the stream's bytes into
 566       strings, and to encode strings into bytes.
 567
 568    .. attribute:: newlines
 569
 570       A string, a tuple of strings, or ``None``, indicating the newlines
 571       translated so far.
 572
 573    .. method:: read(n)
 574
 575       Read and return at most *n* characters from the stream as a single
 576       :class:`str`.  If *n* is negative or ``None``, reads to EOF.
 577
 578    .. method:: readline()
 579
 580       Read until newline or EOF and return a single ``str``.  If the stream is
 581       already at EOF, an empty string is returned.
 582
 583    .. method:: write(s)
 584
 585       Write the string *s* to the stream and return the number of characters
 586       written.
 587
 588
 589 .. class:: TextIOWrapper(buffer[, encoding[, errors[, newline[, line_buffering]]]])
 590
 591    A buffered text stream over a :class:`BufferedIOBase` raw stream, *buffer*.
 592    It inherits :class:`TextIOBase`.
 593
 594    *encoding* gives the name of the encoding that the stream will be decoded or
 595    encoded with.  It defaults to :func:`locale.getpreferredencoding`.
 596
 597    *errors* is an optional string that specifies how encoding and decoding
 598    errors are to be handled.  Pass ``'strict'`` to raise a :exc:`ValueError`
 599    exception if there is an encoding error (the default of ``None`` has the same
 600    effect), or pass ``'ignore'`` to ignore errors.  (Note that ignoring encoding
 601    errors can lead to data loss.)  ``'replace'`` causes a replacement marker
 602    (such as ``'?'``) to be inserted where there is malformed data.  When
 603    writing, ``'xmlcharrefreplace'`` (replace with the appropriate XML character
 604    reference) or ``'backslashreplace'`` (replace with backslashed escape
 605    sequences) can be used.  Any other error handling name that has been
 606    registered with :func:`codecs.register_error` is also valid.
 607
 608    *newline* can be ``None``, ``''``, ``'\n'``, ``'\r'``, or ``'\r\n'``.  It
 609    controls the handling of line endings.  If it is ``None``, universal newlines
 610    is enabled.  With this enabled, on input, the lines endings ``'\n'``,
 611    ``'\r'``, or ``'\r\n'`` are translated to ``'\n'`` before being returned to
 612    the caller.  Conversely, on output, ``'\n'`` is translated to the system
 613    default line seperator, :data:`os.linesep`.  If *newline* is any other of its
 614    legal values, that newline becomes the newline when the file is read and it
 615    is returned untranslated.  On output, ``'\n'`` is converted to the *newline*.
 616
 617    If *line_buffering* is ``True``, :meth:`flush` is implied when a call to
 618    write contains a newline character.
 619
 620    :class:`TextIOWrapper` provides these data attributes in addition to those of
 621    :class:`TextIOBase` and its parents:
 622
 623    .. attribute:: errors
 624
 625       The encoding and decoding error setting.
 626
 627    .. attribute:: line_buffering
 628
 629       Whether line buffering is enabled.
 630
 631
 632 .. class:: StringIO([initial_value[, encoding[, errors[, newline]]]])
 633
 634    An in-memory stream for text.  It in inherits :class:`TextIOWrapper`.
 635
 636    Create a new StringIO stream with an inital value, encoding, error handling,
 637    and newline setting.  See :class:`TextIOWrapper`\'s constructor for more
 638    information.
 639
 640    :class:`StringIO` provides this method in addition to those from
 641    :class:`TextIOWrapper` and its parents:
 642
 643    .. method:: getvalue()
 644
 645       Return a ``str`` containing the entire contents of the buffer.
 646
 647
 648 .. class:: IncrementalNewlineDecoder
 649
 650    A helper codec that decodes newlines for universal newlines mode.  It
 651    inherits :class:`codecs.IncrementalDecoder`.
 652