A lot of small detailed revisions to the io module's doc.
This commit is contained in:
parent
a342c013fc
commit
e6d5f30d1f
|
@ -18,19 +18,22 @@ to throw an :exc:`IOError` if they do not support a given operation.
|
||||||
|
|
||||||
Extending :class:`IOBase` is :class:`RawIOBase` which deals simply with the
|
Extending :class:`IOBase` is :class:`RawIOBase` which deals simply with the
|
||||||
reading and writing of raw bytes to a stream. :class:`FileIO` subclasses
|
reading and writing of raw bytes to a stream. :class:`FileIO` subclasses
|
||||||
:class:`RawIOBase` to provide an interface to OS files.
|
:class:`RawIOBase` to provide an interface to files in the machine's
|
||||||
|
file system.
|
||||||
|
|
||||||
:class:`BufferedIOBase` deals with buffering on a raw byte stream
|
:class:`BufferedIOBase` deals with buffering on a raw byte stream
|
||||||
(:class:`RawIOBase`). Its subclasses, :class:`BufferedWriter`,
|
(:class:`RawIOBase`). Its subclasses, :class:`BufferedWriter`,
|
||||||
:class:`BufferedReader`, and :class:`BufferedRWPair` buffer streams that are
|
:class:`BufferedReader`, and :class:`BufferedRWPair` buffer streams that are
|
||||||
readable, writable, and both respectively. :class:`BufferedRandom` provides a
|
readable, writable, and both readable and writable.
|
||||||
buffered interface to random access streams. :class:`BytesIO` is a simple
|
:class:`BufferedRandom` provides a buffered interface to random access
|
||||||
stream of in-memory bytes.
|
streams. :class:`BytesIO` is a simple stream of in-memory bytes.
|
||||||
|
|
||||||
Another :class:`IOBase` subclass, :class:`TextIOBase`, deals with the encoding
|
Another :class:`IOBase` subclass, :class:`TextIOBase`, deals with
|
||||||
and decoding of streams into text. :class:`TextIOWrapper`, which extends it, is
|
streams whose bytes represent text, and handles encoding and decoding
|
||||||
a buffered text interface to a buffered raw stream (:class:`BufferedIOBase`).
|
from and to strings. :class:`TextIOWrapper`, which extends it, is a
|
||||||
Finally, :class:`StringIO` is a in-memory stream for text.
|
buffered text interface to a buffered raw stream
|
||||||
|
(:class:`BufferedIOBase`). Finally, :class:`StringIO` is an in-memory
|
||||||
|
stream for text.
|
||||||
|
|
||||||
Argument names are not part of the specification, and only the arguments of
|
Argument names are not part of the specification, and only the arguments of
|
||||||
:func:`open` are intended to be used as keyword arguments.
|
:func:`open` are intended to be used as keyword arguments.
|
||||||
|
@ -51,10 +54,10 @@ Module Interface
|
||||||
:exc:`IOError` is raised.
|
:exc:`IOError` is raised.
|
||||||
|
|
||||||
*file* is either a string giving the name (and the path if the file isn't in
|
*file* is either a string giving the name (and the path if the file isn't in
|
||||||
the current working directory) of the file to be opened or an integer file
|
the current working directory) of the file to be opened or a file
|
||||||
descriptor of the file to be wrapped. (If a file descriptor is given, it is
|
descriptor of the file to be opened. (If a file descriptor is given,
|
||||||
closed when the returned I/O object is closed, unless *closefd* is set to
|
for example, from :func:`os.fdopen`, it is closed when the returned
|
||||||
``False``.)
|
I/O object is closed, unless *closefd* is set to ``False``.)
|
||||||
|
|
||||||
*mode* is an optional string that specifies the mode in which the file is
|
*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.
|
opened. It defaults to ``'r'`` which means open for reading in text mode.
|
||||||
|
@ -74,8 +77,8 @@ Module Interface
|
||||||
``'b'`` binary mode
|
``'b'`` binary mode
|
||||||
``'t'`` text mode (default)
|
``'t'`` text mode (default)
|
||||||
``'+'`` open a disk file for updating (reading and writing)
|
``'+'`` open a disk file for updating (reading and writing)
|
||||||
``'U'`` universal newline mode (for backwards compatibility; unneeded
|
``'U'`` universal newline mode (for backwards compatibility; should
|
||||||
for new code)
|
not be used in new code)
|
||||||
========= ===============================================================
|
========= ===============================================================
|
||||||
|
|
||||||
The default mode is ``'rt'`` (open for reading text). For binary random
|
The default mode is ``'rt'`` (open for reading text). For binary random
|
||||||
|
@ -84,9 +87,9 @@ Module Interface
|
||||||
|
|
||||||
Python distinguishes between files opened in binary and text modes, even when
|
Python distinguishes between files opened in binary and text modes, even when
|
||||||
the underlying operating system doesn't. Files opened in binary mode
|
the underlying operating system doesn't. Files opened in binary mode
|
||||||
(appending ``'b'`` to the *mode* argument) return contents as ``bytes``
|
(including ``'b'`` in the *mode* argument) return contents as ``bytes``
|
||||||
objects without any decoding. In text mode (the default, or when ``'t'`` is
|
objects without any decoding. In text mode (the default, or when ``'t'`` is
|
||||||
appended to the *mode* argument), the contents of the file are returned as
|
included in the *mode* argument), the contents of the file are returned as
|
||||||
strings, the bytes having been first decoded using a platform-dependent
|
strings, the bytes having been first decoded using a platform-dependent
|
||||||
encoding or using the specified *encoding* if given.
|
encoding or using the specified *encoding* if given.
|
||||||
|
|
||||||
|
@ -97,7 +100,7 @@ Module Interface
|
||||||
|
|
||||||
*encoding* is the name of the encoding used to decode or encode the file.
|
*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
|
This should only be used in text mode. The default encoding is platform
|
||||||
dependent, but any encoding supported by Python can be passed. See the
|
dependent, but any encoding supported by Python can be used. See the
|
||||||
:mod:`codecs` module for the list of supported encodings.
|
:mod:`codecs` module for the list of supported encodings.
|
||||||
|
|
||||||
*errors* is an optional string that specifies how encoding and decoding
|
*errors* is an optional string that specifies how encoding and decoding
|
||||||
|
@ -129,23 +132,24 @@ Module Interface
|
||||||
the other legal values, any ``'\n'`` characters written are translated to
|
the other legal values, any ``'\n'`` characters written are translated to
|
||||||
the given string.
|
the given string.
|
||||||
|
|
||||||
If *closefd* is ``False``, the underlying file descriptor will be kept open
|
If *closefd* is ``False`` and a file descriptor rather than a
|
||||||
when the file is closed. This does not work when a file name is given and
|
filename was given, the underlying file descriptor will be kept open
|
||||||
must be ``True`` in that case.
|
when the file is closed. If a filename is given *closefd* has no
|
||||||
|
effect but must be ``True`` (the default).
|
||||||
|
|
||||||
:func:`open` returns a file object whose type depends on the mode, and
|
The type of file object returned by the :func:`open` function depends
|
||||||
through which the standard file operations such as reading and writing are
|
on the mode. When :func:`open` is used to open a file in a text mode
|
||||||
performed. When :func:`open` is used to open a file in a text mode (``'w'``,
|
(``'w'``, ``'r'``, ``'wt'``, ``'rt'``, etc.), it returns a
|
||||||
``'r'``, ``'wt'``, ``'rt'``, etc.), it returns a :class:`TextIOWrapper`.
|
:class:`TextIOWrapper`. When used to open a file in a binary mode,
|
||||||
When used to open a file in a binary mode, the returned class varies: in read
|
the returned class varies: in read binary mode, it returns a
|
||||||
binary mode, it returns a :class:`BufferedReader`; in write binary and append
|
:class:`BufferedReader`; in write binary and append binary modes, it
|
||||||
binary modes, it returns a :class:`BufferedWriter`, and in read/write mode,
|
returns a :class:`BufferedWriter`, and in read/write mode, it returns
|
||||||
it returns a :class:`BufferedRandom`.
|
a :class:`BufferedRandom`.
|
||||||
|
|
||||||
It is also possible to use a string or bytearray as a file for both reading
|
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
|
and writing. For strings :class:`StringIO` can be used like a file opened in
|
||||||
a text mode, and for bytes a :class:`BytesIO` can be used like a file opened
|
a text mode, and for bytearrays a :class:`BytesIO` can be used like a
|
||||||
in a binary mode.
|
file opened in a binary mode.
|
||||||
|
|
||||||
|
|
||||||
.. exception:: BlockingIOError
|
.. exception:: BlockingIOError
|
||||||
|
@ -176,9 +180,10 @@ I/O Base Classes
|
||||||
The abstract base class for all I/O classes, acting on streams of bytes.
|
The abstract base class for all I/O classes, acting on streams of bytes.
|
||||||
There is no public constructor.
|
There is no public constructor.
|
||||||
|
|
||||||
This class provides dummy implementations for many methods that derived
|
This class provides empty abstract implementations for many methods
|
||||||
classes can override selectively; the default implementations represent a
|
that derived classes can override selectively; the default
|
||||||
file that cannot be read, written or seeked.
|
implementations represent a file that cannot be read, written or
|
||||||
|
seeked.
|
||||||
|
|
||||||
Even though :class:`IOBase` does not declare :meth:`read`, :meth:`readinto`,
|
Even though :class:`IOBase` does not declare :meth:`read`, :meth:`readinto`,
|
||||||
or :meth:`write` because their signatures will vary, implementations and
|
or :meth:`write` because their signatures will vary, implementations and
|
||||||
|
@ -188,8 +193,8 @@ I/O Base Classes
|
||||||
|
|
||||||
The basic type used for binary data read from or written to a file is
|
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
|
:class:`bytes`. :class:`bytearray`\s are accepted too, and in some cases
|
||||||
(such as :class:`readinto`) needed. Text I/O classes work with :class:`str`
|
(such as :class:`readinto`) required. Text I/O classes work with
|
||||||
data.
|
:class:`str` data.
|
||||||
|
|
||||||
Note that calling any method (even inquiries) on a closed stream is
|
Note that calling any method (even inquiries) on a closed stream is
|
||||||
undefined. Implementations may raise :exc:`IOError` in this case.
|
undefined. Implementations may raise :exc:`IOError` in this case.
|
||||||
|
@ -197,13 +202,14 @@ I/O Base Classes
|
||||||
IOBase (and its subclasses) support the iterator protocol, meaning that an
|
IOBase (and its subclasses) support the iterator protocol, meaning that an
|
||||||
:class:`IOBase` object can be iterated over yielding the lines in a stream.
|
:class:`IOBase` object can be iterated over yielding the lines in a stream.
|
||||||
|
|
||||||
IOBase also supports the :keyword:`with` statement. In this example, *fp* is
|
IOBase is also a context manager and therefore supports the
|
||||||
closed after the suite of the with statment is complete::
|
:keyword:`with` statement. In this example, *file* is closed after the
|
||||||
|
:keyword:`with` statement's suite is finished---even if an exception occurs::
|
||||||
|
|
||||||
with open('spam.txt', 'r') as fp:
|
with open('spam.txt', 'w') as file:
|
||||||
fp.write('Spam and eggs!')
|
file.write('Spam and eggs!')
|
||||||
|
|
||||||
:class:`IOBase` provides these methods:
|
:class:`IOBase` provides these data attributes and methods:
|
||||||
|
|
||||||
.. method:: close()
|
.. method:: close()
|
||||||
|
|
||||||
|
@ -227,17 +233,18 @@ I/O Base Classes
|
||||||
|
|
||||||
.. method:: isatty()
|
.. method:: isatty()
|
||||||
|
|
||||||
Tell if a stream is interactive (connected to a terminal/tty device).
|
Returns ``True`` if the stream is interactive (i.e., connected to
|
||||||
|
a terminal/tty device).
|
||||||
|
|
||||||
.. method:: readable()
|
.. method:: readable()
|
||||||
|
|
||||||
Tell if a stream can be read from. If False, :meth:`read` will raise
|
Returns ``True`` if the stream can be read from. If False,
|
||||||
:exc:`IOError`.
|
:meth:`read` will raise :exc:`IOError`.
|
||||||
|
|
||||||
.. method:: readline([limit])
|
.. method:: readline([limit])
|
||||||
|
|
||||||
Read and return a line from the stream. If *limit* is specified, at most
|
Reads and returns one line from the stream. If *limit* is
|
||||||
*limit* bytes will be read.
|
specified, at most *limit* bytes will be read.
|
||||||
|
|
||||||
The line terminator is always ``b'\n'`` for binary files; for text files,
|
The line terminator is always ``b'\n'`` for binary files; for text files,
|
||||||
the *newlines* argument to :func:`open` can be used to select the line
|
the *newlines* argument to :func:`open` can be used to select the line
|
||||||
|
@ -245,45 +252,47 @@ I/O Base Classes
|
||||||
|
|
||||||
.. method:: readlines([hint])
|
.. method:: readlines([hint])
|
||||||
|
|
||||||
Return a list of lines from the stream. *hint* can be specified to
|
Returns 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
|
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*.
|
size (in bytes/characters) of all lines so far exceeds *hint*.
|
||||||
|
|
||||||
.. method:: seek(offset[, whence])
|
.. method:: seek(offset[, whence])
|
||||||
|
|
||||||
Change the stream position to byte offset *offset*. *offset* is
|
Change the stream position to the given byte *offset*. *offset* is
|
||||||
interpreted relative to the position indicated by *whence*. Values for
|
interpreted relative to the position indicated by *whence*. Values for
|
||||||
*whence* are:
|
*whence* are:
|
||||||
|
|
||||||
* ``0`` -- start of stream (the default); *pos* should be zero or positive
|
* ``0`` -- start of the stream (the default); *offset* should be zero or positive
|
||||||
* ``1`` -- current stream position; *pos* may be negative
|
* ``1`` -- current stream position; *offset* may be negative
|
||||||
* ``2`` -- end of stream; *pos* is usually negative
|
* ``2`` -- end of the stream; *offset* is usually negative
|
||||||
|
|
||||||
Return the new absolute position.
|
Returns the new absolute position.
|
||||||
|
|
||||||
.. method:: seekable()
|
.. method:: seekable()
|
||||||
|
|
||||||
Tell if a stream supports random IO access. If ``False``, :meth:`seek`,
|
Returns ``True`` if the stream supports random access. If
|
||||||
:meth:`tell` and :meth:`truncate` will raise :exc:`IOError`.
|
``False``, :meth:`seek`, :meth:`tell` and :meth:`truncate` will
|
||||||
|
raise :exc:`IOError`.
|
||||||
|
|
||||||
.. method:: tell()
|
.. method:: tell()
|
||||||
|
|
||||||
Return an integer indicating the current stream position.
|
Returns the current stream position.
|
||||||
|
|
||||||
.. method:: truncate([pos])
|
.. method:: truncate([size])
|
||||||
|
|
||||||
Truncate the file to at most *pos* bytes. *pos* defaults to the current
|
Truncates the file to at most *size* bytes. *size* defaults to the current
|
||||||
file position, as returned by :meth:`tell`.
|
file position, as returned by :meth:`tell`.
|
||||||
|
|
||||||
.. method:: writable()
|
.. method:: writable()
|
||||||
|
|
||||||
Tell if a stream supports writing. If ``False``, :meth:`write` and
|
Returns ``True`` if the stream supports writing. If ``False``,
|
||||||
:meth:`truncate` will raise :exc:`IOError`.
|
:meth:`write` and :meth:`truncate` will raise :exc:`IOError`.
|
||||||
|
|
||||||
.. method:: writelines(lines)
|
.. method:: writelines(lines)
|
||||||
|
|
||||||
Write a list of lines to the stream. The lines will not be altered; they
|
Writes a list of lines to the stream. Line separators are not
|
||||||
must contain line separators.
|
added, so it is usual for each of the lines provided to have a
|
||||||
|
line separator at the end.
|
||||||
|
|
||||||
|
|
||||||
.. class:: RawIOBase
|
.. class:: RawIOBase
|
||||||
|
@ -291,30 +300,32 @@ I/O Base Classes
|
||||||
Base class for raw binary I/O. It inherits :class:`IOBase`. There is no
|
Base class for raw binary I/O. It inherits :class:`IOBase`. There is no
|
||||||
public constructor.
|
public constructor.
|
||||||
|
|
||||||
RawIOBase provides or overrides these methods in addition to those from
|
In addition to the attributes and methods from :class:`IOBase`,
|
||||||
:class:`IOBase`:
|
RawIOBase provides the following methods:
|
||||||
|
|
||||||
.. method:: read([n])
|
.. method:: read([n])
|
||||||
|
|
||||||
Read and return all bytes from the stream until EOF, or if *n* is
|
Reads and returns all the bytes from the stream until EOF, or if *n* is
|
||||||
specified, up to *n* bytes. An empty bytes object is returned on EOF;
|
specified, up to *n* bytes. An empty bytes object is returned on EOF;
|
||||||
``None`` is returned if the object is set not to block and has no data to
|
``None`` is returned if the object is set not to block and has no data to
|
||||||
read.
|
read.
|
||||||
|
|
||||||
.. method:: readall()
|
.. method:: readall()
|
||||||
|
|
||||||
Read and return all bytes from the stream until EOF, using multiple calls
|
Reads and returns all the bytes from the stream until EOF, using
|
||||||
to the stream.
|
multiple calls to the stream if necessary.
|
||||||
|
|
||||||
.. method:: readinto(b)
|
.. method:: readinto(b)
|
||||||
|
|
||||||
Read up to len(b) bytes into bytearray *b* and return the number of bytes
|
Reads up to len(b) bytes into bytearray *b* and returns the number
|
||||||
read.
|
of bytes read.
|
||||||
|
|
||||||
.. method:: write(b)
|
.. method:: write(b)
|
||||||
|
|
||||||
Write the given bytes, *b*, to the underlying raw stream and return the
|
Writes the given bytes or bytearray object, *b*, to the underlying
|
||||||
number of bytes written (never less than ``len(b)``).
|
raw stream and returns the number of bytes written (never less
|
||||||
|
than ``len(b)``, since if the write fails an :exc:`IOError` will
|
||||||
|
be raised).
|
||||||
|
|
||||||
|
|
||||||
Raw File I/O
|
Raw File I/O
|
||||||
|
@ -322,7 +333,7 @@ Raw File I/O
|
||||||
|
|
||||||
.. class:: FileIO(name[, mode])
|
.. class:: FileIO(name[, mode])
|
||||||
|
|
||||||
:class:`FileIO` represents an OS file containing bytes data. It implements
|
:class:`FileIO` represents a file containing bytes data. It implements
|
||||||
the :class:`RawIOBase` interface (and therefore the :class:`IOBase`
|
the :class:`RawIOBase` interface (and therefore the :class:`IOBase`
|
||||||
interface, too).
|
interface, too).
|
||||||
|
|
||||||
|
@ -331,8 +342,9 @@ Raw File I/O
|
||||||
writing or appending; it will be truncated when opened for writing. Add a
|
writing or appending; it will be truncated when opened for writing. Add a
|
||||||
``'+'`` to the mode to allow simultaneous reading and writing.
|
``'+'`` to the mode to allow simultaneous reading and writing.
|
||||||
|
|
||||||
:class:`FileIO` provides or overrides these methods in addition to those from
|
In addition to the attributes and methods from :class:`IOBase` and
|
||||||
:class:`RawIOBase` and :class:`IOBase`:
|
:class:`RawIOBase`, :class:`FileIO` provides the following data
|
||||||
|
attributes and methods:
|
||||||
|
|
||||||
.. attribute:: mode
|
.. attribute:: mode
|
||||||
|
|
||||||
|
@ -344,24 +356,27 @@ Raw File I/O
|
||||||
|
|
||||||
.. method:: read([n])
|
.. method:: read([n])
|
||||||
|
|
||||||
Read and return bytes at most *n* bytes. Only one system call is made, so
|
Reads and returns at most *n* bytes. Only one system call is made, so
|
||||||
less data than requested may be returned. In non-blocking mode, ``None``
|
it is possible that less data than was requested is returned. Call
|
||||||
is returned when no data is available.
|
: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()
|
.. method:: readall()
|
||||||
|
|
||||||
Read and return as bytes all the data from the file. As much as
|
Reads and returns the entire file's contents in a single bytes
|
||||||
immediately available is returned in non-blocking mode. If the EOF has
|
object. As much as immediately available is returned in
|
||||||
been reached, ``b''`` is returned.
|
non-blocking mode. If the EOF has been reached, ``b''`` is
|
||||||
|
returned.
|
||||||
.. method:: readinto(bytearray)
|
|
||||||
|
|
||||||
This method should not be used on :class:`FileIO` objects.
|
|
||||||
|
|
||||||
.. method:: write(b)
|
.. method:: write(b)
|
||||||
|
|
||||||
Write the bytes *b* to the file, and return the number actually written.
|
Write the bytes or bytearray object, *b*, to the file, and return
|
||||||
Only one system call is made, so not all of the data may be written.
|
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
|
Buffered Streams
|
||||||
|
@ -390,7 +405,7 @@ Buffered Streams
|
||||||
|
|
||||||
.. method:: read([n])
|
.. method:: read([n])
|
||||||
|
|
||||||
Read and return up to *n* bytes. If the argument is omitted, ``None``, or
|
Reads and returns up to *n* bytes. If the argument is omitted, ``None``, or
|
||||||
negative, data is read and returned until EOF is reached. An empty bytes
|
negative, data is read and returned until EOF is reached. An empty bytes
|
||||||
object is returned if the stream is already at EOF.
|
object is returned if the stream is already at EOF.
|
||||||
|
|
||||||
|
@ -405,7 +420,7 @@ Buffered Streams
|
||||||
|
|
||||||
.. method:: readinto(b)
|
.. method:: readinto(b)
|
||||||
|
|
||||||
Read up to len(b) bytes into bytearray *b* and return the number of bytes
|
Reads up to len(b) bytes into bytearray *b* and returns the number of bytes
|
||||||
read.
|
read.
|
||||||
|
|
||||||
Like :meth:`read`, multiple reads may be issued to the underlying raw
|
Like :meth:`read`, multiple reads may be issued to the underlying raw
|
||||||
|
@ -416,8 +431,10 @@ Buffered Streams
|
||||||
|
|
||||||
.. method:: write(b)
|
.. method:: write(b)
|
||||||
|
|
||||||
Write the given bytes, *b*, to the underlying raw stream and return the
|
Writes the given bytes or bytearray object, *b*, to the underlying
|
||||||
number of bytes written (never less than ``len(b)``).
|
raw stream and returns the number of bytes written (never less than
|
||||||
|
``len(b)``, since if the write fails an :exc:`IOError` will
|
||||||
|
be raised).
|
||||||
|
|
||||||
A :exc:`BlockingIOError` is raised if the buffer is full, and the
|
A :exc:`BlockingIOError` is raised if the buffer is full, and the
|
||||||
underlying raw stream cannot accept more data at the moment.
|
underlying raw stream cannot accept more data at the moment.
|
||||||
|
@ -435,15 +452,16 @@ Buffered Streams
|
||||||
|
|
||||||
.. method:: getvalue()
|
.. method:: getvalue()
|
||||||
|
|
||||||
Return the bytes value of the buffer.
|
Returns a bytes object containing the entire contents of the
|
||||||
|
buffer.
|
||||||
|
|
||||||
.. method:: read1()
|
.. method:: read1()
|
||||||
|
|
||||||
In :class:`BytesIO`, this is the same as :meth:`read`.
|
In :class:`BytesIO`, this is the same as :meth:`read`.
|
||||||
|
|
||||||
.. method:: truncate([pos])
|
.. method:: truncate([size])
|
||||||
|
|
||||||
Truncate the file to at most *pos* bytes. *pos* defaults to the current
|
Truncates the buffer to at most *size* bytes. *size* defaults to the current
|
||||||
stream position, as returned by :meth:`tell`.
|
stream position, as returned by :meth:`tell`.
|
||||||
|
|
||||||
|
|
||||||
|
@ -461,19 +479,20 @@ Buffered Streams
|
||||||
|
|
||||||
.. method:: peek([n])
|
.. method:: peek([n])
|
||||||
|
|
||||||
Return bytes from a buffer without advancing the position. The argument
|
Returns 1 (or *n* if specified) bytes from a buffer without
|
||||||
indicates a desired minimal number of bytes; only one read on the raw
|
advancing the position. Only a single read on the raw stream is done to
|
||||||
stream is done to satisfy it. More than the buffer's size is never
|
satisfy the call. The number of bytes returned may be less than
|
||||||
returned.
|
requested since at most all the buffer's bytes from the current
|
||||||
|
position to the end are returned.
|
||||||
|
|
||||||
.. method:: read([n])
|
.. method:: read([n])
|
||||||
|
|
||||||
Read and return *n* bytes, or if *n* is not given or negative, until EOF
|
Reads and returns *n* bytes, or if *n* is not given or negative, until EOF
|
||||||
or if the read call would block in non-blocking mode.
|
or if the read call would block in non-blocking mode.
|
||||||
|
|
||||||
.. method:: read1(n)
|
.. method:: read1(n)
|
||||||
|
|
||||||
Read and return up to *n* bytes with only one call on the raw stream. If
|
Reads and returns up to *n* bytes with only one call on the raw stream. If
|
||||||
at least one byte is buffered, only buffered bytes are returned.
|
at least one byte is buffered, only buffered bytes are returned.
|
||||||
Otherwise, one raw stream read call is made.
|
Otherwise, one raw stream read call is made.
|
||||||
|
|
||||||
|
@ -494,20 +513,21 @@ Buffered Streams
|
||||||
.. method:: flush()
|
.. method:: flush()
|
||||||
|
|
||||||
Force bytes held in the buffer into the raw stream. A
|
Force bytes held in the buffer into the raw stream. A
|
||||||
:exc:`BlockingIOError` is be raised if the raw stream blocks.
|
:exc:`BlockingIOError` should be raised if the raw stream blocks.
|
||||||
|
|
||||||
.. method:: write(b)
|
.. method:: write(b)
|
||||||
|
|
||||||
Write bytes *b* onto the raw stream and return the number written. A
|
Writes the bytes or bytearray object, *b*, onto the raw stream and
|
||||||
:exc:`BlockingIOError` is raised when the raw stream blocks.
|
returns the number of bytes written. A :exc:`BlockingIOError` is
|
||||||
|
raised when the raw stream blocks.
|
||||||
|
|
||||||
|
|
||||||
.. class:: BufferedRWPair(reader, writer[, buffer_size[, max_buffer_size]])
|
.. class:: BufferedRWPair(reader, writer[, buffer_size[, max_buffer_size]])
|
||||||
|
|
||||||
A buffered writer and reader object together for a raw stream that can be
|
A combined buffered writer and reader object for a raw stream that can be
|
||||||
written and read from. It has and supports both :meth:`read`, :meth:`write`,
|
written to and read from. It has and supports both :meth:`read`, :meth:`write`,
|
||||||
and their variants. This is useful for such applications such as sockets and
|
and their variants. This is useful for sockets and two-way pipes.
|
||||||
two-way pipes. It inherits :class:`BufferedIOBase`.
|
It inherits :class:`BufferedIOBase`.
|
||||||
|
|
||||||
*reader* and *writer* are :class:`RawIOBase` objects that are readable and
|
*reader* and *writer* are :class:`RawIOBase` objects that are readable and
|
||||||
writeable respectively. If the *buffer_size* is omitted it defaults to
|
writeable respectively. If the *buffer_size* is omitted it defaults to
|
||||||
|
@ -541,33 +561,33 @@ Text I/O
|
||||||
Python's character strings are immutable. It inherits :class:`IOBase`.
|
Python's character strings are immutable. It inherits :class:`IOBase`.
|
||||||
There is no public constructor.
|
There is no public constructor.
|
||||||
|
|
||||||
:class:`TextIOBase` provides or overrides these methods in addition to those
|
:class:`TextIOBase` provides or overrides these data attributes and
|
||||||
from :class:`IOBase`:
|
methods in addition to those from :class:`IOBase`:
|
||||||
|
|
||||||
.. attribute:: encoding
|
.. attribute:: encoding
|
||||||
|
|
||||||
Return the name of the encoding used to decode the stream's bytes into
|
The name of the encoding used to decode the stream's bytes into
|
||||||
strings, and to encode strings into bytes.
|
strings, and to encode strings into bytes.
|
||||||
|
|
||||||
.. attribute:: newlines
|
.. attribute:: newlines
|
||||||
|
|
||||||
Return a string, tuple of strings, or ``None`` indicating the newlines
|
A string, a tuple of strings, or ``None``, indicating the newlines
|
||||||
translated so far.
|
translated so far.
|
||||||
|
|
||||||
.. method:: read(n)
|
.. method:: read(n)
|
||||||
|
|
||||||
Read and return at most *n* characters from the stream. If *n* is
|
Reads and returns at most *n* characters from the stream as a
|
||||||
negative or ``None``, read to EOF.
|
single :class:`str`. If *n* is negative or ``None``, reads to EOF.
|
||||||
|
|
||||||
.. method:: readline()
|
.. method:: readline()
|
||||||
|
|
||||||
Read until newline or EOF and return. If the stream is already at EOF, an
|
Reads until newline or EOF and returns a single :class:`str`. If
|
||||||
empty stream is returned.
|
the stream is already at EOF, an empty string is returned.
|
||||||
|
|
||||||
.. method:: write(s)
|
.. method:: write(s)
|
||||||
|
|
||||||
Write string *s* to the stream and return the number of characters
|
Writes the string *s* to the stream and returns the number of
|
||||||
written.
|
characters written.
|
||||||
|
|
||||||
|
|
||||||
.. class:: TextIOWrapper(buffer[, encoding[, errors[, newline[, line_buffering]]]])
|
.. class:: TextIOWrapper(buffer[, encoding[, errors[, newline[, line_buffering]]]])
|
||||||
|
@ -601,7 +621,7 @@ Text I/O
|
||||||
If *line_buffering* is ``True``, :meth:`flush` is implied when a call to
|
If *line_buffering* is ``True``, :meth:`flush` is implied when a call to
|
||||||
write contains a newline character.
|
write contains a newline character.
|
||||||
|
|
||||||
:class:`TextIOWrapper` provides these methods in addition to those of
|
:class:`TextIOWrapper` provides these data attributes in addition to those of
|
||||||
:class:`TextIOBase` and its parents:
|
:class:`TextIOBase` and its parents:
|
||||||
|
|
||||||
.. attribute:: errors
|
.. attribute:: errors
|
||||||
|
@ -621,12 +641,12 @@ Text I/O
|
||||||
and newline setting. See :class:`TextIOWrapper`\'s constructor for more
|
and newline setting. See :class:`TextIOWrapper`\'s constructor for more
|
||||||
information.
|
information.
|
||||||
|
|
||||||
:class:`StringIO` provides these methods in addition to those from
|
:class:`StringIO` provides this method in addition to those from
|
||||||
:class:`TextIOWrapper` and its parents:
|
:class:`TextIOWrapper` and its parents:
|
||||||
|
|
||||||
.. method:: getvalue()
|
.. method:: getvalue()
|
||||||
|
|
||||||
Return a str representation of the contents of the internal buffer.
|
Returns a :class:`str` containing the entire contents of the buffer.
|
||||||
|
|
||||||
|
|
||||||
.. class:: IncrementalNewlineDecoder
|
.. class:: IncrementalNewlineDecoder
|
||||||
|
|
Loading…
Reference in New Issue