Merged revisions 74879 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/branches/py3k ........ r74879 | antoine.pitrou | 2009-09-17 19:18:01 +0200 (jeu., 17 sept. 2009) | 3 lines Issue #6929: fix a couple of statements and clarify a lot of things in the IO docs. ........
This commit is contained in:
parent
7b10c9f301
commit
56abc1f431
|
@ -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
|
||||
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, 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``.
|
||||
|
||||
Besides, the :meth:`read` method 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`.
|
||||
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
|
||||
|
|
Loading…
Reference in New Issue