diff options
Diffstat (limited to 'Doc/library/io.rst')
| -rw-r--r-- | Doc/library/io.rst | 131 |
1 files changed, 63 insertions, 68 deletions
diff --git a/Doc/library/io.rst b/Doc/library/io.rst index d0f82a3..d80d265 100644 --- a/Doc/library/io.rst +++ b/Doc/library/io.rst @@ -222,7 +222,7 @@ I/O Base Classes .. method:: fileno() - Return the underlying file descriptor (an integer) of the stream, if it + Return the underlying file descriptor (an integer) of the stream if it exists. An :exc:`IOError` is raised if the IO object does not use a file descriptor. @@ -233,18 +233,18 @@ I/O Base Classes .. method:: isatty() - Returns ``True`` if the stream is interactive (i.e., connected to + Return ``True`` if the stream is interactive (i.e., connected to a terminal/tty device). .. method:: readable() - Returns ``True`` if the stream can be read from. If False, - :meth:`read` will raise :exc:`IOError`. + Return ``True`` if the stream can be read from. If False, :meth:`read` + will raise :exc:`IOError`. .. method:: readline([limit]) - Reads and returns one line from the stream. If *limit* is - specified, at most *limit* bytes will be read. + Read and return 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 @@ -252,9 +252,9 @@ I/O Base Classes .. method:: readlines([hint]) - 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*. + Read and return 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]) @@ -266,33 +266,32 @@ I/O Base Classes * ``1`` -- current stream position; *offset* may be negative * ``2`` -- end of the stream; *offset* is usually negative - Returns the new absolute position. + Return the new absolute position. .. method:: seekable() - Returns ``True`` if the stream supports random access. If - ``False``, :meth:`seek`, :meth:`tell` and :meth:`truncate` will - raise :exc:`IOError`. + Return ``True`` if the stream supports random access. If ``False``, + :meth:`seek`, :meth:`tell` and :meth:`truncate` will raise :exc:`IOError`. .. method:: tell() - Returns the current stream position. + Return the current stream position. .. method:: truncate([size]) - Truncates the file to at most *size* bytes. *size* defaults to the current + Truncate the file to at most *size* bytes. *size* defaults to the current file position, as returned by :meth:`tell`. .. method:: writable() - Returns ``True`` if the stream supports writing. If ``False``, + Return ``True`` if the stream supports writing. If ``False``, :meth:`write` and :meth:`truncate` will raise :exc:`IOError`. .. method:: writelines(lines) - 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. + Write 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 @@ -305,27 +304,26 @@ I/O Base Classes .. method:: read([n]) - 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. + 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. .. method:: readall() - Reads and returns all the bytes from the stream until EOF, using - multiple calls to the stream if necessary. + Read and return all the bytes from the stream until EOF, using multiple + calls to the stream if necessary. .. method:: readinto(b) - Reads up to len(b) bytes into bytearray *b* and returns the number - of bytes read. + Read up to len(b) bytes into bytearray *b* and return the number of bytes + read. .. method:: write(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). + 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). Raw File I/O @@ -352,22 +350,21 @@ Raw File I/O .. attribute:: name - The file name. + The file name. This is the file descriptor of the file when no name is + given in the constructor. .. method:: read([n]) - 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.) + 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() - 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. + 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) @@ -405,7 +402,7 @@ Buffered Streams .. method:: read([n]) - Reads and returns up to *n* bytes. If the argument is omitted, ``None``, or + Read and return 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. @@ -420,7 +417,7 @@ Buffered Streams .. method:: readinto(b) - Reads up to len(b) bytes into bytearray *b* and returns the number of bytes + Read up to len(b) bytes into bytearray *b* and return the number of bytes read. Like :meth:`read`, multiple reads may be issued to the underlying raw @@ -431,10 +428,9 @@ Buffered Streams .. method:: write(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). + 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). A :exc:`BlockingIOError` is raised if the buffer is full, and the underlying raw stream cannot accept more data at the moment. @@ -452,8 +448,7 @@ Buffered Streams .. method:: getvalue() - Returns a bytes object containing the entire contents of the - buffer. + Return ``bytes`` containing the entire contents of the buffer. .. method:: read1() @@ -461,8 +456,8 @@ Buffered Streams .. method:: truncate([size]) - Truncates the buffer to at most *size* bytes. *size* defaults to the current - stream position, as returned by :meth:`tell`. + Truncate the buffer to at most *size* bytes. *size* defaults to the + current stream position, as returned by :meth:`tell`. .. class:: BufferedReader(raw[, buffer_size]) @@ -479,20 +474,20 @@ Buffered Streams .. method:: peek([n]) - 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. + Return 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]) - Reads and returns *n* bytes, or if *n* is not given or negative, until EOF + Read and return *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) - Reads and returns up to *n* bytes with only one call on the raw stream. If + Read and return 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. @@ -517,9 +512,9 @@ Buffered Streams .. method:: write(b) - 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. + 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. .. class:: BufferedRWPair(reader, writer[, buffer_size[, max_buffer_size]]) @@ -576,18 +571,18 @@ Text I/O .. method:: read(n) - Reads and returns at most *n* characters from the stream as a - single :class:`str`. If *n* is negative or ``None``, reads to EOF. + Read and return at most *n* characters from the stream as a single + :class:`str`. If *n* is negative or ``None``, reads to EOF. .. method:: readline() - Reads until newline or EOF and returns a single :class:`str`. If - the stream is already at EOF, an empty string is returned. + Read until newline or EOF and return a single ``str``. If the stream is + already at EOF, an empty string is returned. .. method:: write(s) - Writes the string *s* to the stream and returns the number of - characters written. + Write the string *s* to the stream and return the number of characters + written. .. class:: TextIOWrapper(buffer[, encoding[, errors[, newline[, line_buffering]]]]) @@ -646,7 +641,7 @@ Text I/O .. method:: getvalue() - Returns a :class:`str` containing the entire contents of the buffer. + Return a ``str`` containing the entire contents of the buffer. .. class:: IncrementalNewlineDecoder |