2008-04-12 23:01:27 -03:00
|
|
|
:mod:`io` --- Core tools for working with streams
|
|
|
|
=================================================
|
|
|
|
|
|
|
|
.. module:: io
|
|
|
|
:synopsis: Core tools for working with streams.
|
|
|
|
.. moduleauthor:: Guido van Rossum <guido@python.org>
|
|
|
|
.. moduleauthor:: Mike Verdone <mike.verdone@gmail.com>
|
|
|
|
.. moduleauthor:: Mark Russell <mark.russell@zen.co.uk>
|
2009-01-11 15:48:15 -04:00
|
|
|
.. sectionauthor:: Benjamin Peterson <benjamin@python.org>
|
2008-04-12 23:01:27 -03:00
|
|
|
.. versionadded:: 2.6
|
|
|
|
|
|
|
|
The :mod:`io` module provides the Python interfaces to stream handling. The
|
|
|
|
builtin :func:`open` function is defined in this module.
|
|
|
|
|
|
|
|
At the top of the I/O hierarchy is the abstract base class :class:`IOBase`. It
|
|
|
|
defines the basic interface to a stream. Note, however, that there is no
|
2009-02-21 16:27:01 -04:00
|
|
|
separation between reading and writing to streams; implementations are allowed
|
2008-04-12 23:01:27 -03:00
|
|
|
to throw an :exc:`IOError` if they do not support a given operation.
|
|
|
|
|
|
|
|
Extending :class:`IOBase` is :class:`RawIOBase` which deals simply with the
|
|
|
|
reading and writing of raw bytes to a stream. :class:`FileIO` subclasses
|
2008-04-21 08:57:40 -03:00
|
|
|
:class:`RawIOBase` to provide an interface to files in the machine's
|
|
|
|
file system.
|
2008-04-12 23:01:27 -03:00
|
|
|
|
|
|
|
:class:`BufferedIOBase` deals with buffering on a raw byte stream
|
|
|
|
(:class:`RawIOBase`). Its subclasses, :class:`BufferedWriter`,
|
|
|
|
:class:`BufferedReader`, and :class:`BufferedRWPair` buffer streams that are
|
2008-04-21 08:57:40 -03:00
|
|
|
readable, writable, and both readable and writable.
|
|
|
|
:class:`BufferedRandom` provides a buffered interface to random access
|
|
|
|
streams. :class:`BytesIO` is a simple stream of in-memory bytes.
|
2008-04-12 23:01:27 -03:00
|
|
|
|
2008-04-21 08:57:40 -03:00
|
|
|
Another :class:`IOBase` subclass, :class:`TextIOBase`, deals with
|
|
|
|
streams whose bytes represent text, and handles encoding and decoding
|
|
|
|
from and to strings. :class:`TextIOWrapper`, which extends it, is a
|
|
|
|
buffered text interface to a buffered raw stream
|
|
|
|
(:class:`BufferedIOBase`). Finally, :class:`StringIO` is an in-memory
|
|
|
|
stream for text.
|
2008-04-12 23:01:27 -03:00
|
|
|
|
|
|
|
Argument names are not part of the specification, and only the arguments of
|
2009-07-26 11:19:57 -03:00
|
|
|
:func:`.open` are intended to be used as keyword arguments.
|
2008-04-12 23:01:27 -03:00
|
|
|
|
|
|
|
|
|
|
|
Module Interface
|
|
|
|
----------------
|
|
|
|
|
|
|
|
.. data:: DEFAULT_BUFFER_SIZE
|
|
|
|
|
|
|
|
An int containing the default buffer size used by the module's buffered I/O
|
2009-07-26 11:19:57 -03:00
|
|
|
classes. :func:`.open` uses the file's blksize (as obtained by
|
2008-04-12 23:01:27 -03:00
|
|
|
:func:`os.stat`) if possible.
|
|
|
|
|
|
|
|
.. function:: open(file[, mode[, buffering[, encoding[, errors[, newline[, closefd=True]]]]]])
|
|
|
|
|
|
|
|
Open *file* and return a stream. If the file cannot be opened, an
|
|
|
|
:exc:`IOError` is raised.
|
|
|
|
|
|
|
|
*file* is either a string giving the name (and the path if the file isn't in
|
2008-04-21 08:57:40 -03:00
|
|
|
the current working directory) of the file to be opened or a file
|
|
|
|
descriptor of the file to be opened. (If a file descriptor is given,
|
|
|
|
for example, from :func:`os.fdopen`, it is closed when the returned
|
|
|
|
I/O object is closed, unless *closefd* is set to ``False``.)
|
2008-04-12 23:01:27 -03:00
|
|
|
|
|
|
|
*mode* is an optional string that specifies the mode in which the file is
|
|
|
|
opened. It defaults to ``'r'`` which means open for reading in text mode.
|
|
|
|
Other common values are ``'w'`` for writing (truncating the file if it
|
|
|
|
already exists), and ``'a'`` for appending (which on *some* Unix systems,
|
|
|
|
means that *all* writes append to the end of the file regardless of the
|
|
|
|
current seek position). In text mode, if *encoding* is not specified the
|
|
|
|
encoding used is platform dependent. (For reading and writing raw bytes use
|
|
|
|
binary mode and leave *encoding* unspecified.) The available modes are:
|
|
|
|
|
|
|
|
========= ===============================================================
|
|
|
|
Character Meaning
|
|
|
|
--------- ---------------------------------------------------------------
|
|
|
|
``'r'`` open for reading (default)
|
|
|
|
``'w'`` open for writing, truncating the file first
|
|
|
|
``'a'`` open for writing, appending to the end of the file if it exists
|
|
|
|
``'b'`` binary mode
|
|
|
|
``'t'`` text mode (default)
|
|
|
|
``'+'`` open a disk file for updating (reading and writing)
|
2008-04-21 08:57:40 -03:00
|
|
|
``'U'`` universal newline mode (for backwards compatibility; should
|
|
|
|
not be used in new code)
|
2008-04-12 23:01:27 -03:00
|
|
|
========= ===============================================================
|
|
|
|
|
|
|
|
The default mode is ``'rt'`` (open for reading text). For binary random
|
|
|
|
access, the mode ``'w+b'`` opens and truncates the file to 0 bytes, while
|
|
|
|
``'r+b'`` opens the file without truncation.
|
|
|
|
|
|
|
|
Python distinguishes between files opened in binary and text modes, even when
|
|
|
|
the underlying operating system doesn't. Files opened in binary mode
|
2008-04-21 08:57:40 -03:00
|
|
|
(including ``'b'`` in the *mode* argument) return contents as ``bytes``
|
2008-04-12 23:01:27 -03:00
|
|
|
objects without any decoding. In text mode (the default, or when ``'t'`` is
|
2008-04-21 08:57:40 -03:00
|
|
|
included in the *mode* argument), the contents of the file are returned as
|
2008-04-12 23:01:27 -03:00
|
|
|
strings, the bytes having been first decoded using a platform-dependent
|
|
|
|
encoding or using the specified *encoding* if given.
|
|
|
|
|
|
|
|
*buffering* is an optional integer used to set the buffering policy. By
|
|
|
|
default full buffering is on. Pass 0 to switch buffering off (only allowed
|
|
|
|
in binary mode), 1 to set line buffering, and an integer > 1 for full
|
|
|
|
buffering.
|
|
|
|
|
|
|
|
*encoding* is the name of the encoding used to decode or encode the file.
|
|
|
|
This should only be used in text mode. The default encoding is platform
|
2008-04-21 08:57:40 -03:00
|
|
|
dependent, but any encoding supported by Python can be used. See the
|
2008-04-12 23:01:27 -03:00
|
|
|
:mod:`codecs` module for the list of supported encodings.
|
|
|
|
|
2008-04-19 16:34:05 -03:00
|
|
|
*errors* is an optional string that specifies how encoding and decoding
|
2008-04-19 16:47:34 -03:00
|
|
|
errors are to be handled. Pass ``'strict'`` to raise a :exc:`ValueError`
|
|
|
|
exception if there is an encoding error (the default of ``None`` has the same
|
|
|
|
effect), or pass ``'ignore'`` to ignore errors. (Note that ignoring encoding
|
|
|
|
errors can lead to data loss.) ``'replace'`` causes a replacement marker
|
|
|
|
(such as ``'?'``) to be inserted where there is malformed data. When
|
|
|
|
writing, ``'xmlcharrefreplace'`` (replace with the appropriate XML character
|
|
|
|
reference) or ``'backslashreplace'`` (replace with backslashed escape
|
|
|
|
sequences) can be used. Any other error handling name that has been
|
|
|
|
registered with :func:`codecs.register_error` is also valid.
|
2008-04-12 23:01:27 -03:00
|
|
|
|
|
|
|
*newline* controls how universal newlines works (it only applies to text
|
|
|
|
mode). It can be ``None``, ``''``, ``'\n'``, ``'\r'``, and ``'\r\n'``. It
|
|
|
|
works as follows:
|
|
|
|
|
|
|
|
* On input, if *newline* is ``None``, universal newlines mode is enabled.
|
|
|
|
Lines in the input can end in ``'\n'``, ``'\r'``, or ``'\r\n'``, and these
|
|
|
|
are translated into ``'\n'`` before being returned to the caller. If it is
|
|
|
|
``''``, universal newline mode is enabled, but line endings are returned to
|
|
|
|
the caller untranslated. If it has any of the other legal values, input
|
|
|
|
lines are only terminated by the given string, and the line ending is
|
|
|
|
returned to the caller untranslated.
|
|
|
|
|
|
|
|
* On output, if *newline* is ``None``, any ``'\n'`` characters written are
|
|
|
|
translated to the system default line separator, :data:`os.linesep`. If
|
|
|
|
*newline* is ``''``, no translation takes place. If *newline* is any of
|
|
|
|
the other legal values, any ``'\n'`` characters written are translated to
|
|
|
|
the given string.
|
|
|
|
|
2008-04-21 08:57:40 -03:00
|
|
|
If *closefd* is ``False`` and a file descriptor rather than a
|
|
|
|
filename was given, the underlying file descriptor will be kept open
|
|
|
|
when the file is closed. If a filename is given *closefd* has no
|
|
|
|
effect but must be ``True`` (the default).
|
2008-04-12 23:01:27 -03:00
|
|
|
|
2009-07-26 11:19:57 -03:00
|
|
|
The type of file object returned by the :func:`.open` function depends
|
|
|
|
on the mode. When :func:`.open` is used to open a file in a text mode
|
2008-04-21 08:57:40 -03:00
|
|
|
(``'w'``, ``'r'``, ``'wt'``, ``'rt'``, etc.), it returns a
|
|
|
|
:class:`TextIOWrapper`. When used to open a file in a binary mode,
|
|
|
|
the returned class varies: in read binary mode, it returns a
|
|
|
|
:class:`BufferedReader`; in write binary and append binary modes, it
|
|
|
|
returns a :class:`BufferedWriter`, and in read/write mode, it returns
|
|
|
|
a :class:`BufferedRandom`.
|
2008-04-12 23:01:27 -03:00
|
|
|
|
|
|
|
It is also possible to use a string or bytearray as a file for both reading
|
|
|
|
and writing. For strings :class:`StringIO` can be used like a file opened in
|
2008-04-21 08:57:40 -03:00
|
|
|
a text mode, and for bytearrays a :class:`BytesIO` can be used like a
|
|
|
|
file opened in a binary mode.
|
2008-04-12 23:01:27 -03:00
|
|
|
|
|
|
|
|
|
|
|
.. exception:: BlockingIOError
|
|
|
|
|
|
|
|
Error raised when blocking would occur on a non-blocking stream. It inherits
|
|
|
|
:exc:`IOError`.
|
|
|
|
|
|
|
|
In addition to those of :exc:`IOError`, :exc:`BlockingIOError` has one
|
|
|
|
attribute:
|
|
|
|
|
|
|
|
.. attribute:: characters_written
|
|
|
|
|
|
|
|
An integer containing the number of characters written to the stream
|
|
|
|
before it blocked.
|
|
|
|
|
|
|
|
|
|
|
|
.. exception:: UnsupportedOperation
|
|
|
|
|
|
|
|
An exception inheriting :exc:`IOError` and :exc:`ValueError` that is raised
|
|
|
|
when an unsupported operation is called on a stream.
|
|
|
|
|
|
|
|
|
|
|
|
I/O Base Classes
|
|
|
|
----------------
|
|
|
|
|
|
|
|
.. class:: IOBase
|
|
|
|
|
|
|
|
The abstract base class for all I/O classes, acting on streams of bytes.
|
|
|
|
There is no public constructor.
|
|
|
|
|
2008-04-21 08:57:40 -03:00
|
|
|
This class provides empty abstract implementations for many methods
|
|
|
|
that derived classes can override selectively; the default
|
|
|
|
implementations represent a file that cannot be read, written or
|
|
|
|
seeked.
|
2008-04-12 23:01:27 -03:00
|
|
|
|
|
|
|
Even though :class:`IOBase` does not declare :meth:`read`, :meth:`readinto`,
|
|
|
|
or :meth:`write` because their signatures will vary, implementations and
|
|
|
|
clients should consider those methods part of the interface. Also,
|
|
|
|
implementations may raise a :exc:`IOError` when operations they do not
|
|
|
|
support are called.
|
|
|
|
|
|
|
|
The basic type used for binary data read from or written to a file is
|
|
|
|
:class:`bytes`. :class:`bytearray`\s are accepted too, and in some cases
|
2008-04-21 08:57:40 -03:00
|
|
|
(such as :class:`readinto`) required. Text I/O classes work with
|
|
|
|
:class:`str` data.
|
2008-04-12 23:01:27 -03:00
|
|
|
|
|
|
|
Note that calling any method (even inquiries) on a closed stream is
|
|
|
|
undefined. Implementations may raise :exc:`IOError` in this case.
|
|
|
|
|
|
|
|
IOBase (and its subclasses) support the iterator protocol, meaning that an
|
|
|
|
:class:`IOBase` object can be iterated over yielding the lines in a stream.
|
|
|
|
|
2008-04-21 08:57:40 -03:00
|
|
|
IOBase is also a context manager and therefore supports the
|
|
|
|
:keyword:`with` statement. In this example, *file* is closed after the
|
|
|
|
:keyword:`with` statement's suite is finished---even if an exception occurs::
|
2008-04-12 23:01:27 -03:00
|
|
|
|
2008-04-21 08:57:40 -03:00
|
|
|
with open('spam.txt', 'w') as file:
|
|
|
|
file.write('Spam and eggs!')
|
2008-04-12 23:01:27 -03:00
|
|
|
|
2008-04-21 08:57:40 -03:00
|
|
|
:class:`IOBase` provides these data attributes and methods:
|
2008-04-12 23:01:27 -03:00
|
|
|
|
|
|
|
.. method:: close()
|
|
|
|
|
2008-11-20 19:34:31 -04:00
|
|
|
Flush and close this stream. This method has no effect if the file is
|
2009-01-03 16:55:06 -04:00
|
|
|
already closed. Once the file is closed, any operation on the file
|
2008-11-20 19:34:31 -04:00
|
|
|
(e.g. reading or writing) will raise an :exc:`IOError`. The internal
|
|
|
|
file descriptor isn't closed if *closefd* was False.
|
2008-04-12 23:01:27 -03:00
|
|
|
|
|
|
|
.. attribute:: closed
|
|
|
|
|
|
|
|
True if the stream is closed.
|
|
|
|
|
|
|
|
.. method:: fileno()
|
|
|
|
|
2008-04-21 23:16:03 -03:00
|
|
|
Return the underlying file descriptor (an integer) of the stream if it
|
2008-04-12 23:01:27 -03:00
|
|
|
exists. An :exc:`IOError` is raised if the IO object does not use a file
|
|
|
|
descriptor.
|
|
|
|
|
|
|
|
.. method:: flush()
|
|
|
|
|
2008-04-19 16:34:05 -03:00
|
|
|
Flush the write buffers of the stream if applicable. This does nothing
|
|
|
|
for read-only and non-blocking streams.
|
2008-04-12 23:01:27 -03:00
|
|
|
|
|
|
|
.. method:: isatty()
|
|
|
|
|
2008-04-21 23:16:03 -03:00
|
|
|
Return ``True`` if the stream is interactive (i.e., connected to
|
2008-04-21 08:57:40 -03:00
|
|
|
a terminal/tty device).
|
2008-04-12 23:01:27 -03:00
|
|
|
|
|
|
|
.. method:: readable()
|
|
|
|
|
2008-04-21 23:16:03 -03:00
|
|
|
Return ``True`` if the stream can be read from. If False, :meth:`read`
|
|
|
|
will raise :exc:`IOError`.
|
2008-04-12 23:01:27 -03:00
|
|
|
|
|
|
|
.. method:: readline([limit])
|
|
|
|
|
2008-04-21 23:16:03 -03:00
|
|
|
Read and return one line from the stream. If *limit* is specified, at
|
|
|
|
most *limit* bytes will be read.
|
2008-04-12 23:01:27 -03:00
|
|
|
|
|
|
|
The line terminator is always ``b'\n'`` for binary files; for text files,
|
2009-07-26 11:19:57 -03:00
|
|
|
the *newlines* argument to :func:`.open` can be used to select the line
|
2008-04-12 23:01:27 -03:00
|
|
|
terminator(s) recognized.
|
|
|
|
|
|
|
|
.. method:: readlines([hint])
|
|
|
|
|
2008-04-21 23:16:03 -03:00
|
|
|
Read and return a list of lines from the stream. *hint* can be specified
|
|
|
|
to control the number of lines read: no more lines will be read if the
|
|
|
|
total size (in bytes/characters) of all lines so far exceeds *hint*.
|
2008-04-12 23:01:27 -03:00
|
|
|
|
|
|
|
.. method:: seek(offset[, whence])
|
|
|
|
|
2008-04-21 08:57:40 -03:00
|
|
|
Change the stream position to the given byte *offset*. *offset* is
|
2008-04-12 23:01:27 -03:00
|
|
|
interpreted relative to the position indicated by *whence*. Values for
|
|
|
|
*whence* are:
|
|
|
|
|
2009-04-01 18:00:55 -03:00
|
|
|
* :data:`SEEK_SET` or ``0`` -- start of the stream (the default);
|
|
|
|
*offset* should be zero or positive
|
|
|
|
* :data:`SEEK_CUR` or ``1`` -- current stream position; *offset* may
|
|
|
|
be negative
|
|
|
|
* :data:`SEEK_END` or ``2`` -- end of the stream; *offset* is usually
|
|
|
|
negative
|
2008-04-12 23:01:27 -03:00
|
|
|
|
2008-04-21 23:16:03 -03:00
|
|
|
Return the new absolute position.
|
2008-04-12 23:01:27 -03:00
|
|
|
|
2009-04-01 18:00:55 -03:00
|
|
|
.. versionadded:: 2.7
|
|
|
|
The ``SEEK_*`` constants
|
|
|
|
|
2008-04-12 23:01:27 -03:00
|
|
|
.. method:: seekable()
|
|
|
|
|
2008-04-21 23:16:03 -03:00
|
|
|
Return ``True`` if the stream supports random access. If ``False``,
|
|
|
|
:meth:`seek`, :meth:`tell` and :meth:`truncate` will raise :exc:`IOError`.
|
2008-04-12 23:01:27 -03:00
|
|
|
|
|
|
|
.. method:: tell()
|
|
|
|
|
2008-04-21 23:16:03 -03:00
|
|
|
Return the current stream position.
|
2008-04-12 23:01:27 -03:00
|
|
|
|
2008-04-21 08:57:40 -03:00
|
|
|
.. method:: truncate([size])
|
2008-04-12 23:01:27 -03:00
|
|
|
|
2008-04-21 23:16:03 -03:00
|
|
|
Truncate the file to at most *size* bytes. *size* defaults to the current
|
2008-04-12 23:01:27 -03:00
|
|
|
file position, as returned by :meth:`tell`.
|
|
|
|
|
|
|
|
.. method:: writable()
|
|
|
|
|
2008-04-21 23:16:03 -03:00
|
|
|
Return ``True`` if the stream supports writing. If ``False``,
|
2008-04-21 08:57:40 -03:00
|
|
|
:meth:`write` and :meth:`truncate` will raise :exc:`IOError`.
|
2008-04-12 23:01:27 -03:00
|
|
|
|
|
|
|
.. method:: writelines(lines)
|
|
|
|
|
2008-04-21 23:16:03 -03:00
|
|
|
Write a list of lines to the stream. Line separators are not added, so it
|
|
|
|
is usual for each of the lines provided to have a line separator at the
|
|
|
|
end.
|
2008-04-12 23:01:27 -03:00
|
|
|
|
|
|
|
|
|
|
|
.. class:: RawIOBase
|
|
|
|
|
|
|
|
Base class for raw binary I/O. It inherits :class:`IOBase`. There is no
|
|
|
|
public constructor.
|
|
|
|
|
2008-04-21 08:57:40 -03:00
|
|
|
In addition to the attributes and methods from :class:`IOBase`,
|
|
|
|
RawIOBase provides the following methods:
|
2008-04-12 23:01:27 -03:00
|
|
|
|
|
|
|
.. method:: read([n])
|
|
|
|
|
2008-04-21 23:16:03 -03:00
|
|
|
Read and return all the bytes from the stream until EOF, or if *n* is
|
|
|
|
specified, up to *n* bytes. Only one system call is ever made. An empty
|
|
|
|
bytes object is returned on EOF; ``None`` is returned if the object is set
|
|
|
|
not to block and has no data to read.
|
2008-04-12 23:01:27 -03:00
|
|
|
|
|
|
|
.. method:: readall()
|
|
|
|
|
2008-04-21 23:16:03 -03:00
|
|
|
Read and return all the bytes from the stream until EOF, using multiple
|
|
|
|
calls to the stream if necessary.
|
2008-04-12 23:01:27 -03:00
|
|
|
|
|
|
|
.. method:: readinto(b)
|
|
|
|
|
2008-04-21 23:16:03 -03:00
|
|
|
Read up to len(b) bytes into bytearray *b* and return the number of bytes
|
|
|
|
read.
|
2008-04-12 23:01:27 -03:00
|
|
|
|
|
|
|
.. method:: write(b)
|
|
|
|
|
2008-04-21 23:16:03 -03:00
|
|
|
Write the given bytes or bytearray object, *b*, to the underlying raw
|
|
|
|
stream and return the number of bytes written (This is never less than
|
|
|
|
``len(b)``, since if the write fails, an :exc:`IOError` will be raised).
|
2008-04-12 23:01:27 -03:00
|
|
|
|
|
|
|
|
|
|
|
.. class:: BufferedIOBase
|
|
|
|
|
|
|
|
Base class for streams that support buffering. It inherits :class:`IOBase`.
|
|
|
|
There is no public constructor.
|
|
|
|
|
|
|
|
The main difference with :class:`RawIOBase` is that the :meth:`read` method
|
|
|
|
supports omitting the *size* argument, and does not have a default
|
|
|
|
implementation that defers to :meth:`readinto`.
|
|
|
|
|
|
|
|
In addition, :meth:`read`, :meth:`readinto`, and :meth:`write` may raise
|
|
|
|
:exc:`BlockingIOError` if the underlying raw stream is in non-blocking mode
|
|
|
|
and not ready; unlike their raw counterparts, they will never return
|
|
|
|
``None``.
|
|
|
|
|
|
|
|
A typical implementation should not inherit from a :class:`RawIOBase`
|
|
|
|
implementation, but wrap one like :class:`BufferedWriter` and
|
|
|
|
:class:`BufferedReader`.
|
|
|
|
|
|
|
|
:class:`BufferedIOBase` provides or overrides these methods in addition to
|
|
|
|
those from :class:`IOBase`:
|
|
|
|
|
|
|
|
.. method:: read([n])
|
|
|
|
|
2008-04-21 23:16:03 -03:00
|
|
|
Read and return up to *n* bytes. If the argument is omitted, ``None``, or
|
2008-04-12 23:01:27 -03:00
|
|
|
negative, data is read and returned until EOF is reached. An empty bytes
|
|
|
|
object is returned if the stream is already at EOF.
|
|
|
|
|
|
|
|
If the argument is positive, and the underlying raw stream is not
|
|
|
|
interactive, multiple raw reads may be issued to satisfy the byte count
|
|
|
|
(unless EOF is reached first). But for interactive raw streams, at most
|
|
|
|
one raw read will be issued, and a short result does not imply that EOF is
|
|
|
|
imminent.
|
|
|
|
|
|
|
|
A :exc:`BlockingIOError` is raised if the underlying raw stream has no
|
|
|
|
data at the moment.
|
|
|
|
|
|
|
|
.. method:: readinto(b)
|
|
|
|
|
2008-04-21 23:16:03 -03:00
|
|
|
Read up to len(b) bytes into bytearray *b* and return the number of bytes
|
2008-04-12 23:01:27 -03:00
|
|
|
read.
|
|
|
|
|
|
|
|
Like :meth:`read`, multiple reads may be issued to the underlying raw
|
|
|
|
stream, unless the latter is 'interactive.'
|
|
|
|
|
|
|
|
A :exc:`BlockingIOError` is raised if the underlying raw stream has no
|
|
|
|
data at the moment.
|
|
|
|
|
|
|
|
.. method:: write(b)
|
|
|
|
|
2008-04-21 23:16:03 -03:00
|
|
|
Write the given bytes or bytearray object, *b*, to the underlying raw
|
|
|
|
stream and return the number of bytes written (never less than ``len(b)``,
|
|
|
|
since if the write fails an :exc:`IOError` will be raised).
|
2008-04-12 23:01:27 -03:00
|
|
|
|
|
|
|
A :exc:`BlockingIOError` is raised if the buffer is full, and the
|
|
|
|
underlying raw stream cannot accept more data at the moment.
|
|
|
|
|
|
|
|
|
2009-01-19 12:17:54 -04:00
|
|
|
Raw File I/O
|
|
|
|
------------
|
|
|
|
|
|
|
|
.. class:: FileIO(name[, mode])
|
|
|
|
|
|
|
|
:class:`FileIO` represents a file containing bytes data. It implements
|
|
|
|
the :class:`RawIOBase` interface (and therefore the :class:`IOBase`
|
|
|
|
interface, too).
|
|
|
|
|
|
|
|
The *mode* can be ``'r'``, ``'w'`` or ``'a'`` for reading (default), writing,
|
|
|
|
or appending. The file will be created if it doesn't exist when opened for
|
|
|
|
writing or appending; it will be truncated when opened for writing. Add a
|
|
|
|
``'+'`` to the mode to allow simultaneous reading and writing.
|
|
|
|
|
|
|
|
In addition to the attributes and methods from :class:`IOBase` and
|
|
|
|
:class:`RawIOBase`, :class:`FileIO` provides the following data
|
|
|
|
attributes and methods:
|
|
|
|
|
|
|
|
.. attribute:: mode
|
|
|
|
|
|
|
|
The mode as given in the constructor.
|
|
|
|
|
|
|
|
.. attribute:: name
|
|
|
|
|
|
|
|
The file name. This is the file descriptor of the file when no name is
|
|
|
|
given in the constructor.
|
|
|
|
|
|
|
|
.. method:: read([n])
|
|
|
|
|
|
|
|
Read and return at most *n* bytes. Only one system call is made, so it is
|
|
|
|
possible that less data than was requested is returned. Use :func:`len`
|
|
|
|
on the returned bytes object to see how many bytes were actually returned.
|
|
|
|
(In non-blocking mode, ``None`` is returned when no data is available.)
|
|
|
|
|
|
|
|
.. method:: readall()
|
|
|
|
|
|
|
|
Read and return the entire file's contents in a single bytes object. As
|
|
|
|
much as immediately available is returned in non-blocking mode. If the
|
|
|
|
EOF has been reached, ``b''`` is returned.
|
|
|
|
|
|
|
|
.. method:: write(b)
|
|
|
|
|
|
|
|
Write the bytes or bytearray object, *b*, to the file, and return
|
|
|
|
the number actually written. Only one system call is made, so it
|
|
|
|
is possible that only some of the data is written.
|
|
|
|
|
|
|
|
Note that the inherited ``readinto()`` method should not be used on
|
|
|
|
:class:`FileIO` objects.
|
|
|
|
|
|
|
|
|
|
|
|
Buffered Streams
|
|
|
|
----------------
|
|
|
|
|
2008-04-12 23:01:27 -03:00
|
|
|
.. class:: BytesIO([initial_bytes])
|
|
|
|
|
|
|
|
A stream implementation using an in-memory bytes buffer. It inherits
|
|
|
|
:class:`BufferedIOBase`.
|
|
|
|
|
|
|
|
The argument *initial_bytes* is an optional initial bytearray.
|
|
|
|
|
|
|
|
:class:`BytesIO` provides or overrides these methods in addition to those
|
|
|
|
from :class:`BufferedIOBase` and :class:`IOBase`:
|
|
|
|
|
|
|
|
.. method:: getvalue()
|
|
|
|
|
2008-04-21 23:16:03 -03:00
|
|
|
Return ``bytes`` containing the entire contents of the buffer.
|
2008-04-12 23:01:27 -03:00
|
|
|
|
|
|
|
.. method:: read1()
|
|
|
|
|
2008-04-19 16:34:05 -03:00
|
|
|
In :class:`BytesIO`, this is the same as :meth:`read`.
|
2008-04-12 23:01:27 -03:00
|
|
|
|
2008-04-21 08:57:40 -03:00
|
|
|
.. method:: truncate([size])
|
2008-04-12 23:01:27 -03:00
|
|
|
|
2008-04-21 23:16:03 -03:00
|
|
|
Truncate the buffer to at most *size* bytes. *size* defaults to the
|
|
|
|
current stream position, as returned by :meth:`tell`.
|
2008-04-12 23:01:27 -03:00
|
|
|
|
|
|
|
|
|
|
|
.. class:: BufferedReader(raw[, buffer_size])
|
|
|
|
|
2008-04-19 16:34:05 -03:00
|
|
|
A buffer for a readable, sequential :class:`RawIOBase` object. It inherits
|
2008-04-12 23:01:27 -03:00
|
|
|
:class:`BufferedIOBase`.
|
|
|
|
|
|
|
|
The constructor creates a :class:`BufferedReader` for the given readable
|
|
|
|
*raw* stream and *buffer_size*. If *buffer_size* is omitted,
|
|
|
|
:data:`DEFAULT_BUFFER_SIZE` is used.
|
|
|
|
|
|
|
|
:class:`BufferedReader` provides or overrides these methods in addition to
|
|
|
|
those from :class:`BufferedIOBase` and :class:`IOBase`:
|
|
|
|
|
|
|
|
.. method:: peek([n])
|
|
|
|
|
2008-04-21 23:16:03 -03:00
|
|
|
Return 1 (or *n* if specified) bytes from a buffer without advancing the
|
|
|
|
position. Only a single read on the raw stream is done to satisfy the
|
|
|
|
call. The number of bytes returned may be less than requested since at
|
|
|
|
most all the buffer's bytes from the current position to the end are
|
|
|
|
returned.
|
2008-04-12 23:01:27 -03:00
|
|
|
|
|
|
|
.. method:: read([n])
|
|
|
|
|
2008-04-21 23:16:03 -03:00
|
|
|
Read and return *n* bytes, or if *n* is not given or negative, until EOF
|
2008-04-12 23:01:27 -03:00
|
|
|
or if the read call would block in non-blocking mode.
|
|
|
|
|
|
|
|
.. method:: read1(n)
|
|
|
|
|
2008-04-21 23:16:03 -03:00
|
|
|
Read and return up to *n* bytes with only one call on the raw stream. If
|
2008-04-12 23:01:27 -03:00
|
|
|
at least one byte is buffered, only buffered bytes are returned.
|
|
|
|
Otherwise, one raw stream read call is made.
|
|
|
|
|
|
|
|
|
|
|
|
.. class:: BufferedWriter(raw[, buffer_size[, max_buffer_size]])
|
|
|
|
|
|
|
|
A buffer for a writeable sequential RawIO object. It inherits
|
|
|
|
:class:`BufferedIOBase`.
|
|
|
|
|
|
|
|
The constructor creates a :class:`BufferedWriter` for the given writeable
|
|
|
|
*raw* stream. If the *buffer_size* is not given, it defaults to
|
|
|
|
:data:`DEAFULT_BUFFER_SIZE`. If *max_buffer_size* is omitted, it defaults to
|
|
|
|
twice the buffer size.
|
|
|
|
|
|
|
|
:class:`BufferedWriter` provides or overrides these methods in addition to
|
|
|
|
those from :class:`BufferedIOBase` and :class:`IOBase`:
|
|
|
|
|
|
|
|
.. method:: flush()
|
|
|
|
|
|
|
|
Force bytes held in the buffer into the raw stream. A
|
2008-04-21 08:57:40 -03:00
|
|
|
:exc:`BlockingIOError` should be raised if the raw stream blocks.
|
2008-04-12 23:01:27 -03:00
|
|
|
|
|
|
|
.. method:: write(b)
|
|
|
|
|
2008-04-21 23:16:03 -03:00
|
|
|
Write the bytes or bytearray object, *b*, onto the raw stream and return
|
|
|
|
the number of bytes written. A :exc:`BlockingIOError` is raised when the
|
|
|
|
raw stream blocks.
|
2008-04-12 23:01:27 -03:00
|
|
|
|
|
|
|
|
|
|
|
.. class:: BufferedRWPair(reader, writer[, buffer_size[, max_buffer_size]])
|
|
|
|
|
2008-04-21 08:57:40 -03:00
|
|
|
A combined buffered writer and reader object for a raw stream that can be
|
|
|
|
written to and read from. It has and supports both :meth:`read`, :meth:`write`,
|
|
|
|
and their variants. This is useful for sockets and two-way pipes.
|
|
|
|
It inherits :class:`BufferedIOBase`.
|
2008-04-12 23:01:27 -03:00
|
|
|
|
|
|
|
*reader* and *writer* are :class:`RawIOBase` objects that are readable and
|
|
|
|
writeable respectively. If the *buffer_size* is omitted it defaults to
|
|
|
|
:data:`DEFAULT_BUFFER_SIZE`. The *max_buffer_size* (for the buffered writer)
|
|
|
|
defaults to twice the buffer size.
|
|
|
|
|
|
|
|
:class:`BufferedRWPair` implements all of :class:`BufferedIOBase`\'s methods.
|
|
|
|
|
|
|
|
|
|
|
|
.. class:: BufferedRandom(raw[, buffer_size[, max_buffer_size]])
|
|
|
|
|
|
|
|
A buffered interface to random access streams. It inherits
|
|
|
|
:class:`BufferedReader` and :class:`BufferedWriter`.
|
|
|
|
|
|
|
|
The constructor creates a reader and writer for a seekable raw stream, given
|
|
|
|
in the first argument. If the *buffer_size* is omitted it defaults to
|
|
|
|
:data:`DEFAULT_BUFFER_SIZE`. The *max_buffer_size* (for the buffered writer)
|
|
|
|
defaults to twice the buffer size.
|
|
|
|
|
|
|
|
:class:`BufferedRandom` is capable of anything :class:`BufferedReader` or
|
|
|
|
:class:`BufferedWriter` can do.
|
|
|
|
|
|
|
|
|
|
|
|
Text I/O
|
|
|
|
--------
|
|
|
|
|
|
|
|
.. class:: TextIOBase
|
|
|
|
|
|
|
|
Base class for text streams. This class provides a character and line based
|
|
|
|
interface to stream I/O. There is no :meth:`readinto` method because
|
|
|
|
Python's character strings are immutable. It inherits :class:`IOBase`.
|
|
|
|
There is no public constructor.
|
|
|
|
|
2008-04-21 08:57:40 -03:00
|
|
|
:class:`TextIOBase` provides or overrides these data attributes and
|
|
|
|
methods in addition to those from :class:`IOBase`:
|
2008-04-12 23:01:27 -03:00
|
|
|
|
|
|
|
.. attribute:: encoding
|
|
|
|
|
2008-04-21 08:57:40 -03:00
|
|
|
The name of the encoding used to decode the stream's bytes into
|
2008-04-12 23:01:27 -03:00
|
|
|
strings, and to encode strings into bytes.
|
|
|
|
|
2009-06-12 17:14:08 -03:00
|
|
|
.. attribute:: errors
|
|
|
|
|
|
|
|
The error setting of the decoder or encoder.
|
|
|
|
|
2008-04-12 23:01:27 -03:00
|
|
|
.. attribute:: newlines
|
|
|
|
|
2008-04-21 08:57:40 -03:00
|
|
|
A string, a tuple of strings, or ``None``, indicating the newlines
|
2008-04-12 23:01:27 -03:00
|
|
|
translated so far.
|
|
|
|
|
|
|
|
.. method:: read(n)
|
|
|
|
|
2008-04-21 23:16:03 -03:00
|
|
|
Read and return at most *n* characters from the stream as a single
|
|
|
|
:class:`str`. If *n* is negative or ``None``, reads to EOF.
|
2008-04-12 23:01:27 -03:00
|
|
|
|
|
|
|
.. method:: readline()
|
|
|
|
|
2008-04-21 23:16:03 -03:00
|
|
|
Read until newline or EOF and return a single ``str``. If the stream is
|
|
|
|
already at EOF, an empty string is returned.
|
2008-04-12 23:01:27 -03:00
|
|
|
|
|
|
|
.. method:: write(s)
|
|
|
|
|
2008-04-21 23:16:03 -03:00
|
|
|
Write the string *s* to the stream and return the number of characters
|
|
|
|
written.
|
2008-04-12 23:01:27 -03:00
|
|
|
|
|
|
|
|
|
|
|
.. class:: TextIOWrapper(buffer[, encoding[, errors[, newline[, line_buffering]]]])
|
|
|
|
|
|
|
|
A buffered text stream over a :class:`BufferedIOBase` raw stream, *buffer*.
|
|
|
|
It inherits :class:`TextIOBase`.
|
|
|
|
|
|
|
|
*encoding* gives the name of the encoding that the stream will be decoded or
|
|
|
|
encoded with. It defaults to :func:`locale.getpreferredencoding`.
|
|
|
|
|
2008-04-19 16:34:05 -03:00
|
|
|
*errors* is an optional string that specifies how encoding and decoding
|
|
|
|
errors are to be handled. Pass ``'strict'`` to raise a :exc:`ValueError`
|
|
|
|
exception if there is an encoding error (the default of ``None`` has the same
|
|
|
|
effect), or pass ``'ignore'`` to ignore errors. (Note that ignoring encoding
|
|
|
|
errors can lead to data loss.) ``'replace'`` causes a replacement marker
|
2008-04-19 16:47:34 -03:00
|
|
|
(such as ``'?'``) to be inserted where there is malformed data. When
|
|
|
|
writing, ``'xmlcharrefreplace'`` (replace with the appropriate XML character
|
|
|
|
reference) or ``'backslashreplace'`` (replace with backslashed escape
|
|
|
|
sequences) can be used. Any other error handling name that has been
|
|
|
|
registered with :func:`codecs.register_error` is also valid.
|
2008-04-12 23:01:27 -03:00
|
|
|
|
|
|
|
*newline* can be ``None``, ``''``, ``'\n'``, ``'\r'``, or ``'\r\n'``. It
|
|
|
|
controls the handling of line endings. If it is ``None``, universal newlines
|
|
|
|
is enabled. With this enabled, on input, the lines endings ``'\n'``,
|
|
|
|
``'\r'``, or ``'\r\n'`` are translated to ``'\n'`` before being returned to
|
|
|
|
the caller. Conversely, on output, ``'\n'`` is translated to the system
|
2009-02-21 16:27:01 -04:00
|
|
|
default line separator, :data:`os.linesep`. If *newline* is any other of its
|
2008-04-12 23:01:27 -03:00
|
|
|
legal values, that newline becomes the newline when the file is read and it
|
|
|
|
is returned untranslated. On output, ``'\n'`` is converted to the *newline*.
|
|
|
|
|
|
|
|
If *line_buffering* is ``True``, :meth:`flush` is implied when a call to
|
|
|
|
write contains a newline character.
|
|
|
|
|
2009-06-12 17:14:08 -03:00
|
|
|
:class:`TextIOWrapper` provides one attribute in addition to those of
|
2008-04-12 23:01:27 -03:00
|
|
|
:class:`TextIOBase` and its parents:
|
|
|
|
|
|
|
|
.. attribute:: line_buffering
|
|
|
|
|
|
|
|
Whether line buffering is enabled.
|
2009-01-03 16:55:06 -04:00
|
|
|
|
2008-04-12 23:01:27 -03:00
|
|
|
|
|
|
|
.. class:: StringIO([initial_value[, encoding[, errors[, newline]]]])
|
|
|
|
|
2009-02-15 05:19:48 -04:00
|
|
|
An in-memory stream for text. It inherits :class:`TextIOWrapper`.
|
2008-04-12 23:01:27 -03:00
|
|
|
|
|
|
|
Create a new StringIO stream with an inital value, encoding, error handling,
|
|
|
|
and newline setting. See :class:`TextIOWrapper`\'s constructor for more
|
|
|
|
information.
|
|
|
|
|
2008-04-21 08:57:40 -03:00
|
|
|
:class:`StringIO` provides this method in addition to those from
|
2008-04-12 23:01:27 -03:00
|
|
|
:class:`TextIOWrapper` and its parents:
|
|
|
|
|
|
|
|
.. method:: getvalue()
|
|
|
|
|
2008-04-21 23:16:03 -03:00
|
|
|
Return a ``str`` containing the entire contents of the buffer.
|
2008-04-12 23:01:27 -03:00
|
|
|
|
|
|
|
|
|
|
|
.. class:: IncrementalNewlineDecoder
|
|
|
|
|
|
|
|
A helper codec that decodes newlines for universal newlines mode. It
|
|
|
|
inherits :class:`codecs.IncrementalDecoder`.
|
|
|
|
|