From e6d5f30d1fd1de012ab0a6c1dd1580740682f0da Mon Sep 17 00:00:00 2001 From: Mark Summerfield Date: Mon, 21 Apr 2008 10:29:45 +0000 Subject: [PATCH] A lot of small detailed revisions to the io module's doc. --- Doc/library/io.rst | 254 ++++++++++++++++++++++++--------------------- 1 file changed, 137 insertions(+), 117 deletions(-) diff --git a/Doc/library/io.rst b/Doc/library/io.rst index 6280adc14e3..d0f82a372de 100644 --- a/Doc/library/io.rst +++ b/Doc/library/io.rst @@ -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 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:`RawIOBase`). Its subclasses, :class:`BufferedWriter`, :class:`BufferedReader`, and :class:`BufferedRWPair` buffer streams that are -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. +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. -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. +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. Argument names are not part of the specification, and only the arguments of :func:`open` are intended to be used as keyword arguments. @@ -51,10 +54,10 @@ Module Interface :exc:`IOError` is raised. *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 - descriptor of the file to be wrapped. (If a file descriptor is given, it is - closed when the returned I/O object is closed, unless *closefd* is set to - ``False``.) + 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``.) *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. @@ -74,8 +77,8 @@ Module Interface ``'b'`` binary mode ``'t'`` text mode (default) ``'+'`` open a disk file for updating (reading and writing) - ``'U'`` universal newline mode (for backwards compatibility; unneeded - for new code) + ``'U'`` universal newline mode (for backwards compatibility; should + not be used in new code) ========= =============================================================== 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 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 - 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 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. 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. *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 given string. - If *closefd* is ``False``, the underlying file descriptor will be kept open - when the file is closed. This does not work when a file name is given and - must be ``True`` in that case. + 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). - :func:`open` returns a file object whose type depends on the mode, and - through which the standard file operations such as reading and writing are - performed. When :func:`open` is used to open a file in a text mode (``'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`. + 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 + (``'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`. 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 - a text mode, and for bytes a :class:`BytesIO` can be used like a file opened - in a binary mode. + a text mode, and for bytearrays a :class:`BytesIO` can be used like a + file opened in a binary mode. .. exception:: BlockingIOError @@ -176,9 +180,10 @@ I/O Base Classes The abstract base class for all I/O classes, acting on streams of bytes. There is no public constructor. - This class provides dummy implementations for many methods that derived - classes can override selectively; the default implementations represent a - file that cannot be read, written or seeked. + 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. Even though :class:`IOBase` does not declare :meth:`read`, :meth:`readinto`, 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 :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. + (such as :class:`readinto`) required. Text I/O classes work with + :class:`str` data. Note that calling any method (even inquiries) on a closed stream is 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 :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 - closed after the suite of the with statment is complete:: + 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:: - with open('spam.txt', 'r') as fp: - fp.write('Spam and eggs!') + with open('spam.txt', 'w') as file: + file.write('Spam and eggs!') - :class:`IOBase` provides these methods: + :class:`IOBase` provides these data attributes and methods: .. method:: close() @@ -227,17 +233,18 @@ I/O Base Classes .. 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() - Tell if a stream can be read from. If False, :meth:`read` will raise - :exc:`IOError`. + Returns ``True`` if the stream can be read from. If False, + :meth:`read` will raise :exc:`IOError`. .. method:: readline([limit]) - Read and return a line from the stream. If *limit* is specified, at most - *limit* bytes will be read. + Reads and returns one 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 @@ -245,45 +252,47 @@ I/O Base Classes .. 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 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 + Change the stream position to the given byte *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 + * ``0`` -- start of the stream (the default); *offset* should be zero or positive + * ``1`` -- current stream position; *offset* may be negative + * ``2`` -- end of the stream; *offset* is usually negative - Return the new absolute position. + Returns the new absolute position. .. method:: seekable() - Tell if a stream supports random IO access. If ``False``, :meth:`seek`, - :meth:`tell` and :meth:`truncate` will raise :exc:`IOError`. + Returns ``True`` if the stream supports random access. If + ``False``, :meth:`seek`, :meth:`tell` and :meth:`truncate` will + raise :exc:`IOError`. .. 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`. .. method:: writable() - Tell if a stream supports writing. If ``False``, :meth:`write` and - :meth:`truncate` will raise :exc:`IOError`. + Returns ``True`` if the stream supports writing. If ``False``, + :meth:`write` and :meth:`truncate` will raise :exc:`IOError`. .. method:: writelines(lines) - Write a list of lines to the stream. The lines will not be altered; they - must contain line separators. + Writes 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. .. class:: RawIOBase @@ -291,30 +300,32 @@ I/O Base Classes Base class for raw binary I/O. It inherits :class:`IOBase`. There is no public constructor. - RawIOBase provides or overrides these methods in addition to those from - :class:`IOBase`: + In addition to the attributes and methods from :class:`IOBase`, + RawIOBase provides the following methods: .. 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; ``None`` is returned if the object is set not to block and has no data to read. .. method:: readall() - Read and return all bytes from the stream until EOF, using multiple calls - to the stream. + Reads and returns all the bytes from the stream until EOF, using + multiple calls to the stream if necessary. .. method:: readinto(b) - Read up to len(b) bytes into bytearray *b* and return the number of bytes - read. + Reads up to len(b) bytes into bytearray *b* and returns 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)``). + Writes the given bytes or bytearray object, *b*, to the underlying + 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 @@ -322,7 +333,7 @@ Raw File I/O .. 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` interface, too). @@ -331,8 +342,9 @@ Raw File I/O writing or appending; it will be truncated when opened for writing. Add a ``'+'`` to the mode to allow simultaneous reading and writing. - :class:`FileIO` provides or overrides these methods in addition to those from - :class:`RawIOBase` and :class:`IOBase`: + In addition to the attributes and methods from :class:`IOBase` and + :class:`RawIOBase`, :class:`FileIO` provides the following data + attributes and methods: .. attribute:: mode @@ -344,24 +356,27 @@ Raw File I/O .. method:: read([n]) - Read and return bytes at most *n* bytes. Only one system call is made, so - less data than requested may be returned. In non-blocking mode, ``None`` - is returned when no data is available. + Reads and returns at most *n* bytes. Only one system call is made, so + it is possible that less data than was requested is returned. Call + :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 as bytes all the data from the file. As much as - immediately available is returned in 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. + Reads and returns 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 *b* to the file, and return the number actually written. - Only one system call is made, so not all of the data may be written. + 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 @@ -390,7 +405,7 @@ Buffered Streams .. 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 object is returned if the stream is already at EOF. @@ -405,7 +420,7 @@ Buffered Streams .. 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. Like :meth:`read`, multiple reads may be issued to the underlying raw @@ -416,8 +431,10 @@ Buffered Streams .. 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)``). + Writes the given bytes or bytearray object, *b*, to the underlying + 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 underlying raw stream cannot accept more data at the moment. @@ -435,15 +452,16 @@ Buffered Streams .. method:: getvalue() - Return the bytes value of the buffer. + Returns a bytes object containing the entire contents of the + buffer. .. method:: read1() 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`. @@ -461,19 +479,20 @@ Buffered Streams .. method:: peek([n]) - Return bytes from a buffer without advancing the position. The argument - indicates a desired minimal number of bytes; only one read on the raw - stream is done to satisfy it. More than the buffer's size is never - returned. + Returns 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. .. 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. .. 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. Otherwise, one raw stream read call is made. @@ -494,20 +513,21 @@ Buffered Streams .. method:: flush() 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) - Write bytes *b* onto the raw stream and return the number written. A - :exc:`BlockingIOError` is raised when the raw stream blocks. + Writes the bytes or bytearray object, *b*, onto the raw stream and + 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]]) - 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`, - and their variants. This is useful for such applications such as sockets and - two-way pipes. It inherits :class:`BufferedIOBase`. + 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`. *reader* and *writer* are :class:`RawIOBase` objects that are readable and 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`. There is no public constructor. - :class:`TextIOBase` provides or overrides these methods in addition to those - from :class:`IOBase`: + :class:`TextIOBase` provides or overrides these data attributes and + methods in addition to those from :class:`IOBase`: .. 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. .. 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. .. method:: read(n) - Read and return at most *n* characters from the stream. If *n* is - negative or ``None``, read to EOF. + Reads and returns at most *n* characters from the stream as a + single :class:`str`. If *n* is negative or ``None``, reads to EOF. .. method:: readline() - Read until newline or EOF and return. If the stream is already at EOF, an - empty stream is returned. + Reads until newline or EOF and returns a single :class:`str`. If + the stream is already at EOF, an empty string is returned. .. method:: write(s) - Write string *s* to the stream and return the number of characters - written. + Writes the string *s* to the stream and returns the number of + characters written. .. 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 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: .. attribute:: errors @@ -621,12 +641,12 @@ Text I/O and newline setting. See :class:`TextIOWrapper`\'s constructor for more 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: .. 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