10
10
.. versionadded:: 2.6
12
12
The :mod:`io` module provides the Python interfaces to stream handling. The
13
builtin :func:`open` function is defined in this module.
13
built-in :func:`open` function is defined in this module.
15
15
At the top of the I/O hierarchy is the abstract base class :class:`IOBase`. It
16
16
defines the basic interface to a stream. Note, however, that there is no
46
46
.. data:: DEFAULT_BUFFER_SIZE
48
48
An int containing the default buffer size used by the module's buffered I/O
49
classes. :func:`open` uses the file's blksize (as obtained by
49
classes. :func:`.open` uses the file's blksize (as obtained by
50
50
:func:`os.stat`) if possible.
52
52
.. function:: open(file[, mode[, buffering[, encoding[, errors[, newline[, closefd=True]]]]]])
94
94
strings, the bytes having been first decoded using a platform-dependent
95
95
encoding or using the specified *encoding* if given.
97
*buffering* is an optional integer used to set the buffering policy. By
98
default full buffering is on. Pass 0 to switch buffering off (only allowed
99
in binary mode), 1 to set line buffering, and an integer > 1 for full
97
*buffering* is an optional integer used to set the buffering policy.
98
Pass 0 to switch buffering off (only allowed in binary mode), 1 to select
99
line buffering (only usable in text mode), and an integer > 1 to indicate
100
the size of a fixed-size chunk buffer. When no *buffering* argument is
101
given, the default buffering policy works as follows:
103
* Binary files are buffered in fixed-size chunks; the size of the buffer
104
is chosen using a heuristic trying to determine the underlying device's
105
"block size" and falling back on :attr:`DEFAULT_BUFFER_SIZE`.
106
On many systems, the buffer will typically be 4096 or 8192 bytes long.
108
* "Interactive" text files (files for which :meth:`isatty` returns True)
109
use line buffering. Other text files use the policy described above
102
112
*encoding* is the name of the encoding used to decode or encode the file.
103
113
This should only be used in text mode. The default encoding is platform
138
148
when the file is closed. If a filename is given *closefd* has no
139
149
effect but must be ``True`` (the default).
141
The type of file object returned by the :func:`open` function depends
142
on the mode. When :func:`open` is used to open a file in a text mode
151
The type of file object returned by the :func:`.open` function depends
152
on the mode. When :func:`.open` is used to open a file in a text mode
143
153
(``'w'``, ``'r'``, ``'wt'``, ``'rt'``, etc.), it returns a
144
154
:class:`TextIOWrapper`. When used to open a file in a binary mode,
145
155
the returned class varies: in read binary mode, it returns a
250
260
most *limit* bytes will be read.
252
262
The line terminator is always ``b'\n'`` for binary files; for text files,
253
the *newlines* argument to :func:`open` can be used to select the line
263
the *newlines* argument to :func:`.open` can be used to select the line
254
264
terminator(s) recognized.
256
266
.. method:: readlines([hint])
329
339
``len(b)``, since if the write fails, an :exc:`IOError` will be raised).
342
.. class:: BufferedIOBase
344
Base class for streams that support buffering. It inherits :class:`IOBase`.
345
There is no public constructor.
347
The main difference with :class:`RawIOBase` is that the :meth:`read` method
348
supports omitting the *size* argument, and does not have a default
349
implementation that defers to :meth:`readinto`.
351
In addition, :meth:`read`, :meth:`readinto`, and :meth:`write` may raise
352
:exc:`BlockingIOError` if the underlying raw stream is in non-blocking mode
353
and not ready; unlike their raw counterparts, they will never return
356
A typical implementation should not inherit from a :class:`RawIOBase`
357
implementation, but wrap one like :class:`BufferedWriter` and
358
:class:`BufferedReader`.
360
:class:`BufferedIOBase` provides or overrides these methods in addition to
361
those from :class:`IOBase`:
363
.. method:: read([n])
365
Read and return up to *n* bytes. If the argument is omitted, ``None``, or
366
negative, data is read and returned until EOF is reached. An empty bytes
367
object is returned if the stream is already at EOF.
369
If the argument is positive, and the underlying raw stream is not
370
interactive, multiple raw reads may be issued to satisfy the byte count
371
(unless EOF is reached first). But for interactive raw streams, at most
372
one raw read will be issued, and a short result does not imply that EOF is
375
A :exc:`BlockingIOError` is raised if the underlying raw stream has no
378
.. method:: readinto(b)
380
Read up to len(b) bytes into bytearray *b* and return the number of bytes
383
Like :meth:`read`, multiple reads may be issued to the underlying raw
384
stream, unless the latter is 'interactive.'
386
A :exc:`BlockingIOError` is raised if the underlying raw stream has no
391
Write the given bytes or bytearray object, *b*, to the underlying raw
392
stream and return the number of bytes written (never less than ``len(b)``,
393
since if the write fails an :exc:`IOError` will be raised).
395
A :exc:`BlockingIOError` is raised if the buffer is full, and the
396
underlying raw stream cannot accept more data at the moment.
385
.. class:: BufferedIOBase
387
Base class for streams that support buffering. It inherits :class:`IOBase`.
388
There is no public constructor.
390
The main difference with :class:`RawIOBase` is that the :meth:`read` method
391
supports omitting the *size* argument, and does not have a default
392
implementation that defers to :meth:`readinto`.
394
In addition, :meth:`read`, :meth:`readinto`, and :meth:`write` may raise
395
:exc:`BlockingIOError` if the underlying raw stream is in non-blocking mode
396
and not ready; unlike their raw counterparts, they will never return
399
A typical implementation should not inherit from a :class:`RawIOBase`
400
implementation, but wrap one like :class:`BufferedWriter` and
401
:class:`BufferedReader`.
403
:class:`BufferedIOBase` provides or overrides these methods in addition to
404
those from :class:`IOBase`:
406
.. method:: read([n])
408
Read and return up to *n* bytes. If the argument is omitted, ``None``, or
409
negative, data is read and returned until EOF is reached. An empty bytes
410
object is returned if the stream is already at EOF.
412
If the argument is positive, and the underlying raw stream is not
413
interactive, multiple raw reads may be issued to satisfy the byte count
414
(unless EOF is reached first). But for interactive raw streams, at most
415
one raw read will be issued, and a short result does not imply that EOF is
418
A :exc:`BlockingIOError` is raised if the underlying raw stream has no
421
.. method:: readinto(b)
423
Read up to len(b) bytes into bytearray *b* and return the number of bytes
426
Like :meth:`read`, multiple reads may be issued to the underlying raw
427
stream, unless the latter is 'interactive.'
429
A :exc:`BlockingIOError` is raised if the underlying raw stream has no
434
Write the given bytes or bytearray object, *b*, to the underlying raw
435
stream and return the number of bytes written (never less than ``len(b)``,
436
since if the write fails an :exc:`IOError` will be raised).
438
A :exc:`BlockingIOError` is raised if the buffer is full, and the
439
underlying raw stream cannot accept more data at the moment.
442
452
.. class:: BytesIO([initial_bytes])
444
454
A stream implementation using an in-memory bytes buffer. It inherits
634
644
.. class:: StringIO([initial_value[, encoding[, errors[, newline]]]])
636
An in-memory stream for text. It in inherits :class:`TextIOWrapper`.
646
An in-memory stream for text. It inherits :class:`TextIOWrapper`.
638
648
Create a new StringIO stream with an inital value, encoding, error handling,
639
649
and newline setting. See :class:`TextIOWrapper`\'s constructor for more
added
removed
Doc/library/io.rst
