1
:mod:`io` --- Core tools for working with streams
2
=================================================
5
:synopsis: Core tools for working with streams.
6
.. moduleauthor:: Guido van Rossum <guido@python.org>
7
.. moduleauthor:: Mike Verdone <mike.verdone@gmail.com>
8
.. moduleauthor:: Mark Russell <mark.russell@zen.co.uk>
9
.. moduleauthor:: Antoine Pitrou <solipsis@pitrou.net>
10
.. moduleauthor:: Amaury Forgeot d'Arc <amauryfa@gmail.com>
11
.. moduleauthor:: Benjamin Peterson <benjamin@python.org>
12
.. sectionauthor:: Benjamin Peterson <benjamin@python.org>
16
The :mod:`io` module provides the Python interfaces to stream handling.
17
Under Python 2.x, this is proposed as an alternative to the built-in
18
:class:`file` object, but in Python 3.x it is the default interface to
19
access files and streams.
23
Since this module has been designed primarily for Python 3.x, you have to
24
be aware that all uses of "bytes" in this document refer to the
25
:class:`str` type (of which :class:`bytes` is an alias), and all uses
26
of "text" refer to the :class:`unicode` type. Furthermore, those two
27
types are not interchangeable in the :mod:`io` APIs.
29
At the top of the I/O hierarchy is the abstract base class :class:`IOBase`. It
30
defines the basic interface to a stream. Note, however, that there is no
31
separation between reading and writing to streams; implementations are allowed
32
to raise an :exc:`IOError` if they do not support a given operation.
34
Extending :class:`IOBase` is :class:`RawIOBase` which deals simply with the
35
reading and writing of raw bytes to a stream. :class:`FileIO` subclasses
36
:class:`RawIOBase` to provide an interface to files in the machine's
39
:class:`BufferedIOBase` deals with buffering on a raw byte stream
40
(:class:`RawIOBase`). Its subclasses, :class:`BufferedWriter`,
41
:class:`BufferedReader`, and :class:`BufferedRWPair` buffer streams that are
42
readable, writable, and both readable and writable.
43
:class:`BufferedRandom` provides a buffered interface to random access
44
streams. :class:`BytesIO` is a simple stream of in-memory bytes.
46
Another :class:`IOBase` subclass, :class:`TextIOBase`, deals with
47
streams whose bytes represent text, and handles encoding and decoding
48
from and to :class:`unicode` strings. :class:`TextIOWrapper`, which extends
49
it, is a buffered text interface to a buffered raw stream
50
(:class:`BufferedIOBase`). Finally, :class:`StringIO` is an in-memory
51
stream for unicode text.
53
Argument names are not part of the specification, and only the arguments of
54
:func:`.open` are intended to be used as keyword arguments.
60
.. data:: DEFAULT_BUFFER_SIZE
62
An int containing the default buffer size used by the module's buffered I/O
63
classes. :func:`.open` uses the file's blksize (as obtained by
64
:func:`os.stat`) if possible.
66
.. function:: open(file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True)
68
Open *file* and return a corresponding stream. If the file cannot be opened,
69
an :exc:`IOError` is raised.
71
*file* is either a string giving the pathname (absolute or
72
relative to the current working directory) of the file to be opened or
73
an integer file descriptor of the file to be wrapped. (If a file descriptor
74
is given, it is closed when the returned I/O object is closed, unless
75
*closefd* is set to ``False``.)
77
*mode* is an optional string that specifies the mode in which the file is
78
opened. It defaults to ``'r'`` which means open for reading in text mode.
79
Other common values are ``'w'`` for writing (truncating the file if it
80
already exists), and ``'a'`` for appending (which on *some* Unix systems,
81
means that *all* writes append to the end of the file regardless of the
82
current seek position). In text mode, if *encoding* is not specified the
83
encoding used is platform dependent. (For reading and writing raw bytes use
84
binary mode and leave *encoding* unspecified.) The available modes are:
86
========= ===============================================================
88
--------- ---------------------------------------------------------------
89
``'r'`` open for reading (default)
90
``'w'`` open for writing, truncating the file first
91
``'a'`` open for writing, appending to the end of the file if it exists
93
``'t'`` text mode (default)
94
``'+'`` open a disk file for updating (reading and writing)
95
``'U'`` universal newlines mode (for backwards compatibility; should
96
not be used in new code)
97
========= ===============================================================
99
The default mode is ``'rt'`` (open for reading text). For binary random
100
access, the mode ``'w+b'`` opens and truncates the file to 0 bytes, while
101
``'r+b'`` opens the file without truncation.
103
Python distinguishes between files opened in binary and text modes, even when
104
the underlying operating system doesn't. Files opened in binary mode
105
(including ``'b'`` in the *mode* argument) return contents as :class:`bytes`
106
objects without any decoding. In text mode (the default, or when ``'t'`` is
107
included in the *mode* argument), the contents of the file are returned as
108
:class:`unicode` strings, the bytes having been first decoded using a
109
platform-dependent encoding or using the specified *encoding* if given.
111
*buffering* is an optional integer used to set the buffering policy.
112
Pass 0 to switch buffering off (only allowed in binary mode), 1 to select
113
line buffering (only usable in text mode), and an integer > 1 to indicate
114
the size of a fixed-size chunk buffer. When no *buffering* argument is
115
given, the default buffering policy works as follows:
117
* Binary files are buffered in fixed-size chunks; the size of the buffer
118
is chosen using a heuristic trying to determine the underlying device's
119
"block size" and falling back on :attr:`DEFAULT_BUFFER_SIZE`.
120
On many systems, the buffer will typically be 4096 or 8192 bytes long.
122
* "Interactive" text files (files for which :meth:`isatty` returns True)
123
use line buffering. Other text files use the policy described above
126
*encoding* is the name of the encoding used to decode or encode the file.
127
This should only be used in text mode. The default encoding is platform
128
dependent (whatever :func:`locale.getpreferredencoding` returns), but any
129
encoding supported by Python can be used. See the :mod:`codecs` module for
130
the list of supported encodings.
132
*errors* is an optional string that specifies how encoding and decoding
133
errors are to be handled--this cannot be used in binary mode. Pass
134
``'strict'`` to raise a :exc:`ValueError` exception if there is an encoding
135
error (the default of ``None`` has the same effect), or pass ``'ignore'`` to
136
ignore errors. (Note that ignoring encoding errors can lead to data loss.)
137
``'replace'`` causes a replacement marker (such as ``'?'``) to be inserted
138
where there is malformed data. When writing, ``'xmlcharrefreplace'``
139
(replace with the appropriate XML character reference) or
140
``'backslashreplace'`` (replace with backslashed escape sequences) can be
141
used. Any other error handling name that has been registered with
142
:func:`codecs.register_error` is also valid.
145
single: universal newlines; open() (in module io)
147
*newline* controls how :term:`universal newlines` works (it only applies to
148
text mode). It can be ``None``, ``''``, ``'\n'``, ``'\r'``, and ``'\r\n'``.
151
* On input, if *newline* is ``None``, universal newlines mode is enabled.
152
Lines in the input can end in ``'\n'``, ``'\r'``, or ``'\r\n'``, and these
153
are translated into ``'\n'`` before being returned to the caller. If it is
154
``''``, universal newlines mode is enabled, but line endings are returned to
155
the caller untranslated. If it has any of the other legal values, input
156
lines are only terminated by the given string, and the line ending is
157
returned to the caller untranslated.
159
* On output, if *newline* is ``None``, any ``'\n'`` characters written are
160
translated to the system default line separator, :data:`os.linesep`. If
161
*newline* is ``''``, no translation takes place. If *newline* is any of
162
the other legal values, any ``'\n'`` characters written are translated to
165
If *closefd* is ``False`` and a file descriptor rather than a filename was
166
given, the underlying file descriptor will be kept open when the file is
167
closed. If a filename is given *closefd* has no effect and must be ``True``
170
The type of file object returned by the :func:`.open` function depends on the
171
mode. When :func:`.open` is used to open a file in a text mode (``'w'``,
172
``'r'``, ``'wt'``, ``'rt'``, etc.), it returns a subclass of
173
:class:`TextIOBase` (specifically :class:`TextIOWrapper`). When used to open
174
a file in a binary mode with buffering, the returned class is a subclass of
175
:class:`BufferedIOBase`. The exact class varies: in read binary mode, it
176
returns a :class:`BufferedReader`; in write binary and append binary modes,
177
it returns a :class:`BufferedWriter`, and in read/write mode, it returns a
178
:class:`BufferedRandom`. When buffering is disabled, the raw stream, a
179
subclass of :class:`RawIOBase`, :class:`FileIO`, is returned.
181
It is also possible to use an :class:`unicode` or :class:`bytes` string
182
as a file for both reading and writing. For :class:`unicode` strings
183
:class:`StringIO` can be used like a file opened in text mode,
184
and for :class:`bytes` a :class:`BytesIO` can be used like a
185
file opened in a binary mode.
188
.. exception:: BlockingIOError
190
Error raised when blocking would occur on a non-blocking stream. It inherits
193
In addition to those of :exc:`IOError`, :exc:`BlockingIOError` has one
196
.. attribute:: characters_written
198
An integer containing the number of characters written to the stream
202
.. exception:: UnsupportedOperation
204
An exception inheriting :exc:`IOError` and :exc:`ValueError` that is raised
205
when an unsupported operation is called on a stream.
213
The abstract base class for all I/O classes, acting on streams of bytes.
214
There is no public constructor.
216
This class provides empty abstract implementations for many methods
217
that derived classes can override selectively; the default
218
implementations represent a file that cannot be read, written or
221
Even though :class:`IOBase` does not declare :meth:`read`, :meth:`readinto`,
222
or :meth:`write` because their signatures will vary, implementations and
223
clients should consider those methods part of the interface. Also,
224
implementations may raise a :exc:`IOError` when operations they do not
227
The basic type used for binary data read from or written to a file is
228
:class:`bytes` (also known as :class:`str`). :class:`bytearray`\s are
229
accepted too, and in some cases (such as :class:`readinto`) required.
230
Text I/O classes work with :class:`unicode` data.
232
Note that calling any method (even inquiries) on a closed stream is
233
undefined. Implementations may raise :exc:`IOError` in this case.
235
IOBase (and its subclasses) support the iterator protocol, meaning that an
236
:class:`IOBase` object can be iterated over yielding the lines in a stream.
237
Lines are defined slightly differently depending on whether the stream is
238
a binary stream (yielding :class:`bytes`), or a text stream (yielding
239
:class:`unicode` strings). See :meth:`~IOBase.readline` below.
241
IOBase is also a context manager and therefore supports the
242
:keyword:`with` statement. In this example, *file* is closed after the
243
:keyword:`with` statement's suite is finished---even if an exception occurs::
245
with io.open('spam.txt', 'w') as file:
246
file.write(u'Spam and eggs!')
248
:class:`IOBase` provides these data attributes and methods:
252
Flush and close this stream. This method has no effect if the file is
253
already closed. Once the file is closed, any operation on the file
254
(e.g. reading or writing) will raise a :exc:`ValueError`.
256
As a convenience, it is allowed to call this method more than once;
257
only the first call, however, will have an effect.
259
.. attribute:: closed
261
True if the stream is closed.
265
Return the underlying file descriptor (an integer) of the stream if it
266
exists. An :exc:`IOError` is raised if the IO object does not use a file
271
Flush the write buffers of the stream if applicable. This does nothing
272
for read-only and non-blocking streams.
276
Return ``True`` if the stream is interactive (i.e., connected to
277
a terminal/tty device).
279
.. method:: readable()
281
Return ``True`` if the stream can be read from. If ``False``, :meth:`read`
282
will raise :exc:`IOError`.
284
.. method:: readline(limit=-1)
286
Read and return one line from the stream. If *limit* is specified, at
287
most *limit* bytes will be read.
289
The line terminator is always ``b'\n'`` for binary files; for text files,
290
the *newline* argument to :func:`.open` can be used to select the line
291
terminator(s) recognized.
293
.. method:: readlines(hint=-1)
295
Read and return a list of lines from the stream. *hint* can be specified
296
to control the number of lines read: no more lines will be read if the
297
total size (in bytes/characters) of all lines so far exceeds *hint*.
299
Note that it's already possible to iterate on file objects using ``for
300
line in file: ...`` without calling ``file.readlines()``.
302
.. method:: seek(offset[, whence])
304
Change the stream position to the given byte *offset*. *offset* is
305
interpreted relative to the position indicated by *whence*. The default
306
value for *whence* is :data:`SEEK_SET`. Values for *whence* are:
308
* :data:`SEEK_SET` or ``0`` -- start of the stream (the default);
309
*offset* should be zero or positive
310
* :data:`SEEK_CUR` or ``1`` -- current stream position; *offset* may
312
* :data:`SEEK_END` or ``2`` -- end of the stream; *offset* is usually
315
Return the new absolute position.
317
.. versionadded:: 2.7
318
The ``SEEK_*`` constants
320
.. method:: seekable()
322
Return ``True`` if the stream supports random access. If ``False``,
323
:meth:`seek`, :meth:`tell` and :meth:`truncate` will raise :exc:`IOError`.
327
Return the current stream position.
329
.. method:: truncate(size=None)
331
Resize the stream to the given *size* in bytes (or the current position
332
if *size* is not specified). The current stream position isn't changed.
333
This resizing can extend or reduce the current file size. In case of
334
extension, the contents of the new file area depend on the platform
335
(on most systems, additional bytes are zero-filled, on Windows they're
336
undetermined). The new file size is returned.
338
.. method:: writable()
340
Return ``True`` if the stream supports writing. If ``False``,
341
:meth:`write` and :meth:`truncate` will raise :exc:`IOError`.
343
.. method:: writelines(lines)
345
Write a list of lines to the stream. Line separators are not added, so it
346
is usual for each of the lines provided to have a line separator at the
349
.. method:: __del__()
351
Prepare for object destruction. :class:`IOBase` provides a default
352
implementation of this method that calls the instance's
353
:meth:`~IOBase.close` method.
358
Base class for raw binary I/O. It inherits :class:`IOBase`. There is no
361
Raw binary I/O typically provides low-level access to an underlying OS
362
device or API, and does not try to encapsulate it in high-level primitives
363
(this is left to Buffered I/O and Text I/O, described later in this page).
365
In addition to the attributes and methods from :class:`IOBase`,
366
RawIOBase provides the following methods:
368
.. method:: read(n=-1)
370
Read up to *n* bytes from the object and return them. As a convenience,
371
if *n* is unspecified or -1, :meth:`readall` is called. Otherwise,
372
only one system call is ever made. Fewer than *n* bytes may be
373
returned if the operating system call returns fewer than *n* bytes.
375
If 0 bytes are returned, and *n* was not 0, this indicates end of file.
376
If the object is in non-blocking mode and no bytes are available,
377
``None`` is returned.
379
.. method:: readall()
381
Read and return all the bytes from the stream until EOF, using multiple
382
calls to the stream if necessary.
384
.. method:: readinto(b)
386
Read up to len(b) bytes into bytearray *b* and return the number
387
of bytes read. If the object is in non-blocking mode and no
388
bytes are available, ``None`` is returned.
392
Write the given bytes or bytearray object, *b*, to the underlying raw
393
stream and return the number of bytes written. This can be less than
394
``len(b)``, depending on specifics of the underlying raw stream, and
395
especially if it is in non-blocking mode. ``None`` is returned if the
396
raw stream is set not to block and no single byte could be readily
400
.. class:: BufferedIOBase
402
Base class for binary streams that support some kind of buffering.
403
It inherits :class:`IOBase`. There is no public constructor.
405
The main difference with :class:`RawIOBase` is that methods :meth:`read`,
406
:meth:`readinto` and :meth:`write` will try (respectively) to read as much
407
input as requested or to consume all given output, at the expense of
408
making perhaps more than one system call.
410
In addition, those methods can raise :exc:`BlockingIOError` if the
411
underlying raw stream is in non-blocking mode and cannot take or give
412
enough data; unlike their :class:`RawIOBase` counterparts, they will
413
never return ``None``.
415
Besides, the :meth:`read` method does not have a default
416
implementation that defers to :meth:`readinto`.
418
A typical :class:`BufferedIOBase` implementation should not inherit from a
419
:class:`RawIOBase` implementation, but wrap one, like
420
:class:`BufferedWriter` and :class:`BufferedReader` do.
422
:class:`BufferedIOBase` provides or overrides these methods and attribute in
423
addition to those from :class:`IOBase`:
427
The underlying raw stream (a :class:`RawIOBase` instance) that
428
:class:`BufferedIOBase` deals with. This is not part of the
429
:class:`BufferedIOBase` API and may not exist on some implementations.
433
Separate the underlying raw stream from the buffer and return it.
435
After the raw stream has been detached, the buffer is in an unusable
438
Some buffers, like :class:`BytesIO`, do not have the concept of a single
439
raw stream to return from this method. They raise
440
:exc:`UnsupportedOperation`.
442
.. versionadded:: 2.7
444
.. method:: read(n=-1)
446
Read and return up to *n* bytes. If the argument is omitted, ``None``, or
447
negative, data is read and returned until EOF is reached. An empty bytes
448
object is returned if the stream is already at EOF.
450
If the argument is positive, and the underlying raw stream is not
451
interactive, multiple raw reads may be issued to satisfy the byte count
452
(unless EOF is reached first). But for interactive raw streams, at most
453
one raw read will be issued, and a short result does not imply that EOF is
456
A :exc:`BlockingIOError` is raised if the underlying raw stream is in
457
non blocking-mode, and has no data available at the moment.
459
.. method:: read1(n=-1)
461
Read and return up to *n* bytes, with at most one call to the underlying
462
raw stream's :meth:`~RawIOBase.read` method. This can be useful if you
463
are implementing your own buffering on top of a :class:`BufferedIOBase`
466
.. method:: readinto(b)
468
Read up to len(b) bytes into bytearray *b* and return the number of bytes
471
Like :meth:`read`, multiple reads may be issued to the underlying raw
472
stream, unless the latter is 'interactive'.
474
A :exc:`BlockingIOError` is raised if the underlying raw stream is in
475
non blocking-mode, and has no data available at the moment.
479
Write the given bytes or bytearray object, *b* and return the number
480
of bytes written (never less than ``len(b)``, since if the write fails
481
an :exc:`IOError` will be raised). Depending on the actual
482
implementation, these bytes may be readily written to the underlying
483
stream, or held in a buffer for performance and latency reasons.
485
When in non-blocking mode, a :exc:`BlockingIOError` is raised if the
486
data needed to be written to the raw stream but it couldn't accept
487
all the data without blocking.
493
.. class:: FileIO(name, mode='r', closefd=True)
495
:class:`FileIO` represents an OS-level file containing bytes data.
496
It implements the :class:`RawIOBase` interface (and therefore the
497
:class:`IOBase` interface, too).
499
The *name* can be one of two things:
501
* a string representing the path to the file which will be opened;
502
* an integer representing the number of an existing OS-level file descriptor
503
to which the resulting :class:`FileIO` object will give access.
505
The *mode* can be ``'r'``, ``'w'`` or ``'a'`` for reading (default), writing,
506
or appending. The file will be created if it doesn't exist when opened for
507
writing or appending; it will be truncated when opened for writing. Add a
508
``'+'`` to the mode to allow simultaneous reading and writing.
510
The :meth:`read` (when called with a positive argument), :meth:`readinto`
511
and :meth:`write` methods on this class will only make one system call.
513
In addition to the attributes and methods from :class:`IOBase` and
514
:class:`RawIOBase`, :class:`FileIO` provides the following data
515
attributes and methods:
519
The mode as given in the constructor.
523
The file name. This is the file descriptor of the file when no name is
524
given in the constructor.
530
Buffered I/O streams provide a higher-level interface to an I/O device
533
.. class:: BytesIO([initial_bytes])
535
A stream implementation using an in-memory bytes buffer. It inherits
536
:class:`BufferedIOBase`.
538
The argument *initial_bytes* is an optional initial :class:`bytes`.
540
:class:`BytesIO` provides or overrides these methods in addition to those
541
from :class:`BufferedIOBase` and :class:`IOBase`:
543
.. method:: getvalue()
545
Return ``bytes`` containing the entire contents of the buffer.
549
In :class:`BytesIO`, this is the same as :meth:`read`.
552
.. class:: BufferedReader(raw, buffer_size=DEFAULT_BUFFER_SIZE)
554
A buffer providing higher-level access to a readable, sequential
555
:class:`RawIOBase` object. It inherits :class:`BufferedIOBase`.
556
When reading data from this object, a larger amount of data may be
557
requested from the underlying raw stream, and kept in an internal buffer.
558
The buffered data can then be returned directly on subsequent reads.
560
The constructor creates a :class:`BufferedReader` for the given readable
561
*raw* stream and *buffer_size*. If *buffer_size* is omitted,
562
:data:`DEFAULT_BUFFER_SIZE` is used.
564
:class:`BufferedReader` provides or overrides these methods in addition to
565
those from :class:`BufferedIOBase` and :class:`IOBase`:
567
.. method:: peek([n])
569
Return bytes from the stream without advancing the position. At most one
570
single read on the raw stream is done to satisfy the call. The number of
571
bytes returned may be less or more than requested.
573
.. method:: read([n])
575
Read and return *n* bytes, or if *n* is not given or negative, until EOF
576
or if the read call would block in non-blocking mode.
580
Read and return up to *n* bytes with only one call on the raw stream. If
581
at least one byte is buffered, only buffered bytes are returned.
582
Otherwise, one raw stream read call is made.
585
.. class:: BufferedWriter(raw, buffer_size=DEFAULT_BUFFER_SIZE)
587
A buffer providing higher-level access to a writeable, sequential
588
:class:`RawIOBase` object. It inherits :class:`BufferedIOBase`.
589
When writing to this object, data is normally held into an internal
590
buffer. The buffer will be written out to the underlying :class:`RawIOBase`
591
object under various conditions, including:
593
* when the buffer gets too small for all pending data;
594
* when :meth:`flush()` is called;
595
* when a :meth:`seek()` is requested (for :class:`BufferedRandom` objects);
596
* when the :class:`BufferedWriter` object is closed or destroyed.
598
The constructor creates a :class:`BufferedWriter` for the given writeable
599
*raw* stream. If the *buffer_size* is not given, it defaults to
600
:data:`DEFAULT_BUFFER_SIZE`.
602
A third argument, *max_buffer_size*, is supported, but unused and deprecated.
604
:class:`BufferedWriter` provides or overrides these methods in addition to
605
those from :class:`BufferedIOBase` and :class:`IOBase`:
609
Force bytes held in the buffer into the raw stream. A
610
:exc:`BlockingIOError` should be raised if the raw stream blocks.
614
Write the bytes or bytearray object, *b* and return the number of bytes
615
written. When in non-blocking mode, a :exc:`BlockingIOError` is raised
616
if the buffer needs to be written out but the raw stream blocks.
619
.. class:: BufferedRandom(raw, buffer_size=DEFAULT_BUFFER_SIZE)
621
A buffered interface to random access streams. It inherits
622
:class:`BufferedReader` and :class:`BufferedWriter`, and further supports
623
:meth:`seek` and :meth:`tell` functionality.
625
The constructor creates a reader and writer for a seekable raw stream, given
626
in the first argument. If the *buffer_size* is omitted it defaults to
627
:data:`DEFAULT_BUFFER_SIZE`.
629
A third argument, *max_buffer_size*, is supported, but unused and deprecated.
631
:class:`BufferedRandom` is capable of anything :class:`BufferedReader` or
632
:class:`BufferedWriter` can do.
635
.. class:: BufferedRWPair(reader, writer, buffer_size=DEFAULT_BUFFER_SIZE)
637
A buffered I/O object combining two unidirectional :class:`RawIOBase`
638
objects -- one readable, the other writeable -- into a single bidirectional
639
endpoint. It inherits :class:`BufferedIOBase`.
641
*reader* and *writer* are :class:`RawIOBase` objects that are readable and
642
writeable respectively. If the *buffer_size* is omitted it defaults to
643
:data:`DEFAULT_BUFFER_SIZE`.
645
A fourth argument, *max_buffer_size*, is supported, but unused and
648
:class:`BufferedRWPair` implements all of :class:`BufferedIOBase`\'s methods
649
except for :meth:`~BufferedIOBase.detach`, which raises
650
:exc:`UnsupportedOperation`.
654
:class:`BufferedRWPair` does not attempt to synchronize accesses to
655
its underlying raw streams. You should not pass it the same object
656
as reader and writer; use :class:`BufferedRandom` instead.
662
.. class:: TextIOBase
664
Base class for text streams. This class provides an unicode character
665
and line based interface to stream I/O. There is no :meth:`readinto`
666
method because Python's :class:`unicode` strings are immutable.
667
It inherits :class:`IOBase`. There is no public constructor.
669
:class:`TextIOBase` provides or overrides these data attributes and
670
methods in addition to those from :class:`IOBase`:
672
.. attribute:: encoding
674
The name of the encoding used to decode the stream's bytes into
675
strings, and to encode strings into bytes.
677
.. attribute:: errors
679
The error setting of the decoder or encoder.
681
.. attribute:: newlines
683
A string, a tuple of strings, or ``None``, indicating the newlines
684
translated so far. Depending on the implementation and the initial
685
constructor flags, this may not be available.
687
.. attribute:: buffer
689
The underlying binary buffer (a :class:`BufferedIOBase` instance) that
690
:class:`TextIOBase` deals with. This is not part of the
691
:class:`TextIOBase` API and may not exist on some implementations.
695
Separate the underlying binary buffer from the :class:`TextIOBase` and
698
After the underlying buffer has been detached, the :class:`TextIOBase` is
699
in an unusable state.
701
Some :class:`TextIOBase` implementations, like :class:`StringIO`, may not
702
have the concept of an underlying buffer and calling this method will
703
raise :exc:`UnsupportedOperation`.
705
.. versionadded:: 2.7
709
Read and return at most *n* characters from the stream as a single
710
:class:`unicode`. If *n* is negative or ``None``, reads until EOF.
712
.. method:: readline(limit=-1)
714
Read until newline or EOF and return a single ``unicode``. If the
715
stream is already at EOF, an empty string is returned.
717
If *limit* is specified, at most *limit* characters will be read.
719
.. method:: seek(offset[, whence])
721
Change the stream position to the given *offset*. Behaviour depends on
722
the *whence* parameter. The default value for *whence* is
725
* :data:`SEEK_SET` or ``0``: seek from the start of the stream
726
(the default); *offset* must either be a number returned by
727
:meth:`TextIOBase.tell`, or zero. Any other *offset* value
728
produces undefined behaviour.
729
* :data:`SEEK_CUR` or ``1``: "seek" to the current position;
730
*offset* must be zero, which is a no-operation (all other values
732
* :data:`SEEK_END` or ``2``: seek to the end of the stream;
733
*offset* must be zero (all other values are unsupported).
735
Return the new absolute position as an opaque number.
737
.. versionadded:: 2.7
738
The ``SEEK_*`` constants.
742
Return the current stream position as an opaque number. The number
743
does not usually represent a number of bytes in the underlying
748
Write the :class:`unicode` string *s* to the stream and return the
749
number of characters written.
752
.. class:: TextIOWrapper(buffer, encoding=None, errors=None, newline=None, line_buffering=False)
754
A buffered text stream over a :class:`BufferedIOBase` binary stream.
755
It inherits :class:`TextIOBase`.
757
*encoding* gives the name of the encoding that the stream will be decoded or
758
encoded with. It defaults to :func:`locale.getpreferredencoding`.
760
*errors* is an optional string that specifies how encoding and decoding
761
errors are to be handled. Pass ``'strict'`` to raise a :exc:`ValueError`
762
exception if there is an encoding error (the default of ``None`` has the same
763
effect), or pass ``'ignore'`` to ignore errors. (Note that ignoring encoding
764
errors can lead to data loss.) ``'replace'`` causes a replacement marker
765
(such as ``'?'``) to be inserted where there is malformed data. When
766
writing, ``'xmlcharrefreplace'`` (replace with the appropriate XML character
767
reference) or ``'backslashreplace'`` (replace with backslashed escape
768
sequences) can be used. Any other error handling name that has been
769
registered with :func:`codecs.register_error` is also valid.
772
single: universal newlines; io.TextIOWrapper class
774
*newline* controls how line endings are handled. It can be ``None``,
775
``''``, ``'\n'``, ``'\r'``, and ``'\r\n'``. It works as follows:
777
* On input, if *newline* is ``None``, :term:`universal newlines` mode is
778
enabled. Lines in the input can end in ``'\n'``, ``'\r'``, or ``'\r\n'``,
779
and these are translated into ``'\n'`` before being returned to the
780
caller. If it is ``''``, universal newlines mode is enabled, but line
781
endings are returned to the caller untranslated. If it has any of the
782
other legal values, input lines are only terminated by the given string,
783
and the line ending is returned to the caller untranslated.
785
* On output, if *newline* is ``None``, any ``'\n'`` characters written are
786
translated to the system default line separator, :data:`os.linesep`. If
787
*newline* is ``''``, no translation takes place. If *newline* is any of
788
the other legal values, any ``'\n'`` characters written are translated to
791
If *line_buffering* is ``True``, :meth:`flush` is implied when a call to
792
write contains a newline character.
794
:class:`TextIOWrapper` provides one attribute in addition to those of
795
:class:`TextIOBase` and its parents:
797
.. attribute:: line_buffering
799
Whether line buffering is enabled.
802
.. class:: StringIO(initial_value=u'', newline=u'\\n')
804
An in-memory stream for unicode text. It inherits :class:`TextIOWrapper`.
806
The initial value of the buffer can be set by providing *initial_value*.
807
If newline translation is enabled, newlines will be encoded as if by
808
:meth:`~TextIOBase.write`. The stream is positioned at the start of
811
The *newline* argument works like that of :class:`TextIOWrapper`.
812
The default is to consider only ``\n`` characters as ends of lines and
813
to do no newline translation. If *newline* is set to ``None``,
814
newlines are written as ``\n`` on all platforms, but universal
815
newline decoding is still performed when reading.
817
:class:`StringIO` provides this method in addition to those from
818
:class:`TextIOWrapper` and its parents:
820
.. method:: getvalue()
822
Return a ``unicode`` containing the entire contents of the buffer at any
823
time before the :class:`StringIO` object's :meth:`close` method is
824
called. Newlines are decoded as if by :meth:`~TextIOBase.read`,
825
although the stream position is not changed.
831
output = io.StringIO()
832
output.write(u'First line.\n')
833
output.write(u'Second line.\n')
835
# Retrieve file contents -- this will be
836
# u'First line.\nSecond line.\n'
837
contents = output.getvalue()
839
# Close object and discard memory buffer --
840
# .getvalue() will now raise an exception.
845
single: universal newlines; io.IncrementalNewlineDecoder class
847
.. class:: IncrementalNewlineDecoder
849
A helper codec that decodes newlines for :term:`universal newlines` mode.
850
It inherits :class:`codecs.IncrementalDecoder`.
856
Here we will discuss several advanced topics pertaining to the concrete
857
I/O implementations described above.
865
By reading and writing only large chunks of data even when the user asks
866
for a single byte, buffered I/O is designed to hide any inefficiency in
867
calling and executing the operating system's unbuffered I/O routines. The
868
gain will vary very much depending on the OS and the kind of I/O which is
869
performed (for example, on some contemporary OSes such as Linux, unbuffered
870
disk I/O can be as fast as buffered I/O). The bottom line, however, is
871
that buffered I/O will offer you predictable performance regardless of the
872
platform and the backing device. Therefore, it is most always preferable to
873
use buffered I/O rather than unbuffered I/O.
878
Text I/O over a binary storage (such as a file) is significantly slower than
879
binary I/O over the same storage, because it implies conversions from
880
unicode to binary data using a character codec. This can become noticeable
881
if you handle huge amounts of text data (for example very large log files).
882
Also, :meth:`TextIOWrapper.tell` and :meth:`TextIOWrapper.seek` are both
883
quite slow due to the reconstruction algorithm used.
885
:class:`StringIO`, however, is a native in-memory unicode container and will
886
exhibit similar speed to :class:`BytesIO`.
891
:class:`FileIO` objects are thread-safe to the extent that the operating
892
system calls (such as ``read(2)`` under Unix) they are wrapping are thread-safe
895
Binary buffered objects (instances of :class:`BufferedReader`,
896
:class:`BufferedWriter`, :class:`BufferedRandom` and :class:`BufferedRWPair`)
897
protect their internal structures using a lock; it is therefore safe to call
898
them from multiple threads at once.
900
:class:`TextIOWrapper` objects are not thread-safe.
905
Binary buffered objects (instances of :class:`BufferedReader`,
906
:class:`BufferedWriter`, :class:`BufferedRandom` and :class:`BufferedRWPair`)
907
are not reentrant. While reentrant calls will not happen in normal situations,
908
they can arise if you are doing I/O in a :mod:`signal` handler. If it is
909
attempted to enter a buffered object again while already being accessed
910
*from the same thread*, then a :exc:`RuntimeError` is raised.
912
The above implicitly extends to text files, since the :func:`open()`
913
function will wrap a buffered object inside a :class:`TextIOWrapper`. This
914
includes standard streams and therefore affects the built-in function
915
:func:`print()` as well.
added
removed
python-2.7.11-docs-html/_sources/library/io.txt
