/Doc/library/io.rst

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