[Python-checkins] r62452 - python/trunk/Doc/library/io.rst

Tue Apr 22 04:16:03 CEST 2008

Author: benjamin.peterson
Date: Tue Apr 22 04:16:03 2008
New Revision: 62452
Log:
Various io doc updates
Modified:
 python/trunk/Doc/library/io.rst
Modified: python/trunk/Doc/library/io.rst
==============================================================================

--- python/trunk/Doc/library/io.rst	(original)
+++ python/trunk/Doc/library/io.rst	Tue Apr 22 04:16:03 2008
@@ -223,7 +223,7 @@
 
 .. 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.
 
@@ -234,18 +234,18 @@
 
 .. 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
@@ -253,9 +253,9 @@
 
 .. 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])
 
@@ -267,33 +267,32 @@
 * ``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
@@ -306,27 +305,26 @@
 
 .. 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
@@ -353,22 +351,21 @@
 
 .. 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)
 
@@ -406,7 +403,7 @@
 
 .. 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.
 
@@ -421,7 +418,7 @@
 
 .. 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
@@ -432,10 +429,9 @@
 
 .. 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.
@@ -453,8 +449,7 @@
 
 .. method:: getvalue()
 
- Returns a bytes object containing the entire contents of the
- buffer.
+ Return ``bytes`` containing the entire contents of the buffer.
 
 .. method:: read1()
 
@@ -462,8 +457,8 @@
 
 .. 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])
@@ -480,20 +475,20 @@
 
 .. 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.
 
@@ -518,9 +513,9 @@
 
 .. 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]])
@@ -577,18 +572,18 @@
 
 .. 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]]]])
@@ -647,7 +642,7 @@
 
 .. 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
