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