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