.. 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.
.. 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
.. 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])
* ``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
.. 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
.. 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)
.. 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.
.. 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
.. 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.
.. method:: getvalue()
- Returns a bytes object containing the entire contents of the
- buffer.
+ Return ``bytes`` containing the entire contents of the buffer.
.. method:: read1()
.. 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])
.. 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.
.. 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]])
.. 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]]]])
.. 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
projects / python / commitdiff