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