diff options
Diffstat (limited to 'Doc/library')
| -rw-r--r-- | Doc/library/io.rst | 164 |
1 files changed, 96 insertions, 68 deletions
diff --git a/Doc/library/io.rst b/Doc/library/io.rst index 1f6f813..6432d99 100644 --- a/Doc/library/io.rst +++ b/Doc/library/io.rst @@ -208,6 +208,9 @@ I/O Base Classes IOBase (and its subclasses) support the iterator protocol, meaning that an :class:`IOBase` object can be iterated over yielding the lines in a stream. + Lines are defined slightly differently depending on whether the stream is + a binary stream (yielding bytes), or a text stream (yielding character + strings). See :meth:`readline` below. IOBase is also a context manager and therefore supports the :keyword:`with` statement. In this example, *file* is closed after the @@ -314,15 +317,20 @@ I/O Base Classes Base class for raw binary I/O. It inherits :class:`IOBase`. There is no public constructor. + Raw binary I/O typically provides low-level access to an underlying OS + device or API, and does not try to encapsulate it in high-level primitives + (this is left to Buffered I/O and Text I/O, described later in this page). + In addition to the attributes and methods from :class:`IOBase`, RawIOBase provides the following methods: .. method:: read(n=-1) - 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. + Read and return up to *n* bytes from the stream. As a convenience, if + *n* is unspecified or -1, :meth:`readall` is called. Otherwise, + 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. .. method:: readall() @@ -337,27 +345,34 @@ I/O Base Classes .. method:: write(b) 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). + stream and return the number of bytes written. This can be less than + ``len(b)``, depending on specifics of the underlying raw stream, and + especially if it is in non-blocking mode. ``None`` is returned if the + raw stream is set not to block and no single byte could be readily + written to it. .. class:: BufferedIOBase - Base class for streams that support buffering. It inherits :class:`IOBase`. - There is no public constructor. + Base class for binary streams that support some kind of 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`. + The main difference with :class:`RawIOBase` is that methods :meth:`read`, + :meth:`readinto` and :meth:`write` will try (respectively) to read as much + input as requested or to consume all given output, at the expense of + making perhaps more than one system call. - 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``. + In addition, those methods can raise :exc:`BlockingIOError` if the + underlying raw stream is in non-blocking mode and cannot take or give + enough data; unlike their :class:`RawIOBase` 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`. + Besides, the :meth:`read` method does not have a default + implementation that defers to :meth:`readinto`. + + A typical :class:`BufferedIOBase` implementation should not inherit from a + :class:`RawIOBase` implementation, but wrap one, like + :class:`BufferedWriter` and :class:`BufferedReader` do. :class:`BufferedIOBase` provides or overrides these members in addition to those from :class:`IOBase`: @@ -393,13 +408,15 @@ I/O Base Classes 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. + A :exc:`BlockingIOError` is raised if the underlying raw stream is in + non blocking-mode, and has no data available at the moment. .. method:: read1(n=-1) Read and return up to *n* bytes, with at most one call to the underlying - raw stream's :meth:`~RawIOBase.read` method. + raw stream's :meth:`~RawIOBase.read` method. This can be useful if you + are implementing your own buffering on top of a :class:`BufferedIOBase` + object. .. method:: readinto(b) @@ -407,19 +424,22 @@ I/O Base Classes read. Like :meth:`read`, multiple reads may be issued to the underlying raw - stream, unless the latter is 'interactive.' + stream, unless the latter is 'interactive'. - A :exc:`BlockingIOError` is raised if the underlying raw stream has no - data at the moment. + A :exc:`BlockingIOError` is raised if the underlying raw stream is in + non blocking-mode, and has no data available at the moment. .. method:: write(b) - 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). + Write the given bytes or bytearray object, *b* and return the number + of bytes written (never less than ``len(b)``, since if the write fails + an :exc:`IOError` will be raised). Depending on the actual + implementation, these bytes may be readily written to the underlying + stream, or held in a buffer for performance and latency reasons. - A :exc:`BlockingIOError` is raised if the buffer is full, and the - underlying raw stream cannot accept more data at the moment. + When in non-blocking mode, a :exc:`BlockingIOError` is raised if the + data needed to be written to the raw stream but it couldn't accept + all the data without blocking. Raw File I/O @@ -427,15 +447,25 @@ Raw File I/O .. class:: FileIO(name, mode='r', closefd=True) - :class:`FileIO` represents a file containing bytes data. It implements - the :class:`RawIOBase` interface (and therefore the :class:`IOBase` - interface, too). + :class:`FileIO` represents an OS-level file containing bytes data. + It implements the :class:`RawIOBase` interface (and therefore the + :class:`IOBase` interface, too). + + The *name* can be one of two things: + + * a character string or bytes object representing the path to the file + which will be opened; + * an integer representing the number of an existing OS-level file descriptor + to which the resulting :class:`FileIO` object will give access. 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. + The :meth:`read` (when called with a positive argument), :meth:`readinto` + and :meth:`write` methods on this class will only make one system call. + In addition to the attributes and methods from :class:`IOBase` and :class:`RawIOBase`, :class:`FileIO` provides the following data attributes and methods: @@ -449,29 +479,13 @@ Raw File I/O The file name. This is the file descriptor of the file when no name is given in the constructor. - .. method:: read(n=-1) - - 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. - Buffered Streams ---------------- +In many situations, buffered I/O streams will provide higher performance +(bandwidth and latency) than raw I/O streams. Their API is also more usable. + .. class:: BytesIO([initial_bytes]) A stream implementation using an in-memory bytes buffer. It inherits @@ -498,8 +512,11 @@ Buffered Streams .. class:: BufferedReader(raw, buffer_size=DEFAULT_BUFFER_SIZE) - A buffer for a readable, sequential :class:`RawIOBase` object. It inherits - :class:`BufferedIOBase`. + A buffer providing higher-level access to a readable, sequential + :class:`RawIOBase` object. It inherits :class:`BufferedIOBase`. + When reading data from this object, a larger amount of data may be + requested from the underlying raw stream, and kept in an internal buffer. + The buffered data can then be returned directly on subsequent reads. The constructor creates a :class:`BufferedReader` for the given readable *raw* stream and *buffer_size*. If *buffer_size* is omitted, @@ -528,8 +545,16 @@ Buffered Streams .. class:: BufferedWriter(raw, buffer_size=DEFAULT_BUFFER_SIZE) - A buffer for a writeable sequential RawIO object. It inherits - :class:`BufferedIOBase`. + A buffer providing higher-level access to a writeable, sequential + :class:`RawIOBase` object. It inherits :class:`BufferedIOBase`. + When writing to this object, data is normally held into an internal + buffer. The buffer will be written out to the underlying :class:`RawIOBase` + object under various conditions, including: + + * when the buffer gets too small for all pending data; + * when :meth:`flush()` is called; + * when a :meth:`seek()` is requested (for :class:`BufferedRandom` objects); + * when the :class:`BufferedWriter` object is closed or destroyed. The constructor creates a :class:`BufferedWriter` for the given writeable *raw* stream. If the *buffer_size* is not given, it defaults to @@ -547,17 +572,17 @@ Buffered Streams .. method:: write(b) - 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. + Write the bytes or bytearray object, *b* and return the number of bytes + written. When in non-blocking mode, a :exc:`BlockingIOError` is raised + if the buffer needs to be written out but the raw stream blocks. -.. class:: BufferedRWPair(reader, writer, buffer_size, max_buffer_size=DEFAULT_BUFFER_SIZE) +.. class:: BufferedRWPair(reader, writer, buffer_size=DEFAULT_BUFFER_SIZE) - 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`. + A buffered I/O object giving a combined, higher-level access to two + sequential :class:`RawIOBase` objects: one readable, the other writeable. + It is useful for pairs of unidirectional communication channels + (pipes, for instance). It inherits :class:`BufferedIOBase`. *reader* and *writer* are :class:`RawIOBase` objects that are readable and writeable respectively. If the *buffer_size* is omitted it defaults to @@ -574,7 +599,8 @@ Buffered Streams .. class:: BufferedRandom(raw, buffer_size=DEFAULT_BUFFER_SIZE) A buffered interface to random access streams. It inherits - :class:`BufferedReader` and :class:`BufferedWriter`. + :class:`BufferedReader` and :class:`BufferedWriter`, and further supports + :meth:`seek` and :meth:`tell` functionality. 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 @@ -611,7 +637,8 @@ Text I/O .. attribute:: newlines A string, a tuple of strings, or ``None``, indicating the newlines - translated so far. + translated so far. Depending on the implementation and the initial + constructor flags, this may not be available. .. attribute:: buffer @@ -621,7 +648,8 @@ Text I/O .. method:: detach() - Separate the underlying buffer from the :class:`TextIOBase` and return it. + Separate the underlying binary buffer from the :class:`TextIOBase` and + return it. After the underlying buffer has been detached, the :class:`TextIOBase` is in an unusable state. @@ -635,7 +663,7 @@ Text I/O .. method:: read(n) Read and return at most *n* characters from the stream as a single - :class:`str`. If *n* is negative or ``None``, reads to EOF. + :class:`str`. If *n* is negative or ``None``, reads until EOF. .. method:: readline() @@ -650,7 +678,7 @@ Text I/O .. class:: TextIOWrapper(buffer, encoding=None, errors=None, newline=None, line_buffering=False) - A buffered text stream over a :class:`BufferedIOBase` raw stream, *buffer*. + A buffered text stream over a :class:`BufferedIOBase` binary stream. It inherits :class:`TextIOBase`. *encoding* gives the name of the encoding that the stream will be decoded or |