/Doc/library/io.rst
ReStructuredText | 654 lines | 448 code | 206 blank | 0 comment | 0 complexity | 20887414745f6d35c33098b74b2a837a MD5 | raw file
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 <benjamin@python.org> 10.. versionadded:: 2.6 11 12The :mod:`io` module provides the Python interfaces to stream handling. The 13builtin :func:`open` function is defined in this module. 14 15At the top of the I/O hierarchy is the abstract base class :class:`IOBase`. It 16defines the basic interface to a stream. Note, however, that there is no 17separation between reading and writing to streams; implementations are allowed 18to throw an :exc:`IOError` if they do not support a given operation. 19 20Extending :class:`IOBase` is :class:`RawIOBase` which deals simply with the 21reading and writing of raw bytes to a stream. :class:`FileIO` subclasses 22:class:`RawIOBase` to provide an interface to files in the machine's 23file 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 28readable, writable, and both readable and writable. 29:class:`BufferedRandom` provides a buffered interface to random access 30streams. :class:`BytesIO` is a simple stream of in-memory bytes. 31 32Another :class:`IOBase` subclass, :class:`TextIOBase`, deals with 33streams whose bytes represent text, and handles encoding and decoding 34from and to strings. :class:`TextIOWrapper`, which extends it, is a 35buffered text interface to a buffered raw stream 36(:class:`BufferedIOBase`). Finally, :class:`StringIO` is an in-memory 37stream for text. 38 39Argument 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 43Module 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 176I/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. Once the file is closed, any operation on the file 219 (e.g. reading or writing) will raise an :exc:`IOError`. The internal 220 file descriptor isn't closed if *closefd* was False. 221 222 .. attribute:: closed 223 224 True if the stream is closed. 225 226 .. method:: fileno() 227 228 Return the underlying file descriptor (an integer) of the stream if it 229 exists. An :exc:`IOError` is raised if the IO object does not use a file 230 descriptor. 231 232 .. method:: flush() 233 234 Flush the write buffers of the stream if applicable. This does nothing 235 for read-only and non-blocking streams. 236 237 .. method:: isatty() 238 239 Return ``True`` if the stream is interactive (i.e., connected to 240 a terminal/tty device). 241 242 .. method:: readable() 243 244 Return ``True`` if the stream can be read from. If False, :meth:`read` 245 will raise :exc:`IOError`. 246 247 .. method:: readline([limit]) 248 249 Read and return one line from the stream. If *limit* is specified, at 250 most *limit* bytes will be read. 251 252 The line terminator is always ``b'\n'`` for binary files; for text files, 253 the *newlines* argument to :func:`open` can be used to select the line 254 terminator(s) recognized. 255 256 .. method:: readlines([hint]) 257 258 Read and return a list of lines from the stream. *hint* can be specified 259 to control the number of lines read: no more lines will be read if the 260 total size (in bytes/characters) of all lines so far exceeds *hint*. 261 262 .. method:: seek(offset[, whence]) 263 264 Change the stream position to the given byte *offset*. *offset* is 265 interpreted relative to the position indicated by *whence*. Values for 266 *whence* are: 267 268 * ``0`` -- start of the stream (the default); *offset* should be zero or positive 269 * ``1`` -- current stream position; *offset* may be negative 270 * ``2`` -- end of the stream; *offset* is usually negative 271 272 Return the new absolute position. 273 274 .. method:: seekable() 275 276 Return ``True`` if the stream supports random access. If ``False``, 277 :meth:`seek`, :meth:`tell` and :meth:`truncate` will raise :exc:`IOError`. 278 279 .. method:: tell() 280 281 Return the current stream position. 282 283 .. method:: truncate([size]) 284 285 Truncate the file to at most *size* bytes. *size* defaults to the current 286 file position, as returned by :meth:`tell`. 287 288 .. method:: writable() 289 290 Return ``True`` if the stream supports writing. If ``False``, 291 :meth:`write` and :meth:`truncate` will raise :exc:`IOError`. 292 293 .. method:: writelines(lines) 294 295 Write a list of lines to the stream. Line separators are not added, so it 296 is usual for each of the lines provided to have a line separator at the 297 end. 298 299 300.. class:: RawIOBase 301 302 Base class for raw binary I/O. It inherits :class:`IOBase`. There is no 303 public constructor. 304 305 In addition to the attributes and methods from :class:`IOBase`, 306 RawIOBase provides the following methods: 307 308 .. method:: read([n]) 309 310 Read and return all the bytes from the stream until EOF, or if *n* is 311 specified, up to *n* bytes. Only one system call is ever made. An empty 312 bytes object is returned on EOF; ``None`` is returned if the object is set 313 not to block and has no data to read. 314 315 .. method:: readall() 316 317 Read and return all the bytes from the stream until EOF, using multiple 318 calls to the stream if necessary. 319 320 .. method:: readinto(b) 321 322 Read up to len(b) bytes into bytearray *b* and return the number of bytes 323 read. 324 325 .. method:: write(b) 326 327 Write the given bytes or bytearray object, *b*, to the underlying raw 328 stream and return the number of bytes written (This is never less than 329 ``len(b)``, since if the write fails, an :exc:`IOError` will be raised). 330 331 332Raw File I/O 333------------ 334 335.. class:: FileIO(name[, mode]) 336 337 :class:`FileIO` represents a file containing bytes data. It implements 338 the :class:`RawIOBase` interface (and therefore the :class:`IOBase` 339 interface, too). 340 341 The *mode* can be ``'r'``, ``'w'`` or ``'a'`` for reading (default), writing, 342 or appending. The file will be created if it doesn't exist when opened for 343 writing or appending; it will be truncated when opened for writing. Add a 344 ``'+'`` to the mode to allow simultaneous reading and writing. 345 346 In addition to the attributes and methods from :class:`IOBase` and 347 :class:`RawIOBase`, :class:`FileIO` provides the following data 348 attributes and methods: 349 350 .. attribute:: mode 351 352 The mode as given in the constructor. 353 354 .. attribute:: name 355 356 The file name. This is the file descriptor of the file when no name is 357 given in the constructor. 358 359 .. method:: read([n]) 360 361 Read and return at most *n* bytes. Only one system call is made, so it is 362 possible that less data than was requested is returned. Use :func:`len` 363 on the returned bytes object to see how many bytes were actually returned. 364 (In non-blocking mode, ``None`` is returned when no data is available.) 365 366 .. method:: readall() 367 368 Read and return the entire file's contents in a single bytes object. As 369 much as immediately available is returned in non-blocking mode. If the 370 EOF has been reached, ``b''`` is returned. 371 372 .. method:: write(b) 373 374 Write the bytes or bytearray object, *b*, to the file, and return 375 the number actually written. Only one system call is made, so it 376 is possible that only some of the data is written. 377 378 Note that the inherited ``readinto()`` method should not be used on 379 :class:`FileIO` objects. 380 381 382Buffered Streams 383---------------- 384 385.. class:: BufferedIOBase 386 387 Base class for streams that support buffering. It inherits :class:`IOBase`. 388 There is no public constructor. 389 390 The main difference with :class:`RawIOBase` is that the :meth:`read` method 391 supports omitting the *size* argument, and does not have a default 392 implementation that defers to :meth:`readinto`. 393 394 In addition, :meth:`read`, :meth:`readinto`, and :meth:`write` may raise 395 :exc:`BlockingIOError` if the underlying raw stream is in non-blocking mode 396 and not ready; unlike their raw counterparts, they will never return 397 ``None``. 398 399 A typical implementation should not inherit from a :class:`RawIOBase` 400 implementation, but wrap one like :class:`BufferedWriter` and 401 :class:`BufferedReader`. 402 403 :class:`BufferedIOBase` provides or overrides these methods in addition to 404 those from :class:`IOBase`: 405 406 .. method:: read([n]) 407 408 Read and return up to *n* bytes. If the argument is omitted, ``None``, or 409 negative, data is read and returned until EOF is reached. An empty bytes 410 object is returned if the stream is already at EOF. 411 412 If the argument is positive, and the underlying raw stream is not 413 interactive, multiple raw reads may be issued to satisfy the byte count 414 (unless EOF is reached first). But for interactive raw streams, at most 415 one raw read will be issued, and a short result does not imply that EOF is 416 imminent. 417 418 A :exc:`BlockingIOError` is raised if the underlying raw stream has no 419 data at the moment. 420 421 .. method:: readinto(b) 422 423 Read up to len(b) bytes into bytearray *b* and return the number of bytes 424 read. 425 426 Like :meth:`read`, multiple reads may be issued to the underlying raw 427 stream, unless the latter is 'interactive.' 428 429 A :exc:`BlockingIOError` is raised if the underlying raw stream has no 430 data at the moment. 431 432 .. method:: write(b) 433 434 Write the given bytes or bytearray object, *b*, to the underlying raw 435 stream and return the number of bytes written (never less than ``len(b)``, 436 since if the write fails an :exc:`IOError` will be raised). 437 438 A :exc:`BlockingIOError` is raised if the buffer is full, and the 439 underlying raw stream cannot accept more data at the moment. 440 441 442.. class:: BytesIO([initial_bytes]) 443 444 A stream implementation using an in-memory bytes buffer. It inherits 445 :class:`BufferedIOBase`. 446 447 The argument *initial_bytes* is an optional initial bytearray. 448 449 :class:`BytesIO` provides or overrides these methods in addition to those 450 from :class:`BufferedIOBase` and :class:`IOBase`: 451 452 .. method:: getvalue() 453 454 Return ``bytes`` containing the entire contents of the buffer. 455 456 .. method:: read1() 457 458 In :class:`BytesIO`, this is the same as :meth:`read`. 459 460 .. method:: truncate([size]) 461 462 Truncate the buffer to at most *size* bytes. *size* defaults to the 463 current stream position, as returned by :meth:`tell`. 464 465 466.. class:: BufferedReader(raw[, buffer_size]) 467 468 A buffer for a readable, sequential :class:`RawIOBase` object. It inherits 469 :class:`BufferedIOBase`. 470 471 The constructor creates a :class:`BufferedReader` for the given readable 472 *raw* stream and *buffer_size*. If *buffer_size* is omitted, 473 :data:`DEFAULT_BUFFER_SIZE` is used. 474 475 :class:`BufferedReader` provides or overrides these methods in addition to 476 those from :class:`BufferedIOBase` and :class:`IOBase`: 477 478 .. method:: peek([n]) 479 480 Return 1 (or *n* if specified) bytes from a buffer without advancing the 481 position. Only a single read on the raw stream is done to satisfy the 482 call. The number of bytes returned may be less than requested since at 483 most all the buffer's bytes from the current position to the end are 484 returned. 485 486 .. method:: read([n]) 487 488 Read and return *n* bytes, or if *n* is not given or negative, until EOF 489 or if the read call would block in non-blocking mode. 490 491 .. method:: read1(n) 492 493 Read and return up to *n* bytes with only one call on the raw stream. If 494 at least one byte is buffered, only buffered bytes are returned. 495 Otherwise, one raw stream read call is made. 496 497 498.. class:: BufferedWriter(raw[, buffer_size[, max_buffer_size]]) 499 500 A buffer for a writeable sequential RawIO object. It inherits 501 :class:`BufferedIOBase`. 502 503 The constructor creates a :class:`BufferedWriter` for the given writeable 504 *raw* stream. If the *buffer_size* is not given, it defaults to 505 :data:`DEAFULT_BUFFER_SIZE`. If *max_buffer_size* is omitted, it defaults to 506 twice the buffer size. 507 508 :class:`BufferedWriter` provides or overrides these methods in addition to 509 those from :class:`BufferedIOBase` and :class:`IOBase`: 510 511 .. method:: flush() 512 513 Force bytes held in the buffer into the raw stream. A 514 :exc:`BlockingIOError` should be raised if the raw stream blocks. 515 516 .. method:: write(b) 517 518 Write the bytes or bytearray object, *b*, onto the raw stream and return 519 the number of bytes written. A :exc:`BlockingIOError` is raised when the 520 raw stream blocks. 521 522 523.. class:: BufferedRWPair(reader, writer[, buffer_size[, max_buffer_size]]) 524 525 A combined buffered writer and reader object for a raw stream that can be 526 written to and read from. It has and supports both :meth:`read`, :meth:`write`, 527 and their variants. This is useful for sockets and two-way pipes. 528 It inherits :class:`BufferedIOBase`. 529 530 *reader* and *writer* are :class:`RawIOBase` objects that are readable and 531 writeable respectively. If the *buffer_size* is omitted it defaults to 532 :data:`DEFAULT_BUFFER_SIZE`. The *max_buffer_size* (for the buffered writer) 533 defaults to twice the buffer size. 534 535 :class:`BufferedRWPair` implements all of :class:`BufferedIOBase`\'s methods. 536 537 538.. class:: BufferedRandom(raw[, buffer_size[, max_buffer_size]]) 539 540 A buffered interface to random access streams. It inherits 541 :class:`BufferedReader` and :class:`BufferedWriter`. 542 543 The constructor creates a reader and writer for a seekable raw stream, given 544 in the first argument. If the *buffer_size* is omitted it defaults to 545 :data:`DEFAULT_BUFFER_SIZE`. The *max_buffer_size* (for the buffered writer) 546 defaults to twice the buffer size. 547 548 :class:`BufferedRandom` is capable of anything :class:`BufferedReader` or 549 :class:`BufferedWriter` can do. 550 551 552Text I/O 553-------- 554 555.. class:: TextIOBase 556 557 Base class for text streams. This class provides a character and line based 558 interface to stream I/O. There is no :meth:`readinto` method because 559 Python's character strings are immutable. It inherits :class:`IOBase`. 560 There is no public constructor. 561 562 :class:`TextIOBase` provides or overrides these data attributes and 563 methods in addition to those from :class:`IOBase`: 564 565 .. attribute:: encoding 566 567 The name of the encoding used to decode the stream's bytes into 568 strings, and to encode strings into bytes. 569 570 .. attribute:: newlines 571 572 A string, a tuple of strings, or ``None``, indicating the newlines 573 translated so far. 574 575 .. method:: read(n) 576 577 Read and return at most *n* characters from the stream as a single 578 :class:`str`. If *n* is negative or ``None``, reads to EOF. 579 580 .. method:: readline() 581 582 Read until newline or EOF and return a single ``str``. If the stream is 583 already at EOF, an empty string is returned. 584 585 .. method:: write(s) 586 587 Write the string *s* to the stream and return the number of characters 588 written. 589 590 591.. class:: TextIOWrapper(buffer[, encoding[, errors[, newline[, line_buffering]]]]) 592 593 A buffered text stream over a :class:`BufferedIOBase` raw stream, *buffer*. 594 It inherits :class:`TextIOBase`. 595 596 *encoding* gives the name of the encoding that the stream will be decoded or 597 encoded with. It defaults to :func:`locale.getpreferredencoding`. 598 599 *errors* is an optional string that specifies how encoding and decoding 600 errors are to be handled. Pass ``'strict'`` to raise a :exc:`ValueError` 601 exception if there is an encoding error (the default of ``None`` has the same 602 effect), or pass ``'ignore'`` to ignore errors. (Note that ignoring encoding 603 errors can lead to data loss.) ``'replace'`` causes a replacement marker 604 (such as ``'?'``) to be inserted where there is malformed data. When 605 writing, ``'xmlcharrefreplace'`` (replace with the appropriate XML character 606 reference) or ``'backslashreplace'`` (replace with backslashed escape 607 sequences) can be used. Any other error handling name that has been 608 registered with :func:`codecs.register_error` is also valid. 609 610 *newline* can be ``None``, ``''``, ``'\n'``, ``'\r'``, or ``'\r\n'``. It 611 controls the handling of line endings. If it is ``None``, universal newlines 612 is enabled. With this enabled, on input, the lines endings ``'\n'``, 613 ``'\r'``, or ``'\r\n'`` are translated to ``'\n'`` before being returned to 614 the caller. Conversely, on output, ``'\n'`` is translated to the system 615 default line separator, :data:`os.linesep`. If *newline* is any other of its 616 legal values, that newline becomes the newline when the file is read and it 617 is returned untranslated. On output, ``'\n'`` is converted to the *newline*. 618 619 If *line_buffering* is ``True``, :meth:`flush` is implied when a call to 620 write contains a newline character. 621 622 :class:`TextIOWrapper` provides these data attributes in addition to those of 623 :class:`TextIOBase` and its parents: 624 625 .. attribute:: errors 626 627 The encoding and decoding error setting. 628 629 .. attribute:: line_buffering 630 631 Whether line buffering is enabled. 632 633 634.. class:: StringIO([initial_value[, encoding[, errors[, newline]]]]) 635 636 An in-memory stream for text. It in inherits :class:`TextIOWrapper`. 637 638 Create a new StringIO stream with an inital value, encoding, error handling, 639 and newline setting. See :class:`TextIOWrapper`\'s constructor for more 640 information. 641 642 :class:`StringIO` provides this method in addition to those from 643 :class:`TextIOWrapper` and its parents: 644 645 .. method:: getvalue() 646 647 Return a ``str`` containing the entire contents of the buffer. 648 649 650.. class:: IncrementalNewlineDecoder 651 652 A helper codec that decodes newlines for universal newlines mode. It 653 inherits :class:`codecs.IncrementalDecoder`. 654