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