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 | |
Benjamin Peterson | 6b4fa77 | 2010-08-30 13:19:53 +0000 | [diff] [blame] | 14 | .. _io-overview: |
| 15 | |
Antoine Pitrou | b530e14 | 2010-08-30 12:41:00 +0000 | [diff] [blame] | 16 | Overview |
| 17 | -------- |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 18 | |
R David Murray | 9f0c940 | 2012-08-17 20:33:54 -0400 | [diff] [blame] | 19 | .. index:: |
| 20 | single: file object; io module |
| 21 | |
| 22 | The :mod:`io` module provides Python's main facilities for dealing with various |
| 23 | types of I/O. There are three main types of I/O: *text I/O*, *binary I/O* |
| 24 | and *raw I/O*. These are generic categories, and various backing stores can |
| 25 | be used for each of them. A concrete object belonging to any of these |
| 26 | categories is called a :term:`file object`. Other common terms are *stream* |
| 27 | and *file-like object*. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 28 | |
Antoine Pitrou | b530e14 | 2010-08-30 12:41:00 +0000 | [diff] [blame] | 29 | Independently of its category, each concrete stream object will also have |
Benjamin Peterson | 6b4fa77 | 2010-08-30 13:19:53 +0000 | [diff] [blame] | 30 | various capabilities: it can be read-only, write-only, or read-write. It can |
| 31 | also allow arbitrary random access (seeking forwards or backwards to any |
| 32 | location), or only sequential access (for example in the case of a socket or |
| 33 | pipe). |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 34 | |
Antoine Pitrou | b530e14 | 2010-08-30 12:41:00 +0000 | [diff] [blame] | 35 | All streams are careful about the type of data you give to them. For example |
| 36 | giving a :class:`str` object to the ``write()`` method of a binary stream |
| 37 | will raise a ``TypeError``. So will giving a :class:`bytes` object to the |
| 38 | ``write()`` method of a text stream. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 39 | |
Antoine Pitrou | a787b65 | 2011-10-12 19:02:52 +0200 | [diff] [blame] | 40 | .. versionchanged:: 3.3 |
Eli Bendersky | f877a7c | 2012-07-14 21:22:25 +0300 | [diff] [blame] | 41 | Operations that used to raise :exc:`IOError` now raise :exc:`OSError`, since |
| 42 | :exc:`IOError` is now an alias of :exc:`OSError`. |
Antoine Pitrou | a787b65 | 2011-10-12 19:02:52 +0200 | [diff] [blame] | 43 | |
Benjamin Peterson | 6b4fa77 | 2010-08-30 13:19:53 +0000 | [diff] [blame] | 44 | |
Antoine Pitrou | b530e14 | 2010-08-30 12:41:00 +0000 | [diff] [blame] | 45 | Text I/O |
| 46 | ^^^^^^^^ |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 47 | |
Benjamin Peterson | 6b4fa77 | 2010-08-30 13:19:53 +0000 | [diff] [blame] | 48 | Text I/O expects and produces :class:`str` objects. This means that whenever |
| 49 | the backing store is natively made of bytes (such as in the case of a file), |
| 50 | encoding and decoding of data is made transparently as well as optional |
| 51 | translation of platform-specific newline characters. |
Benjamin Peterson | 2c5f828 | 2008-04-13 00:27:46 +0000 | [diff] [blame] | 52 | |
Benjamin Peterson | 6b4fa77 | 2010-08-30 13:19:53 +0000 | [diff] [blame] | 53 | The easiest way to create a text stream is with :meth:`open()`, optionally |
| 54 | specifying an encoding:: |
Antoine Pitrou | b530e14 | 2010-08-30 12:41:00 +0000 | [diff] [blame] | 55 | |
| 56 | f = open("myfile.txt", "r", encoding="utf-8") |
| 57 | |
| 58 | In-memory text streams are also available as :class:`StringIO` objects:: |
| 59 | |
| 60 | f = io.StringIO("some initial text data") |
| 61 | |
Eli Bendersky | f877a7c | 2012-07-14 21:22:25 +0300 | [diff] [blame] | 62 | The text stream API is described in detail in the documentation of |
Benjamin Peterson | 6b4fa77 | 2010-08-30 13:19:53 +0000 | [diff] [blame] | 63 | :class:`TextIOBase`. |
Antoine Pitrou | b530e14 | 2010-08-30 12:41:00 +0000 | [diff] [blame] | 64 | |
Antoine Pitrou | b530e14 | 2010-08-30 12:41:00 +0000 | [diff] [blame] | 65 | |
| 66 | Binary I/O |
| 67 | ^^^^^^^^^^ |
| 68 | |
Benjamin Peterson | 6b4fa77 | 2010-08-30 13:19:53 +0000 | [diff] [blame] | 69 | Binary I/O (also called *buffered I/O*) expects and produces :class:`bytes` |
| 70 | objects. No encoding, decoding, or newline translation is performed. This |
| 71 | category of streams can be used for all kinds of non-text data, and also when |
| 72 | manual control over the handling of text data is desired. |
Antoine Pitrou | b530e14 | 2010-08-30 12:41:00 +0000 | [diff] [blame] | 73 | |
Benjamin Peterson | 6b4fa77 | 2010-08-30 13:19:53 +0000 | [diff] [blame] | 74 | The easiest way to create a binary stream is with :meth:`open()` with ``'b'`` in |
| 75 | the mode string:: |
Antoine Pitrou | b530e14 | 2010-08-30 12:41:00 +0000 | [diff] [blame] | 76 | |
| 77 | f = open("myfile.jpg", "rb") |
| 78 | |
| 79 | In-memory binary streams are also available as :class:`BytesIO` objects:: |
| 80 | |
| 81 | f = io.BytesIO(b"some initial binary data: \x00\x01") |
| 82 | |
Benjamin Peterson | 6b4fa77 | 2010-08-30 13:19:53 +0000 | [diff] [blame] | 83 | The binary stream API is described in detail in the docs of |
| 84 | :class:`BufferedIOBase`. |
Antoine Pitrou | b530e14 | 2010-08-30 12:41:00 +0000 | [diff] [blame] | 85 | |
| 86 | Other library modules may provide additional ways to create text or binary |
Benjamin Peterson | 6b4fa77 | 2010-08-30 13:19:53 +0000 | [diff] [blame] | 87 | streams. See :meth:`socket.socket.makefile` for example. |
| 88 | |
Antoine Pitrou | b530e14 | 2010-08-30 12:41:00 +0000 | [diff] [blame] | 89 | |
| 90 | Raw I/O |
| 91 | ^^^^^^^ |
| 92 | |
| 93 | Raw I/O (also called *unbuffered I/O*) is generally used as a low-level |
| 94 | building-block for binary and text streams; it is rarely useful to directly |
Benjamin Peterson | 6b4fa77 | 2010-08-30 13:19:53 +0000 | [diff] [blame] | 95 | manipulate a raw stream from user code. Nevertheless, you can create a raw |
| 96 | stream by opening a file in binary mode with buffering disabled:: |
Antoine Pitrou | b530e14 | 2010-08-30 12:41:00 +0000 | [diff] [blame] | 97 | |
| 98 | f = open("myfile.jpg", "rb", buffering=0) |
| 99 | |
Benjamin Peterson | 6b4fa77 | 2010-08-30 13:19:53 +0000 | [diff] [blame] | 100 | The raw stream API is described in detail in the docs of :class:`RawIOBase`. |
Benjamin Peterson | cc12e1b | 2010-02-19 00:58:13 +0000 | [diff] [blame] | 101 | |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 102 | |
Antoine Pitrou | b530e14 | 2010-08-30 12:41:00 +0000 | [diff] [blame] | 103 | High-level Module Interface |
| 104 | --------------------------- |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 105 | |
| 106 | .. data:: DEFAULT_BUFFER_SIZE |
| 107 | |
| 108 | An int containing the default buffer size used by the module's buffered I/O |
Benjamin Peterson | 6b4fa77 | 2010-08-30 13:19:53 +0000 | [diff] [blame] | 109 | classes. :func:`open` uses the file's blksize (as obtained by |
Benjamin Peterson | 2c5f828 | 2008-04-13 00:27:46 +0000 | [diff] [blame] | 110 | :func:`os.stat`) if possible. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 111 | |
Benjamin Peterson | 6b4fa77 | 2010-08-30 13:19:53 +0000 | [diff] [blame] | 112 | |
Andrew Svetlov | a60de4f | 2013-02-17 16:55:58 +0200 | [diff] [blame] | 113 | .. function:: open(file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True, opener=None) |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 114 | |
Benjamin Peterson | 6b4fa77 | 2010-08-30 13:19:53 +0000 | [diff] [blame] | 115 | This is an alias for the builtin :func:`open` function. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 116 | |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 117 | |
| 118 | .. exception:: BlockingIOError |
| 119 | |
Antoine Pitrou | f55011f | 2011-10-12 18:57:23 +0200 | [diff] [blame] | 120 | This is a compatibility alias for the builtin :exc:`BlockingIOError` |
| 121 | exception. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 122 | |
| 123 | |
| 124 | .. exception:: UnsupportedOperation |
| 125 | |
Antoine Pitrou | a787b65 | 2011-10-12 19:02:52 +0200 | [diff] [blame] | 126 | An exception inheriting :exc:`OSError` and :exc:`ValueError` that is raised |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 127 | when an unsupported operation is called on a stream. |
| 128 | |
| 129 | |
Antoine Pitrou | b530e14 | 2010-08-30 12:41:00 +0000 | [diff] [blame] | 130 | In-memory streams |
| 131 | ^^^^^^^^^^^^^^^^^ |
| 132 | |
| 133 | It is also possible to use a :class:`str` or :class:`bytes`-like object as a |
Benjamin Peterson | 6b4fa77 | 2010-08-30 13:19:53 +0000 | [diff] [blame] | 134 | file for both reading and writing. For strings :class:`StringIO` can be used |
| 135 | like a file opened in text mode. :class:`BytesIO` can be used like a file |
| 136 | opened in binary mode. Both provide full read-write capabilities with random |
| 137 | access. |
Antoine Pitrou | b530e14 | 2010-08-30 12:41:00 +0000 | [diff] [blame] | 138 | |
| 139 | |
| 140 | .. seealso:: |
Benjamin Peterson | 6b4fa77 | 2010-08-30 13:19:53 +0000 | [diff] [blame] | 141 | |
Antoine Pitrou | b530e14 | 2010-08-30 12:41:00 +0000 | [diff] [blame] | 142 | :mod:`sys` |
| 143 | contains the standard IO streams: :data:`sys.stdin`, :data:`sys.stdout`, |
| 144 | and :data:`sys.stderr`. |
| 145 | |
| 146 | |
| 147 | Class hierarchy |
| 148 | --------------- |
| 149 | |
Benjamin Peterson | 6b4fa77 | 2010-08-30 13:19:53 +0000 | [diff] [blame] | 150 | The implementation of I/O streams is organized as a hierarchy of classes. First |
| 151 | :term:`abstract base classes <abstract base class>` (ABCs), which are used to |
| 152 | specify the various categories of streams, then concrete classes providing the |
| 153 | standard stream implementations. |
Antoine Pitrou | b530e14 | 2010-08-30 12:41:00 +0000 | [diff] [blame] | 154 | |
| 155 | .. note:: |
Benjamin Peterson | 6b4fa77 | 2010-08-30 13:19:53 +0000 | [diff] [blame] | 156 | |
| 157 | The abstract base classes also provide default implementations of some |
| 158 | methods in order to help implementation of concrete stream classes. For |
| 159 | example, :class:`BufferedIOBase` provides unoptimized implementations of |
| 160 | ``readinto()`` and ``readline()``. |
Antoine Pitrou | b530e14 | 2010-08-30 12:41:00 +0000 | [diff] [blame] | 161 | |
| 162 | At the top of the I/O hierarchy is the abstract base class :class:`IOBase`. It |
| 163 | defines the basic interface to a stream. Note, however, that there is no |
| 164 | separation between reading and writing to streams; implementations are allowed |
Benjamin Peterson | 6b4fa77 | 2010-08-30 13:19:53 +0000 | [diff] [blame] | 165 | to raise :exc:`UnsupportedOperation` if they do not support a given operation. |
Antoine Pitrou | b530e14 | 2010-08-30 12:41:00 +0000 | [diff] [blame] | 166 | |
Benjamin Peterson | 6b4fa77 | 2010-08-30 13:19:53 +0000 | [diff] [blame] | 167 | The :class:`RawIOBase` ABC extends :class:`IOBase`. It deals with the reading |
| 168 | and writing of bytes to a stream. :class:`FileIO` subclasses :class:`RawIOBase` |
| 169 | to provide an interface to files in the machine's file system. |
Antoine Pitrou | b530e14 | 2010-08-30 12:41:00 +0000 | [diff] [blame] | 170 | |
| 171 | The :class:`BufferedIOBase` ABC deals with buffering on a raw byte stream |
| 172 | (:class:`RawIOBase`). Its subclasses, :class:`BufferedWriter`, |
| 173 | :class:`BufferedReader`, and :class:`BufferedRWPair` buffer streams that are |
Benjamin Peterson | 6b4fa77 | 2010-08-30 13:19:53 +0000 | [diff] [blame] | 174 | readable, writable, and both readable and writable. :class:`BufferedRandom` |
| 175 | provides a buffered interface to random access streams. Another |
Georg Brandl | 682d7e0 | 2010-10-06 10:26:05 +0000 | [diff] [blame] | 176 | :class:`BufferedIOBase` subclass, :class:`BytesIO`, is a stream of in-memory |
Benjamin Peterson | 6b4fa77 | 2010-08-30 13:19:53 +0000 | [diff] [blame] | 177 | bytes. |
Antoine Pitrou | b530e14 | 2010-08-30 12:41:00 +0000 | [diff] [blame] | 178 | |
Benjamin Peterson | 6b4fa77 | 2010-08-30 13:19:53 +0000 | [diff] [blame] | 179 | The :class:`TextIOBase` ABC, another subclass of :class:`IOBase`, deals with |
| 180 | streams whose bytes represent text, and handles encoding and decoding to and |
| 181 | from strings. :class:`TextIOWrapper`, which extends it, is a buffered text |
| 182 | interface to a buffered raw stream (:class:`BufferedIOBase`). Finally, |
| 183 | :class:`StringIO` is an in-memory stream for text. |
Antoine Pitrou | b530e14 | 2010-08-30 12:41:00 +0000 | [diff] [blame] | 184 | |
| 185 | Argument names are not part of the specification, and only the arguments of |
Benjamin Peterson | 6b4fa77 | 2010-08-30 13:19:53 +0000 | [diff] [blame] | 186 | :func:`open` are intended to be used as keyword arguments. |
Antoine Pitrou | b530e14 | 2010-08-30 12:41:00 +0000 | [diff] [blame] | 187 | |
Andrew Svetlov | ed636a8 | 2012-12-06 12:20:56 +0200 | [diff] [blame] | 188 | The following table summarizes the ABCs provided by the :mod:`io` module: |
| 189 | |
| 190 | ========================= ================== ======================== ================================================== |
| 191 | ABC Inherits Stub Methods Mixin Methods and Properties |
| 192 | ========================= ================== ======================== ================================================== |
| 193 | :class:`IOBase` ``fileno``, ``seek``, ``close``, ``closed``, ``__enter__``, |
| 194 | and ``truncate`` ``__exit__``, ``flush``, ``isatty``, ``__iter__``, |
| 195 | ``__next__``, ``readable``, ``readline``, |
| 196 | ``readlines``, ``seekable``, ``tell``, |
| 197 | ``writable``, and ``writelines`` |
| 198 | :class:`RawIOBase` :class:`IOBase` ``readinto`` and Inherited :class:`IOBase` methods, ``read``, |
| 199 | ``write`` and ``readall`` |
| 200 | :class:`BufferedIOBase` :class:`IOBase` ``detach``, ``read``, Inherited :class:`IOBase` methods, ``readinto`` |
| 201 | ``read1``, and ``write`` |
| 202 | :class:`TextIOBase` :class:`IOBase` ``detach``, ``read``, Inherited :class:`IOBase` methods, ``encoding``, |
| 203 | ``readline``, and ``errors``, and ``newlines`` |
| 204 | ``write`` |
| 205 | ========================= ================== ======================== ================================================== |
| 206 | |
Antoine Pitrou | b530e14 | 2010-08-30 12:41:00 +0000 | [diff] [blame] | 207 | |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 208 | I/O Base Classes |
Antoine Pitrou | b530e14 | 2010-08-30 12:41:00 +0000 | [diff] [blame] | 209 | ^^^^^^^^^^^^^^^^ |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 210 | |
| 211 | .. class:: IOBase |
| 212 | |
| 213 | The abstract base class for all I/O classes, acting on streams of bytes. |
| 214 | There is no public constructor. |
| 215 | |
Mark Summerfield | e6d5f30 | 2008-04-21 10:29:45 +0000 | [diff] [blame] | 216 | This class provides empty abstract implementations for many methods |
| 217 | that derived classes can override selectively; the default |
| 218 | implementations represent a file that cannot be read, written or |
| 219 | seeked. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 220 | |
| 221 | Even though :class:`IOBase` does not declare :meth:`read`, :meth:`readinto`, |
Benjamin Peterson | 2c5f828 | 2008-04-13 00:27:46 +0000 | [diff] [blame] | 222 | or :meth:`write` because their signatures will vary, implementations and |
| 223 | clients should consider those methods part of the interface. Also, |
Antoine Pitrou | a787b65 | 2011-10-12 19:02:52 +0200 | [diff] [blame] | 224 | implementations may raise a :exc:`ValueError` (or :exc:`UnsupportedOperation`) |
| 225 | when operations they do not support are called. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 226 | |
| 227 | The basic type used for binary data read from or written to a file is |
| 228 | :class:`bytes`. :class:`bytearray`\s are accepted too, and in some cases |
Mark Summerfield | e6d5f30 | 2008-04-21 10:29:45 +0000 | [diff] [blame] | 229 | (such as :class:`readinto`) required. Text I/O classes work with |
| 230 | :class:`str` data. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 231 | |
Benjamin Peterson | 2c5f828 | 2008-04-13 00:27:46 +0000 | [diff] [blame] | 232 | Note that calling any method (even inquiries) on a closed stream is |
Antoine Pitrou | a787b65 | 2011-10-12 19:02:52 +0200 | [diff] [blame] | 233 | undefined. Implementations may raise :exc:`ValueError` in this case. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 234 | |
Éric Araujo | 3f7c0e4 | 2012-12-08 22:53:43 -0500 | [diff] [blame] | 235 | :class:`IOBase` (and its subclasses) supports the iterator protocol, meaning |
Eli Bendersky | f877a7c | 2012-07-14 21:22:25 +0300 | [diff] [blame] | 236 | that an :class:`IOBase` object can be iterated over yielding the lines in a |
| 237 | stream. Lines are defined slightly differently depending on whether the |
| 238 | stream is a binary stream (yielding bytes), or a text stream (yielding |
| 239 | character strings). See :meth:`~IOBase.readline` below. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 240 | |
Eli Bendersky | f877a7c | 2012-07-14 21:22:25 +0300 | [diff] [blame] | 241 | :class:`IOBase` is also a context manager and therefore supports the |
Mark Summerfield | e6d5f30 | 2008-04-21 10:29:45 +0000 | [diff] [blame] | 242 | :keyword:`with` statement. In this example, *file* is closed after the |
| 243 | :keyword:`with` statement's suite is finished---even if an exception occurs:: |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 244 | |
Mark Summerfield | e6d5f30 | 2008-04-21 10:29:45 +0000 | [diff] [blame] | 245 | with open('spam.txt', 'w') as file: |
| 246 | file.write('Spam and eggs!') |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 247 | |
Mark Summerfield | e6d5f30 | 2008-04-21 10:29:45 +0000 | [diff] [blame] | 248 | :class:`IOBase` provides these data attributes and methods: |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 249 | |
| 250 | .. method:: close() |
| 251 | |
Christian Heimes | ecc42a2 | 2008-11-05 19:30:32 +0000 | [diff] [blame] | 252 | 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] | 253 | already closed. Once the file is closed, any operation on the file |
Georg Brandl | 8569e58 | 2010-05-19 20:57:08 +0000 | [diff] [blame] | 254 | (e.g. reading or writing) will raise a :exc:`ValueError`. |
Antoine Pitrou | f9fc08f | 2010-04-28 19:59:32 +0000 | [diff] [blame] | 255 | |
| 256 | As a convenience, it is allowed to call this method more than once; |
| 257 | only the first call, however, will have an effect. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 258 | |
| 259 | .. attribute:: closed |
| 260 | |
Eli Bendersky | f877a7c | 2012-07-14 21:22:25 +0300 | [diff] [blame] | 261 | ``True`` if the stream is closed. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 262 | |
| 263 | .. method:: fileno() |
| 264 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 265 | Return the underlying file descriptor (an integer) of the stream if it |
Antoine Pitrou | a787b65 | 2011-10-12 19:02:52 +0200 | [diff] [blame] | 266 | exists. An :exc:`OSError` is raised if the IO object does not use a file |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 267 | descriptor. |
| 268 | |
| 269 | .. method:: flush() |
| 270 | |
Benjamin Peterson | b85a584 | 2008-04-13 21:39:58 +0000 | [diff] [blame] | 271 | Flush the write buffers of the stream if applicable. This does nothing |
| 272 | for read-only and non-blocking streams. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 273 | |
| 274 | .. method:: isatty() |
| 275 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 276 | Return ``True`` if the stream is interactive (i.e., connected to |
Mark Summerfield | e6d5f30 | 2008-04-21 10:29:45 +0000 | [diff] [blame] | 277 | a terminal/tty device). |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 278 | |
| 279 | .. method:: readable() |
| 280 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 281 | Return ``True`` if the stream can be read from. If False, :meth:`read` |
Antoine Pitrou | a787b65 | 2011-10-12 19:02:52 +0200 | [diff] [blame] | 282 | will raise :exc:`OSError`. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 283 | |
Georg Brandl | 3dd3388 | 2009-06-01 17:35:27 +0000 | [diff] [blame] | 284 | .. method:: readline(limit=-1) |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 285 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 286 | Read and return one line from the stream. If *limit* is specified, at |
| 287 | most *limit* bytes will be read. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 288 | |
Benjamin Peterson | 2c5f828 | 2008-04-13 00:27:46 +0000 | [diff] [blame] | 289 | The line terminator is always ``b'\n'`` for binary files; for text files, |
Benjamin Peterson | 6b4fa77 | 2010-08-30 13:19:53 +0000 | [diff] [blame] | 290 | 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] | 291 | terminator(s) recognized. |
| 292 | |
Georg Brandl | 3dd3388 | 2009-06-01 17:35:27 +0000 | [diff] [blame] | 293 | .. method:: readlines(hint=-1) |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 294 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 295 | Read and return a list of lines from the stream. *hint* can be specified |
| 296 | to control the number of lines read: no more lines will be read if the |
| 297 | total size (in bytes/characters) of all lines so far exceeds *hint*. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 298 | |
Georg Brandl | 3dd3388 | 2009-06-01 17:35:27 +0000 | [diff] [blame] | 299 | .. method:: seek(offset, whence=SEEK_SET) |
Benjamin Peterson | 2c5f828 | 2008-04-13 00:27:46 +0000 | [diff] [blame] | 300 | |
Mark Summerfield | e6d5f30 | 2008-04-21 10:29:45 +0000 | [diff] [blame] | 301 | Change the stream position to the given byte *offset*. *offset* is |
Benjamin Peterson | 2c5f828 | 2008-04-13 00:27:46 +0000 | [diff] [blame] | 302 | interpreted relative to the position indicated by *whence*. Values for |
| 303 | *whence* are: |
| 304 | |
Benjamin Peterson | 0e4caf4 | 2009-04-01 21:22:20 +0000 | [diff] [blame] | 305 | * :data:`SEEK_SET` or ``0`` -- start of the stream (the default); |
| 306 | *offset* should be zero or positive |
| 307 | * :data:`SEEK_CUR` or ``1`` -- current stream position; *offset* may |
| 308 | be negative |
| 309 | * :data:`SEEK_END` or ``2`` -- end of the stream; *offset* is usually |
| 310 | negative |
Benjamin Peterson | 2c5f828 | 2008-04-13 00:27:46 +0000 | [diff] [blame] | 311 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 312 | Return the new absolute position. |
Benjamin Peterson | 2c5f828 | 2008-04-13 00:27:46 +0000 | [diff] [blame] | 313 | |
Raymond Hettinger | 35a8836 | 2009-04-09 00:08:24 +0000 | [diff] [blame] | 314 | .. versionadded:: 3.1 |
Georg Brandl | 67b21b7 | 2010-08-17 15:07:14 +0000 | [diff] [blame] | 315 | The ``SEEK_*`` constants. |
Benjamin Peterson | 0e4caf4 | 2009-04-01 21:22:20 +0000 | [diff] [blame] | 316 | |
Jesus Cea | 9436361 | 2012-06-22 18:32:07 +0200 | [diff] [blame] | 317 | .. versionadded:: 3.3 |
| 318 | Some operating systems could support additional values, like |
| 319 | :data:`os.SEEK_HOLE` or :data:`os.SEEK_DATA`. The valid values |
| 320 | for a file could depend on it being open in text or binary mode. |
| 321 | |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 322 | .. method:: seekable() |
| 323 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 324 | Return ``True`` if the stream supports random access. If ``False``, |
Antoine Pitrou | a787b65 | 2011-10-12 19:02:52 +0200 | [diff] [blame] | 325 | :meth:`seek`, :meth:`tell` and :meth:`truncate` will raise :exc:`OSError`. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 326 | |
| 327 | .. method:: tell() |
| 328 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 329 | Return the current stream position. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 330 | |
Georg Brandl | 3dd3388 | 2009-06-01 17:35:27 +0000 | [diff] [blame] | 331 | .. method:: truncate(size=None) |
Benjamin Peterson | 2c5f828 | 2008-04-13 00:27:46 +0000 | [diff] [blame] | 332 | |
Antoine Pitrou | 2016dc9 | 2010-05-29 12:08:25 +0000 | [diff] [blame] | 333 | Resize the stream to the given *size* in bytes (or the current position |
| 334 | if *size* is not specified). The current stream position isn't changed. |
| 335 | This resizing can extend or reduce the current file size. In case of |
| 336 | extension, the contents of the new file area depend on the platform |
| 337 | (on most systems, additional bytes are zero-filled, on Windows they're |
| 338 | undetermined). The new file size is returned. |
Benjamin Peterson | 2c5f828 | 2008-04-13 00:27:46 +0000 | [diff] [blame] | 339 | |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 340 | .. method:: writable() |
| 341 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 342 | Return ``True`` if the stream supports writing. If ``False``, |
Antoine Pitrou | a787b65 | 2011-10-12 19:02:52 +0200 | [diff] [blame] | 343 | :meth:`write` and :meth:`truncate` will raise :exc:`OSError`. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 344 | |
| 345 | .. method:: writelines(lines) |
| 346 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 347 | Write a list of lines to the stream. Line separators are not added, so it |
| 348 | is usual for each of the lines provided to have a line separator at the |
| 349 | end. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 350 | |
| 351 | |
| 352 | .. class:: RawIOBase |
| 353 | |
| 354 | Base class for raw binary I/O. It inherits :class:`IOBase`. There is no |
| 355 | public constructor. |
| 356 | |
Antoine Pitrou | 497a767 | 2009-09-17 17:18:01 +0000 | [diff] [blame] | 357 | Raw binary I/O typically provides low-level access to an underlying OS |
| 358 | device or API, and does not try to encapsulate it in high-level primitives |
| 359 | (this is left to Buffered I/O and Text I/O, described later in this page). |
| 360 | |
Mark Summerfield | e6d5f30 | 2008-04-21 10:29:45 +0000 | [diff] [blame] | 361 | In addition to the attributes and methods from :class:`IOBase`, |
Eli Bendersky | f877a7c | 2012-07-14 21:22:25 +0300 | [diff] [blame] | 362 | :class:`RawIOBase` provides the following methods: |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 363 | |
Georg Brandl | 3dd3388 | 2009-06-01 17:35:27 +0000 | [diff] [blame] | 364 | .. method:: read(n=-1) |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 365 | |
Antoine Pitrou | 78ddbe6 | 2009-10-01 16:24:45 +0000 | [diff] [blame] | 366 | Read up to *n* bytes from the object and return them. As a convenience, |
| 367 | if *n* is unspecified or -1, :meth:`readall` is called. Otherwise, |
| 368 | only one system call is ever made. Fewer than *n* bytes may be |
| 369 | returned if the operating system call returns fewer than *n* bytes. |
| 370 | |
| 371 | If 0 bytes are returned, and *n* was not 0, this indicates end of file. |
| 372 | If the object is in non-blocking mode and no bytes are available, |
| 373 | ``None`` is returned. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 374 | |
Benjamin Peterson | b47aace | 2008-04-09 21:38:38 +0000 | [diff] [blame] | 375 | .. method:: readall() |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 376 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 377 | Read and return all the bytes from the stream until EOF, using multiple |
| 378 | calls to the stream if necessary. |
Benjamin Peterson | 2c5f828 | 2008-04-13 00:27:46 +0000 | [diff] [blame] | 379 | |
| 380 | .. method:: readinto(b) |
| 381 | |
Eli Bendersky | f877a7c | 2012-07-14 21:22:25 +0300 | [diff] [blame] | 382 | Read up to ``len(b)`` bytes into :class:`bytearray` *b* and return the |
| 383 | number of bytes read. If the object is in non-blocking mode and no |
Daniel Stutzbach | d01df46 | 2010-11-30 17:49:53 +0000 | [diff] [blame] | 384 | bytes are available, ``None`` is returned. |
Benjamin Peterson | 2c5f828 | 2008-04-13 00:27:46 +0000 | [diff] [blame] | 385 | |
| 386 | .. method:: write(b) |
| 387 | |
Eli Bendersky | f877a7c | 2012-07-14 21:22:25 +0300 | [diff] [blame] | 388 | Write the given :class:`bytes` or :class:`bytearray` object, *b*, to the |
| 389 | underlying raw stream and return the number of bytes written. This can |
| 390 | be less than ``len(b)``, depending on specifics of the underlying raw |
| 391 | stream, and especially if it is in non-blocking mode. ``None`` is |
| 392 | returned if the raw stream is set not to block and no single byte could |
| 393 | be readily written to it. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 394 | |
| 395 | |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 396 | .. class:: BufferedIOBase |
| 397 | |
Antoine Pitrou | 497a767 | 2009-09-17 17:18:01 +0000 | [diff] [blame] | 398 | Base class for binary streams that support some kind of buffering. |
| 399 | It inherits :class:`IOBase`. There is no public constructor. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 400 | |
Antoine Pitrou | 497a767 | 2009-09-17 17:18:01 +0000 | [diff] [blame] | 401 | The main difference with :class:`RawIOBase` is that methods :meth:`read`, |
| 402 | :meth:`readinto` and :meth:`write` will try (respectively) to read as much |
| 403 | input as requested or to consume all given output, at the expense of |
| 404 | making perhaps more than one system call. |
| 405 | |
| 406 | In addition, those methods can raise :exc:`BlockingIOError` if the |
| 407 | underlying raw stream is in non-blocking mode and cannot take or give |
| 408 | enough data; unlike their :class:`RawIOBase` counterparts, they will |
| 409 | never return ``None``. |
| 410 | |
| 411 | Besides, the :meth:`read` method does not have a default |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 412 | implementation that defers to :meth:`readinto`. |
| 413 | |
Antoine Pitrou | 497a767 | 2009-09-17 17:18:01 +0000 | [diff] [blame] | 414 | A typical :class:`BufferedIOBase` implementation should not inherit from a |
| 415 | :class:`RawIOBase` implementation, but wrap one, like |
| 416 | :class:`BufferedWriter` and :class:`BufferedReader` do. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 417 | |
Senthil Kumaran | a6bac95 | 2011-07-04 11:28:30 -0700 | [diff] [blame] | 418 | :class:`BufferedIOBase` provides or overrides these methods and attribute in |
| 419 | addition to those from :class:`IOBase`: |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 420 | |
Benjamin Peterson | c609b6b | 2009-06-28 17:32:20 +0000 | [diff] [blame] | 421 | .. attribute:: raw |
| 422 | |
| 423 | The underlying raw stream (a :class:`RawIOBase` instance) that |
| 424 | :class:`BufferedIOBase` deals with. This is not part of the |
| 425 | :class:`BufferedIOBase` API and may not exist on some implementations. |
| 426 | |
Benjamin Peterson | d2e0c79 | 2009-05-01 20:40:59 +0000 | [diff] [blame] | 427 | .. method:: detach() |
| 428 | |
| 429 | Separate the underlying raw stream from the buffer and return it. |
| 430 | |
| 431 | After the raw stream has been detached, the buffer is in an unusable |
| 432 | state. |
| 433 | |
| 434 | Some buffers, like :class:`BytesIO`, do not have the concept of a single |
| 435 | raw stream to return from this method. They raise |
| 436 | :exc:`UnsupportedOperation`. |
| 437 | |
Benjamin Peterson | edc3647 | 2009-05-01 20:48:14 +0000 | [diff] [blame] | 438 | .. versionadded:: 3.1 |
| 439 | |
Georg Brandl | 3dd3388 | 2009-06-01 17:35:27 +0000 | [diff] [blame] | 440 | .. method:: read(n=-1) |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 441 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 442 | Read and return up to *n* bytes. If the argument is omitted, ``None``, or |
Eli Bendersky | f877a7c | 2012-07-14 21:22:25 +0300 | [diff] [blame] | 443 | negative, data is read and returned until EOF is reached. An empty |
| 444 | :class:`bytes` object is returned if the stream is already at EOF. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 445 | |
| 446 | If the argument is positive, and the underlying raw stream is not |
| 447 | interactive, multiple raw reads may be issued to satisfy the byte count |
| 448 | (unless EOF is reached first). But for interactive raw streams, at most |
| 449 | one raw read will be issued, and a short result does not imply that EOF is |
| 450 | imminent. |
| 451 | |
Antoine Pitrou | 497a767 | 2009-09-17 17:18:01 +0000 | [diff] [blame] | 452 | A :exc:`BlockingIOError` is raised if the underlying raw stream is in |
| 453 | non blocking-mode, and has no data available at the moment. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 454 | |
Georg Brandl | 3dd3388 | 2009-06-01 17:35:27 +0000 | [diff] [blame] | 455 | .. method:: read1(n=-1) |
Benjamin Peterson | 4fa88fa | 2009-03-04 00:14:51 +0000 | [diff] [blame] | 456 | |
| 457 | Read and return up to *n* bytes, with at most one call to the underlying |
Antoine Pitrou | 497a767 | 2009-09-17 17:18:01 +0000 | [diff] [blame] | 458 | raw stream's :meth:`~RawIOBase.read` method. This can be useful if you |
| 459 | are implementing your own buffering on top of a :class:`BufferedIOBase` |
| 460 | object. |
Benjamin Peterson | 4fa88fa | 2009-03-04 00:14:51 +0000 | [diff] [blame] | 461 | |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 462 | .. method:: readinto(b) |
| 463 | |
Eli Bendersky | f877a7c | 2012-07-14 21:22:25 +0300 | [diff] [blame] | 464 | Read up to ``len(b)`` bytes into bytearray *b* and return the number of |
| 465 | bytes read. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 466 | |
| 467 | Like :meth:`read`, multiple reads may be issued to the underlying raw |
Eli Bendersky | f877a7c | 2012-07-14 21:22:25 +0300 | [diff] [blame] | 468 | stream, unless the latter is interactive. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 469 | |
Antoine Pitrou | 497a767 | 2009-09-17 17:18:01 +0000 | [diff] [blame] | 470 | A :exc:`BlockingIOError` is raised if the underlying raw stream is in |
| 471 | non blocking-mode, and has no data available at the moment. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 472 | |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 473 | .. method:: write(b) |
| 474 | |
Eli Bendersky | f877a7c | 2012-07-14 21:22:25 +0300 | [diff] [blame] | 475 | Write the given :class:`bytes` or :class:`bytearray` object, *b* and |
| 476 | return the number of bytes written (never less than ``len(b)``, since if |
| 477 | the write fails an :exc:`OSError` will be raised). Depending on the |
| 478 | actual implementation, these bytes may be readily written to the |
| 479 | underlying stream, or held in a buffer for performance and latency |
| 480 | reasons. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 481 | |
Antoine Pitrou | 497a767 | 2009-09-17 17:18:01 +0000 | [diff] [blame] | 482 | When in non-blocking mode, a :exc:`BlockingIOError` is raised if the |
| 483 | data needed to be written to the raw stream but it couldn't accept |
| 484 | all the data without blocking. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 485 | |
| 486 | |
Benjamin Peterson | aa06900 | 2009-01-23 03:26:36 +0000 | [diff] [blame] | 487 | Raw File I/O |
Antoine Pitrou | b530e14 | 2010-08-30 12:41:00 +0000 | [diff] [blame] | 488 | ^^^^^^^^^^^^ |
Benjamin Peterson | aa06900 | 2009-01-23 03:26:36 +0000 | [diff] [blame] | 489 | |
Ross Lagerwall | 59142db | 2011-10-31 20:34:46 +0200 | [diff] [blame] | 490 | .. class:: FileIO(name, mode='r', closefd=True, opener=None) |
Benjamin Peterson | aa06900 | 2009-01-23 03:26:36 +0000 | [diff] [blame] | 491 | |
Antoine Pitrou | 497a767 | 2009-09-17 17:18:01 +0000 | [diff] [blame] | 492 | :class:`FileIO` represents an OS-level file containing bytes data. |
| 493 | It implements the :class:`RawIOBase` interface (and therefore the |
| 494 | :class:`IOBase` interface, too). |
| 495 | |
| 496 | The *name* can be one of two things: |
| 497 | |
Eli Bendersky | f877a7c | 2012-07-14 21:22:25 +0300 | [diff] [blame] | 498 | * a character string or :class:`bytes` object representing the path to the |
| 499 | file which will be opened; |
Antoine Pitrou | 497a767 | 2009-09-17 17:18:01 +0000 | [diff] [blame] | 500 | * an integer representing the number of an existing OS-level file descriptor |
| 501 | to which the resulting :class:`FileIO` object will give access. |
Benjamin Peterson | aa06900 | 2009-01-23 03:26:36 +0000 | [diff] [blame] | 502 | |
Charles-François Natali | dc3044c | 2012-01-09 22:40:02 +0100 | [diff] [blame] | 503 | The *mode* can be ``'r'``, ``'w'``, ``'x'`` or ``'a'`` for reading |
Charles-François Natali | d612de1 | 2012-01-14 11:51:00 +0100 | [diff] [blame] | 504 | (default), writing, exclusive creation or appending. The file will be |
| 505 | created if it doesn't exist when opened for writing or appending; it will be |
| 506 | truncated when opened for writing. :exc:`FileExistsError` will be raised if |
| 507 | it already exists when opened for creating. Opening a file for creating |
| 508 | implies writing, so this mode behaves in a similar way to ``'w'``. Add a |
| 509 | ``'+'`` to the mode to allow simultaneous reading and writing. |
Benjamin Peterson | aa06900 | 2009-01-23 03:26:36 +0000 | [diff] [blame] | 510 | |
Antoine Pitrou | 497a767 | 2009-09-17 17:18:01 +0000 | [diff] [blame] | 511 | The :meth:`read` (when called with a positive argument), :meth:`readinto` |
| 512 | and :meth:`write` methods on this class will only make one system call. |
| 513 | |
Ross Lagerwall | 59142db | 2011-10-31 20:34:46 +0200 | [diff] [blame] | 514 | A custom opener can be used by passing a callable as *opener*. The underlying |
| 515 | file descriptor for the file object is then obtained by calling *opener* with |
| 516 | (*name*, *flags*). *opener* must return an open file descriptor (passing |
| 517 | :mod:`os.open` as *opener* results in functionality similar to passing |
| 518 | ``None``). |
| 519 | |
Éric Araujo | 8f423c9 | 2012-11-03 17:06:52 -0400 | [diff] [blame] | 520 | See the :func:`open` built-in function for examples on using the *opener* |
| 521 | parameter. |
| 522 | |
Ross Lagerwall | 59142db | 2011-10-31 20:34:46 +0200 | [diff] [blame] | 523 | .. versionchanged:: 3.3 |
| 524 | The *opener* parameter was added. |
Charles-François Natali | dc3044c | 2012-01-09 22:40:02 +0100 | [diff] [blame] | 525 | The ``'x'`` mode was added. |
Ross Lagerwall | 59142db | 2011-10-31 20:34:46 +0200 | [diff] [blame] | 526 | |
Benjamin Peterson | aa06900 | 2009-01-23 03:26:36 +0000 | [diff] [blame] | 527 | In addition to the attributes and methods from :class:`IOBase` and |
| 528 | :class:`RawIOBase`, :class:`FileIO` provides the following data |
Eli Bendersky | f877a7c | 2012-07-14 21:22:25 +0300 | [diff] [blame] | 529 | attributes: |
Benjamin Peterson | aa06900 | 2009-01-23 03:26:36 +0000 | [diff] [blame] | 530 | |
| 531 | .. attribute:: mode |
| 532 | |
| 533 | The mode as given in the constructor. |
| 534 | |
| 535 | .. attribute:: name |
| 536 | |
| 537 | The file name. This is the file descriptor of the file when no name is |
| 538 | given in the constructor. |
| 539 | |
Benjamin Peterson | aa06900 | 2009-01-23 03:26:36 +0000 | [diff] [blame] | 540 | |
| 541 | Buffered Streams |
Antoine Pitrou | b530e14 | 2010-08-30 12:41:00 +0000 | [diff] [blame] | 542 | ^^^^^^^^^^^^^^^^ |
Benjamin Peterson | aa06900 | 2009-01-23 03:26:36 +0000 | [diff] [blame] | 543 | |
Antoine Pitrou | bed81c8 | 2010-12-03 19:14:17 +0000 | [diff] [blame] | 544 | Buffered I/O streams provide a higher-level interface to an I/O device |
| 545 | than raw I/O does. |
Antoine Pitrou | 497a767 | 2009-09-17 17:18:01 +0000 | [diff] [blame] | 546 | |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 547 | .. class:: BytesIO([initial_bytes]) |
| 548 | |
| 549 | A stream implementation using an in-memory bytes buffer. It inherits |
| 550 | :class:`BufferedIOBase`. |
| 551 | |
Antoine Pitrou | b530e14 | 2010-08-30 12:41:00 +0000 | [diff] [blame] | 552 | The argument *initial_bytes* contains optional initial :class:`bytes` data. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 553 | |
| 554 | :class:`BytesIO` provides or overrides these methods in addition to those |
| 555 | from :class:`BufferedIOBase` and :class:`IOBase`: |
| 556 | |
Antoine Pitrou | 972ee13 | 2010-09-06 18:48:21 +0000 | [diff] [blame] | 557 | .. method:: getbuffer() |
| 558 | |
| 559 | Return a readable and writable view over the contents of the buffer |
| 560 | without copying them. Also, mutating the view will transparently |
| 561 | update the contents of the buffer:: |
| 562 | |
| 563 | >>> b = io.BytesIO(b"abcdef") |
| 564 | >>> view = b.getbuffer() |
| 565 | >>> view[2:4] = b"56" |
| 566 | >>> b.getvalue() |
| 567 | b'ab56ef' |
| 568 | |
| 569 | .. note:: |
| 570 | As long as the view exists, the :class:`BytesIO` object cannot be |
| 571 | resized. |
| 572 | |
| 573 | .. versionadded:: 3.2 |
| 574 | |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 575 | .. method:: getvalue() |
| 576 | |
Eli Bendersky | f877a7c | 2012-07-14 21:22:25 +0300 | [diff] [blame] | 577 | Return :class:`bytes` containing the entire contents of the buffer. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 578 | |
| 579 | .. method:: read1() |
| 580 | |
Benjamin Peterson | 9efcc4b | 2008-04-14 21:30:21 +0000 | [diff] [blame] | 581 | In :class:`BytesIO`, this is the same as :meth:`read`. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 582 | |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 583 | |
Georg Brandl | 3dd3388 | 2009-06-01 17:35:27 +0000 | [diff] [blame] | 584 | .. class:: BufferedReader(raw, buffer_size=DEFAULT_BUFFER_SIZE) |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 585 | |
Antoine Pitrou | 497a767 | 2009-09-17 17:18:01 +0000 | [diff] [blame] | 586 | A buffer providing higher-level access to a readable, sequential |
| 587 | :class:`RawIOBase` object. It inherits :class:`BufferedIOBase`. |
| 588 | When reading data from this object, a larger amount of data may be |
| 589 | requested from the underlying raw stream, and kept in an internal buffer. |
| 590 | The buffered data can then be returned directly on subsequent reads. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 591 | |
| 592 | The constructor creates a :class:`BufferedReader` for the given readable |
| 593 | *raw* stream and *buffer_size*. If *buffer_size* is omitted, |
| 594 | :data:`DEFAULT_BUFFER_SIZE` is used. |
| 595 | |
| 596 | :class:`BufferedReader` provides or overrides these methods in addition to |
| 597 | those from :class:`BufferedIOBase` and :class:`IOBase`: |
| 598 | |
| 599 | .. method:: peek([n]) |
| 600 | |
Benjamin Peterson | c43a26d | 2009-06-16 23:09:24 +0000 | [diff] [blame] | 601 | Return bytes from the stream without advancing the position. At most one |
Benjamin Peterson | 2a8b54d | 2009-06-14 14:37:23 +0000 | [diff] [blame] | 602 | single read on the raw stream is done to satisfy the call. The number of |
| 603 | bytes returned may be less or more than requested. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 604 | |
| 605 | .. method:: read([n]) |
| 606 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 607 | 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] | 608 | or if the read call would block in non-blocking mode. |
| 609 | |
| 610 | .. method:: read1(n) |
| 611 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 612 | 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] | 613 | at least one byte is buffered, only buffered bytes are returned. |
| 614 | Otherwise, one raw stream read call is made. |
| 615 | |
| 616 | |
Georg Brandl | 3dd3388 | 2009-06-01 17:35:27 +0000 | [diff] [blame] | 617 | .. class:: BufferedWriter(raw, buffer_size=DEFAULT_BUFFER_SIZE) |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 618 | |
Antoine Pitrou | 497a767 | 2009-09-17 17:18:01 +0000 | [diff] [blame] | 619 | A buffer providing higher-level access to a writeable, sequential |
| 620 | :class:`RawIOBase` object. It inherits :class:`BufferedIOBase`. |
Eli Bendersky | f877a7c | 2012-07-14 21:22:25 +0300 | [diff] [blame] | 621 | When writing to this object, data is normally placed into an internal |
Antoine Pitrou | 497a767 | 2009-09-17 17:18:01 +0000 | [diff] [blame] | 622 | buffer. The buffer will be written out to the underlying :class:`RawIOBase` |
| 623 | object under various conditions, including: |
| 624 | |
| 625 | * when the buffer gets too small for all pending data; |
| 626 | * when :meth:`flush()` is called; |
| 627 | * when a :meth:`seek()` is requested (for :class:`BufferedRandom` objects); |
| 628 | * when the :class:`BufferedWriter` object is closed or destroyed. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 629 | |
| 630 | The constructor creates a :class:`BufferedWriter` for the given writeable |
| 631 | *raw* stream. If the *buffer_size* is not given, it defaults to |
Benjamin Peterson | 394ee00 | 2009-03-05 22:33:59 +0000 | [diff] [blame] | 632 | :data:`DEFAULT_BUFFER_SIZE`. |
| 633 | |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 634 | :class:`BufferedWriter` provides or overrides these methods in addition to |
| 635 | those from :class:`BufferedIOBase` and :class:`IOBase`: |
| 636 | |
| 637 | .. method:: flush() |
| 638 | |
| 639 | Force bytes held in the buffer into the raw stream. A |
Mark Summerfield | e6d5f30 | 2008-04-21 10:29:45 +0000 | [diff] [blame] | 640 | :exc:`BlockingIOError` should be raised if the raw stream blocks. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 641 | |
| 642 | .. method:: write(b) |
| 643 | |
Eli Bendersky | f877a7c | 2012-07-14 21:22:25 +0300 | [diff] [blame] | 644 | Write the :class:`bytes` or :class:`bytearray` object, *b* and return the |
| 645 | number of bytes written. When in non-blocking mode, a |
| 646 | :exc:`BlockingIOError` is raised if the buffer needs to be written out but |
| 647 | the raw stream blocks. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 648 | |
| 649 | |
Georg Brandl | 3dd3388 | 2009-06-01 17:35:27 +0000 | [diff] [blame] | 650 | .. class:: BufferedRandom(raw, buffer_size=DEFAULT_BUFFER_SIZE) |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 651 | |
| 652 | A buffered interface to random access streams. It inherits |
Antoine Pitrou | 497a767 | 2009-09-17 17:18:01 +0000 | [diff] [blame] | 653 | :class:`BufferedReader` and :class:`BufferedWriter`, and further supports |
| 654 | :meth:`seek` and :meth:`tell` functionality. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 655 | |
Benjamin Peterson | 2c5f828 | 2008-04-13 00:27:46 +0000 | [diff] [blame] | 656 | 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] | 657 | 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] | 658 | :data:`DEFAULT_BUFFER_SIZE`. |
| 659 | |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 660 | :class:`BufferedRandom` is capable of anything :class:`BufferedReader` or |
| 661 | :class:`BufferedWriter` can do. |
| 662 | |
| 663 | |
Antoine Pitrou | 13d2895 | 2011-08-20 19:48:43 +0200 | [diff] [blame] | 664 | .. class:: BufferedRWPair(reader, writer, buffer_size=DEFAULT_BUFFER_SIZE) |
| 665 | |
| 666 | A buffered I/O object combining two unidirectional :class:`RawIOBase` |
| 667 | objects -- one readable, the other writeable -- into a single bidirectional |
| 668 | endpoint. It inherits :class:`BufferedIOBase`. |
| 669 | |
| 670 | *reader* and *writer* are :class:`RawIOBase` objects that are readable and |
| 671 | writeable respectively. If the *buffer_size* is omitted it defaults to |
| 672 | :data:`DEFAULT_BUFFER_SIZE`. |
| 673 | |
Antoine Pitrou | 13d2895 | 2011-08-20 19:48:43 +0200 | [diff] [blame] | 674 | :class:`BufferedRWPair` implements all of :class:`BufferedIOBase`\'s methods |
| 675 | except for :meth:`~BufferedIOBase.detach`, which raises |
| 676 | :exc:`UnsupportedOperation`. |
| 677 | |
| 678 | .. warning:: |
| 679 | :class:`BufferedRWPair` does not attempt to synchronize accesses to |
| 680 | its underlying raw streams. You should not pass it the same object |
| 681 | as reader and writer; use :class:`BufferedRandom` instead. |
| 682 | |
| 683 | |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 684 | Text I/O |
Antoine Pitrou | b530e14 | 2010-08-30 12:41:00 +0000 | [diff] [blame] | 685 | ^^^^^^^^ |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 686 | |
| 687 | .. class:: TextIOBase |
| 688 | |
| 689 | Base class for text streams. This class provides a character and line based |
| 690 | interface to stream I/O. There is no :meth:`readinto` method because |
| 691 | Python's character strings are immutable. It inherits :class:`IOBase`. |
| 692 | There is no public constructor. |
| 693 | |
Mark Summerfield | e6d5f30 | 2008-04-21 10:29:45 +0000 | [diff] [blame] | 694 | :class:`TextIOBase` provides or overrides these data attributes and |
| 695 | methods in addition to those from :class:`IOBase`: |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 696 | |
| 697 | .. attribute:: encoding |
| 698 | |
Mark Summerfield | e6d5f30 | 2008-04-21 10:29:45 +0000 | [diff] [blame] | 699 | 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] | 700 | strings, and to encode strings into bytes. |
| 701 | |
Benjamin Peterson | 0926ad1 | 2009-06-06 18:02:12 +0000 | [diff] [blame] | 702 | .. attribute:: errors |
| 703 | |
| 704 | The error setting of the decoder or encoder. |
| 705 | |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 706 | .. attribute:: newlines |
| 707 | |
Mark Summerfield | e6d5f30 | 2008-04-21 10:29:45 +0000 | [diff] [blame] | 708 | A string, a tuple of strings, or ``None``, indicating the newlines |
Antoine Pitrou | 497a767 | 2009-09-17 17:18:01 +0000 | [diff] [blame] | 709 | translated so far. Depending on the implementation and the initial |
| 710 | constructor flags, this may not be available. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 711 | |
Benjamin Peterson | c609b6b | 2009-06-28 17:32:20 +0000 | [diff] [blame] | 712 | .. attribute:: buffer |
| 713 | |
| 714 | The underlying binary buffer (a :class:`BufferedIOBase` instance) that |
| 715 | :class:`TextIOBase` deals with. This is not part of the |
Eli Bendersky | f877a7c | 2012-07-14 21:22:25 +0300 | [diff] [blame] | 716 | :class:`TextIOBase` API and may not exist in some implementations. |
Benjamin Peterson | c609b6b | 2009-06-28 17:32:20 +0000 | [diff] [blame] | 717 | |
Benjamin Peterson | d2e0c79 | 2009-05-01 20:40:59 +0000 | [diff] [blame] | 718 | .. method:: detach() |
| 719 | |
Antoine Pitrou | 497a767 | 2009-09-17 17:18:01 +0000 | [diff] [blame] | 720 | Separate the underlying binary buffer from the :class:`TextIOBase` and |
| 721 | return it. |
Benjamin Peterson | d2e0c79 | 2009-05-01 20:40:59 +0000 | [diff] [blame] | 722 | |
| 723 | After the underlying buffer has been detached, the :class:`TextIOBase` is |
| 724 | in an unusable state. |
| 725 | |
| 726 | Some :class:`TextIOBase` implementations, like :class:`StringIO`, may not |
| 727 | have the concept of an underlying buffer and calling this method will |
| 728 | raise :exc:`UnsupportedOperation`. |
| 729 | |
Benjamin Peterson | edc3647 | 2009-05-01 20:48:14 +0000 | [diff] [blame] | 730 | .. versionadded:: 3.1 |
| 731 | |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 732 | .. method:: read(n) |
| 733 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 734 | Read and return at most *n* characters from the stream as a single |
Antoine Pitrou | 497a767 | 2009-09-17 17:18:01 +0000 | [diff] [blame] | 735 | :class:`str`. If *n* is negative or ``None``, reads until EOF. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 736 | |
Antoine Pitrou | 707bd4e | 2012-07-25 22:38:33 +0200 | [diff] [blame] | 737 | .. method:: readline(limit=-1) |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 738 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 739 | Read until newline or EOF and return a single ``str``. If the stream is |
| 740 | already at EOF, an empty string is returned. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 741 | |
Antoine Pitrou | 707bd4e | 2012-07-25 22:38:33 +0200 | [diff] [blame] | 742 | If *limit* is specified, at most *limit* characters will be read. |
| 743 | |
Antoine Pitrou | f49d152 | 2012-01-21 20:20:49 +0100 | [diff] [blame] | 744 | .. method:: seek(offset, whence=SEEK_SET) |
| 745 | |
| 746 | Change the stream position to the given *offset*. Behaviour depends |
| 747 | on the *whence* parameter: |
| 748 | |
| 749 | * :data:`SEEK_SET` or ``0``: seek from the start of the stream |
| 750 | (the default); *offset* must either be a number returned by |
| 751 | :meth:`TextIOBase.tell`, or zero. Any other *offset* value |
| 752 | produces undefined behaviour. |
| 753 | * :data:`SEEK_CUR` or ``1``: "seek" to the current position; |
| 754 | *offset* must be zero, which is a no-operation (all other values |
| 755 | are unsupported). |
| 756 | * :data:`SEEK_END` or ``2``: seek to the end of the stream; |
| 757 | *offset* must be zero (all other values are unsupported). |
| 758 | |
| 759 | Return the new absolute position as an opaque number. |
| 760 | |
| 761 | .. versionadded:: 3.1 |
| 762 | The ``SEEK_*`` constants. |
| 763 | |
| 764 | .. method:: tell() |
| 765 | |
| 766 | Return the current stream position as an opaque number. The number |
| 767 | does not usually represent a number of bytes in the underlying |
| 768 | binary storage. |
| 769 | |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 770 | .. method:: write(s) |
| 771 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 772 | Write the string *s* to the stream and return the number of characters |
| 773 | written. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 774 | |
| 775 | |
Antoine Pitrou | 664091b | 2011-07-23 22:00:03 +0200 | [diff] [blame] | 776 | .. class:: TextIOWrapper(buffer, encoding=None, errors=None, newline=None, \ |
| 777 | line_buffering=False, write_through=False) |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 778 | |
Antoine Pitrou | 497a767 | 2009-09-17 17:18:01 +0000 | [diff] [blame] | 779 | A buffered text stream over a :class:`BufferedIOBase` binary stream. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 780 | It inherits :class:`TextIOBase`. |
| 781 | |
| 782 | *encoding* gives the name of the encoding that the stream will be decoded or |
Andrew Svetlov | 4805fa8 | 2012-08-13 22:11:14 +0300 | [diff] [blame] | 783 | encoded with. It defaults to |
| 784 | :func:`locale.getpreferredencoding(False) <locale.getpreferredencoding>`. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 785 | |
Benjamin Peterson | b85a584 | 2008-04-13 21:39:58 +0000 | [diff] [blame] | 786 | *errors* is an optional string that specifies how encoding and decoding |
| 787 | errors are to be handled. Pass ``'strict'`` to raise a :exc:`ValueError` |
| 788 | exception if there is an encoding error (the default of ``None`` has the same |
| 789 | effect), or pass ``'ignore'`` to ignore errors. (Note that ignoring encoding |
| 790 | errors can lead to data loss.) ``'replace'`` causes a replacement marker |
Christian Heimes | a342c01 | 2008-04-20 21:01:16 +0000 | [diff] [blame] | 791 | (such as ``'?'``) to be inserted where there is malformed data. When |
| 792 | writing, ``'xmlcharrefreplace'`` (replace with the appropriate XML character |
| 793 | reference) or ``'backslashreplace'`` (replace with backslashed escape |
| 794 | sequences) can be used. Any other error handling name that has been |
| 795 | registered with :func:`codecs.register_error` is also valid. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 796 | |
R David Murray | 1b00f25 | 2012-08-15 10:43:58 -0400 | [diff] [blame] | 797 | .. index:: |
| 798 | single: universal newlines; io.TextIOWrapper class |
| 799 | |
Antoine Pitrou | 0c1c0d4 | 2012-08-04 00:55:38 +0200 | [diff] [blame] | 800 | *newline* controls how line endings are handled. It can be ``None``, |
| 801 | ``''``, ``'\n'``, ``'\r'``, and ``'\r\n'``. It works as follows: |
| 802 | |
R David Murray | 1b00f25 | 2012-08-15 10:43:58 -0400 | [diff] [blame] | 803 | * When reading input from the stream, if *newline* is ``None``, |
R David Murray | ee0a945 | 2012-08-15 11:05:36 -0400 | [diff] [blame] | 804 | :term:`universal newlines` mode is enabled. Lines in the input can end in |
| 805 | ``'\n'``, ``'\r'``, or ``'\r\n'``, and these are translated into ``'\n'`` |
| 806 | before being returned to the caller. If it is ``''``, universal newlines |
| 807 | mode is enabled, but line endings are returned to the caller untranslated. |
| 808 | If it has any of the other legal values, input lines are only terminated |
| 809 | by the given string, and the line ending is returned to the caller |
| 810 | untranslated. |
Antoine Pitrou | 0c1c0d4 | 2012-08-04 00:55:38 +0200 | [diff] [blame] | 811 | |
Georg Brandl | 296d1be | 2012-08-14 09:39:07 +0200 | [diff] [blame] | 812 | * When writing output to the stream, if *newline* is ``None``, any ``'\n'`` |
| 813 | characters written are translated to the system default line separator, |
| 814 | :data:`os.linesep`. If *newline* is ``''`` or ``'\n'``, no translation |
| 815 | takes place. If *newline* is any of the other legal values, any ``'\n'`` |
| 816 | characters written are translated to the given string. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 817 | |
| 818 | If *line_buffering* is ``True``, :meth:`flush` is implied when a call to |
| 819 | write contains a newline character. |
| 820 | |
Antoine Pitrou | 664091b | 2011-07-23 22:00:03 +0200 | [diff] [blame] | 821 | If *write_through* is ``True``, calls to :meth:`write` are guaranteed |
| 822 | not to be buffered: any data written on the :class:`TextIOWrapper` |
| 823 | object is immediately handled to its underlying binary *buffer*. |
| 824 | |
| 825 | .. versionchanged:: 3.3 |
| 826 | The *write_through* argument has been added. |
| 827 | |
Victor Stinner | f86a5e8 | 2012-06-05 13:43:22 +0200 | [diff] [blame] | 828 | .. versionchanged:: 3.3 |
| 829 | The default *encoding* is now ``locale.getpreferredencoding(False)`` |
| 830 | instead of ``locale.getpreferredencoding()``. Don't change temporary the |
| 831 | locale encoding using :func:`locale.setlocale`, use the current locale |
| 832 | encoding instead of the user preferred encoding. |
| 833 | |
Benjamin Peterson | 0926ad1 | 2009-06-06 18:02:12 +0000 | [diff] [blame] | 834 | :class:`TextIOWrapper` provides one attribute in addition to those of |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 835 | :class:`TextIOBase` and its parents: |
| 836 | |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 837 | .. attribute:: line_buffering |
| 838 | |
| 839 | Whether line buffering is enabled. |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 840 | |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 841 | |
Georg Brandl | 3dd3388 | 2009-06-01 17:35:27 +0000 | [diff] [blame] | 842 | .. class:: StringIO(initial_value='', newline=None) |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 843 | |
Antoine Pitrou | b530e14 | 2010-08-30 12:41:00 +0000 | [diff] [blame] | 844 | An in-memory stream for text I/O. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 845 | |
Benjamin Peterson | aa1c8d8 | 2009-03-09 02:02:23 +0000 | [diff] [blame] | 846 | The initial value of the buffer (an empty string by default) can be set by |
| 847 | providing *initial_value*. The *newline* argument works like that of |
| 848 | :class:`TextIOWrapper`. The default is to do no newline translation. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 849 | |
Mark Summerfield | e6d5f30 | 2008-04-21 10:29:45 +0000 | [diff] [blame] | 850 | :class:`StringIO` provides this method in addition to those from |
Antoine Pitrou | b530e14 | 2010-08-30 12:41:00 +0000 | [diff] [blame] | 851 | :class:`TextIOBase` and its parents: |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 852 | |
| 853 | .. method:: getvalue() |
| 854 | |
Georg Brandl | 2932d93 | 2008-05-30 06:27:09 +0000 | [diff] [blame] | 855 | Return a ``str`` containing the entire contents of the buffer at any |
| 856 | time before the :class:`StringIO` object's :meth:`close` method is |
| 857 | called. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 858 | |
Georg Brandl | 2932d93 | 2008-05-30 06:27:09 +0000 | [diff] [blame] | 859 | Example usage:: |
| 860 | |
| 861 | import io |
| 862 | |
| 863 | output = io.StringIO() |
| 864 | output.write('First line.\n') |
| 865 | print('Second line.', file=output) |
| 866 | |
| 867 | # Retrieve file contents -- this will be |
| 868 | # 'First line.\nSecond line.\n' |
| 869 | contents = output.getvalue() |
| 870 | |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 871 | # Close object and discard memory buffer -- |
Georg Brandl | 2932d93 | 2008-05-30 06:27:09 +0000 | [diff] [blame] | 872 | # .getvalue() will now raise an exception. |
| 873 | output.close() |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 874 | |
Antoine Pitrou | b530e14 | 2010-08-30 12:41:00 +0000 | [diff] [blame] | 875 | |
R David Murray | 1b00f25 | 2012-08-15 10:43:58 -0400 | [diff] [blame] | 876 | .. index:: |
| 877 | single: universal newlines; io.IncrementalNewlineDecoder class |
| 878 | |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 879 | .. class:: IncrementalNewlineDecoder |
| 880 | |
R David Murray | 1b00f25 | 2012-08-15 10:43:58 -0400 | [diff] [blame] | 881 | A helper codec that decodes newlines for :term:`universal newlines` mode. |
| 882 | It inherits :class:`codecs.IncrementalDecoder`. |
Georg Brandl | 014197c | 2008-04-09 18:40:51 +0000 | [diff] [blame] | 883 | |
Antoine Pitrou | bed81c8 | 2010-12-03 19:14:17 +0000 | [diff] [blame] | 884 | |
Antoine Pitrou | bed81c8 | 2010-12-03 19:14:17 +0000 | [diff] [blame] | 885 | Performance |
Benjamin Peterson | edf5132 | 2011-02-24 03:03:46 +0000 | [diff] [blame] | 886 | ----------- |
| 887 | |
| 888 | This section discusses the performance of the provided concrete I/O |
| 889 | implementations. |
Antoine Pitrou | bed81c8 | 2010-12-03 19:14:17 +0000 | [diff] [blame] | 890 | |
| 891 | Binary I/O |
Benjamin Peterson | edf5132 | 2011-02-24 03:03:46 +0000 | [diff] [blame] | 892 | ^^^^^^^^^^ |
Antoine Pitrou | bed81c8 | 2010-12-03 19:14:17 +0000 | [diff] [blame] | 893 | |
Benjamin Peterson | edf5132 | 2011-02-24 03:03:46 +0000 | [diff] [blame] | 894 | By reading and writing only large chunks of data even when the user asks for a |
| 895 | single byte, buffered I/O hides any inefficiency in calling and executing the |
| 896 | operating system's unbuffered I/O routines. The gain depends on the OS and the |
| 897 | kind of I/O which is performed. For example, on some modern OSes such as Linux, |
| 898 | unbuffered disk I/O can be as fast as buffered I/O. The bottom line, however, |
| 899 | is that buffered I/O offers predictable performance regardless of the platform |
Eli Bendersky | f877a7c | 2012-07-14 21:22:25 +0300 | [diff] [blame] | 900 | and the backing device. Therefore, it is almost always preferable to use |
| 901 | buffered I/O rather than unbuffered I/O for binary data. |
Antoine Pitrou | bed81c8 | 2010-12-03 19:14:17 +0000 | [diff] [blame] | 902 | |
| 903 | Text I/O |
Benjamin Peterson | edf5132 | 2011-02-24 03:03:46 +0000 | [diff] [blame] | 904 | ^^^^^^^^ |
Antoine Pitrou | bed81c8 | 2010-12-03 19:14:17 +0000 | [diff] [blame] | 905 | |
| 906 | Text I/O over a binary storage (such as a file) is significantly slower than |
Benjamin Peterson | edf5132 | 2011-02-24 03:03:46 +0000 | [diff] [blame] | 907 | binary I/O over the same storage, because it requires conversions between |
| 908 | unicode and binary data using a character codec. This can become noticeable |
| 909 | handling huge amounts of text data like large log files. Also, |
| 910 | :meth:`TextIOWrapper.tell` and :meth:`TextIOWrapper.seek` are both quite slow |
| 911 | due to the reconstruction algorithm used. |
Antoine Pitrou | bed81c8 | 2010-12-03 19:14:17 +0000 | [diff] [blame] | 912 | |
| 913 | :class:`StringIO`, however, is a native in-memory unicode container and will |
| 914 | exhibit similar speed to :class:`BytesIO`. |
| 915 | |
| 916 | Multi-threading |
| 917 | ^^^^^^^^^^^^^^^ |
| 918 | |
Benjamin Peterson | edf5132 | 2011-02-24 03:03:46 +0000 | [diff] [blame] | 919 | :class:`FileIO` objects are thread-safe to the extent that the operating system |
| 920 | calls (such as ``read(2)`` under Unix) they wrap are thread-safe too. |
Antoine Pitrou | bed81c8 | 2010-12-03 19:14:17 +0000 | [diff] [blame] | 921 | |
| 922 | Binary buffered objects (instances of :class:`BufferedReader`, |
| 923 | :class:`BufferedWriter`, :class:`BufferedRandom` and :class:`BufferedRWPair`) |
| 924 | protect their internal structures using a lock; it is therefore safe to call |
| 925 | them from multiple threads at once. |
| 926 | |
| 927 | :class:`TextIOWrapper` objects are not thread-safe. |
| 928 | |
| 929 | Reentrancy |
| 930 | ^^^^^^^^^^ |
| 931 | |
| 932 | Binary buffered objects (instances of :class:`BufferedReader`, |
| 933 | :class:`BufferedWriter`, :class:`BufferedRandom` and :class:`BufferedRWPair`) |
| 934 | are not reentrant. While reentrant calls will not happen in normal situations, |
Benjamin Peterson | edf5132 | 2011-02-24 03:03:46 +0000 | [diff] [blame] | 935 | they can arise from doing I/O in a :mod:`signal` handler. If a thread tries to |
Eli Bendersky | f877a7c | 2012-07-14 21:22:25 +0300 | [diff] [blame] | 936 | re-enter a buffered object which it is already accessing, a :exc:`RuntimeError` |
| 937 | is raised. Note this doesn't prohibit a different thread from entering the |
Benjamin Peterson | edf5132 | 2011-02-24 03:03:46 +0000 | [diff] [blame] | 938 | buffered object. |
Antoine Pitrou | bed81c8 | 2010-12-03 19:14:17 +0000 | [diff] [blame] | 939 | |
Benjamin Peterson | edf5132 | 2011-02-24 03:03:46 +0000 | [diff] [blame] | 940 | The above implicitly extends to text files, since the :func:`open()` function |
| 941 | will wrap a buffered object inside a :class:`TextIOWrapper`. This includes |
| 942 | standard streams and therefore affects the built-in function :func:`print()` as |
| 943 | well. |
Antoine Pitrou | bed81c8 | 2010-12-03 19:14:17 +0000 | [diff] [blame] | 944 | |