diff options
Diffstat (limited to 'Doc/library/io.rst')
| -rw-r--r-- | Doc/library/io.rst | 143 |
1 files changed, 71 insertions, 72 deletions
diff --git a/Doc/library/io.rst b/Doc/library/io.rst index 224738f..a34c09a 100644 --- a/Doc/library/io.rst +++ b/Doc/library/io.rst @@ -27,11 +27,14 @@ readable, writable, and both respectively. :class:`BufferedRandom` provides a buffered interface to random access 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 the encoding and decoding of streams into text. :class:`TextIOWrapper`, which extends it, is a buffered text interface to a buffered raw stream (:class:`BufferedIOBase`). Finally, :class:`StringIO` is a in-memory stream for text. +Argument names are not part of the specification, and only the arguments of +:func:`open()` are intended to be used as keyword arguments. + Module Interface ---------------- @@ -39,8 +42,8 @@ Module Interface .. data:: DEFAULT_BUFFER_SIZE An int containing the default buffer size used by the module's buffered I/O - classes. :func:`open` uses the file's blksize (as obtained by os.stat) if - possible. + classes. :func:`open()` uses the file's blksize (as obtained by + :func:`os.stat`) if possible. .. function:: open(file[, mode[, buffering[, encoding[, errors[, newline[, closefd=True]]]]]]) @@ -79,18 +82,18 @@ Module Interface 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 (appending ``'b'`` to the *mode* argument) return contents as - ``bytes`` 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 strings, the bytes having been first decoded - using a platform-dependent encoding or using the specified *encoding* - if given. + Python distinguishes between files opened in binary and text modes, even when + the underlying operating system doesn't. Files opened in binary mode + (appending ``'b'`` to the *mode* argument) return contents as ``bytes`` + 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 + 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. + 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 @@ -176,18 +179,18 @@ I/O Base Classes file that cannot be read, written or seeked. Even though :class:`IOBase` does not declare :meth:`read`, :meth:`readinto`, - :meth:`seek`, 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. + 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 (such as :class:`readinto`) needed. Text I/O classes work with :class:`str` data. - Note that calling any method (even inquiries) on a closed file is undefined. - Implementations may raise :exc:`IOError` in this case. + 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. @@ -212,13 +215,13 @@ I/O Base Classes .. method:: fileno() Return the underlying file descriptor (an integer) of the stream, if it - exists. Raises :exc:`IOError` if the IO object does not use a file + exists. An :exc:`IOError` is raised if the IO object does not use a file descriptor. .. method:: flush() - Flush the write buffers of the stream if applicable. This is a no-op for - read-only and non-blocking streams. + Flush the write buffers of the stream if applicable. This is not + implemented for read-only and non-blocking streams. .. method:: isatty() @@ -234,8 +237,8 @@ I/O Base Classes Read and return a line from the stream. If *limit* is specified, at most *limit* bytes will be read. - 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 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 terminator(s) recognized. .. method:: readlines([hint]) @@ -244,6 +247,18 @@ I/O Base Classes 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*. + .. method:: seek(offset[, whence]) + + Change the stream position to byte offset *offset*. *offset* is + interpreted relative to the position indicated by *whence*. Values for + *whence* are: + + * ``0`` -- start of stream (the default); *pos* should be zero or positive + * ``1`` -- current stream position; *pos* may be negative + * ``2`` -- end of stream; *pos* is usually negative + + Return the new absolute position. + .. method:: seekable() Tell if a stream supports random IO access. If ``False``, :meth:`seek`, @@ -253,6 +268,11 @@ I/O Base Classes Return an integer indicating the current stream position. + .. method:: truncate([pos]) + + Truncate the file to at most *pos* bytes. *pos* defaults to the current + file position, as returned by :meth:`tell`. + .. method:: writable() Tell if a stream supports writing. If ``False``, :meth:`write` and @@ -281,7 +301,18 @@ I/O Base Classes .. method:: readall() - Read and return all bytes from the stream until EOF. + Read and return all bytes from the stream until EOF, using multiple calls + to the stream. + + .. method:: readinto(b) + + Read up to len(b) bytes into bytearray *b* and return the number of bytes + read. + + .. method:: write(b) + + Write the given bytes, *b*, to the underlying raw stream and return the + number of bytes written (never less than ``len(b)``). Raw File I/O @@ -325,22 +356,6 @@ Raw File I/O This method should not be used on :class:`FileIO` objects. - .. method:: seek(offset, [whence]) - - Change the stream position to byte offset *pos*. *pos* is interpreted - relative to the position indicated by *whence*. Values for *whence* are: - - * ``0`` -- start of stream (the default); *pos* should be zero or positive - * ``1`` -- current stream position; *pos* may be negative - * ``2`` -- end of stream; *pos* is usually negative - - Return the new absolute position. - - .. method:: truncate([pos]) - - Truncate the file to at most *pos* bytes. *pos* defaults to the current - file position, as returned by :meth:`tell`. - .. method:: write(b) Write the bytes *b* to the file, and return the number actually written. @@ -397,21 +412,10 @@ Buffered Streams A :exc:`BlockingIOError` is raised if the underlying raw stream has no data at the moment. - .. method:: seek(pos[, whence]) - - Change the stream position to byte offset *pos*. *pos* is interpreted - relative to the position indicated by *whence*. Values for *whence* are: - - * ``0`` -- start of stream (the default); *pos* should be zero or positive - * ``1`` -- current stream position; *pos* may be negative - * ``2`` -- end of stream; *pos* is usually negative - - Return the new absolute position. - .. method:: write(b) - Write the given bytes to the underlying raw stream and return the number - of bytes written (never less than ``len(b)``). + Write the given bytes, *b*, to the underlying raw stream and return the + number of bytes written (never less than ``len(b)``). A :exc:`BlockingIOError` is raised if the buffer is full, and the underlying raw stream cannot accept more data at the moment. @@ -433,17 +437,17 @@ Buffered Streams .. 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]) Truncate the file to at most *pos* bytes. *pos* defaults to the current - stream position, as returned by :meth:`tell`. + stream position, as returned by :meth:`tell()`. -.. class:: BufferedReader(raw, [buffer_size]) +.. class:: BufferedReader(raw[, buffer_size]) - A buffer for a readable sequential RawIO object. It inherits + A buffer for a readable, sequential :class:`BaseRawIO` object. It inherits :class:`BufferedIOBase`. The constructor creates a :class:`BufferedReader` for the given readable @@ -472,7 +476,7 @@ Buffered Streams Otherwise, one raw stream read call is made. -.. class:: BufferedWriter(raw, [buffer_size, [max_buffer_size]]) +.. class:: BufferedWriter(raw[, buffer_size[, max_buffer_size]]) A buffer for a writeable sequential RawIO object. It inherits :class:`BufferedIOBase`. @@ -496,7 +500,7 @@ Buffered Streams :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 written and read from. It has and supports both :meth:`read`, :meth:`write`, @@ -511,12 +515,12 @@ Buffered Streams :class:`BufferedRWPair` implements all of :class:`BufferedIOBase`\'s methods. -.. class:: BufferedRandom(raw, [buffer_size, [max_buffer_size]]) +.. 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 + 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. @@ -558,11 +562,6 @@ Text I/O Read until newline or EOF and return. If the stream is already at EOF, an empty stream is returned. - .. method:: truncate([pos]) - - Truncate size to *pos*. If *pos* is not specified, it is assumed to be the - current position, as returned by :meth:`tell`. - .. method:: write(s) Write string *s* to the stream and return the number of characters @@ -578,7 +577,7 @@ Text I/O encoded with. It defaults to :func:`locale.getpreferredencoding`. *errors* determines the strictness of encoding and decoding (see the errors - argument of :func:`codecs.open`) and defaults to "strict". + argument of :func:`codecs.register`) and defaults to ``'strict'``. *newline* can be ``None``, ``''``, ``'\n'``, ``'\r'``, or ``'\r\n'``. It controls the handling of line endings. If it is ``None``, universal newlines @@ -604,12 +603,12 @@ Text I/O Whether line buffering is enabled. -.. class:: StringIO([initial_value, [encoding, [errors, [newline]]]]) +.. class:: StringIO([initial_value[, encoding[, errors[, newline]]]]) An in-memory stream for text. It in inherits :class:`TextIOWrapper`. Create a new StringIO stream with an inital value, encoding, error handling, - and newline setting. See :class:`TextIOWrapper`'s constructor for more + and newline setting. See :class:`TextIOWrapper`\'s constructor for more information. :class:`StringIO` provides these methods in addition to those from @@ -622,6 +621,6 @@ Text I/O .. class:: IncrementalNewlineDecoder - A helper codec that decodes newlines. It inherits - :class:`codecs.IncrementalDecoder`. + A helper codec that decodes newlines for universal newlines mode. It + inherits :class:`codecs.IncrementalDecoder`. |