Index: Doc/library/allos.rst
===================================================================
--- Doc/library/allos.rst	(revision 62183)
+++ Doc/library/allos.rst	(working copy)
@@ -14,6 +14,7 @@
 .. toctree::
 
    os.rst
+   io.rst
    time.rst
    optparse.rst
    getopt.rst
Index: Doc/library/io.rst
===================================================================
--- Doc/library/io.rst	(revision 0)
+++ Doc/library/io.rst	(revision 0)
@@ -0,0 +1,586 @@
+:mod:`io` -- Core tools for working with streams
+================================================
+
+.. module:: io
+   :synopsis: Core tools for working with streams
+.. moduleauthor:: Guido van Rossum <guido@python.org>
+.. moduleauthor:: Mike Verdone <mike.verdone@gmail.com>
+.. moduleauthor:: Mark Russell <mark.russell@zen.co.uk
+.. sectionauthor:: Benjamin Peterson
+
+The :mod:`io` module provides the Python interfaces to stream handling.  The
+builtin :func:`open` function is defined in this module.
+
+At the top of the I/O hierarchy, is the abstract base class :class:`IOBase`.  It
+defines the basic interface to a stream.  Note, however, that there is no
+seperation between reading and writing to streams; implementations are allowed
+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:`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.
+
+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.
+
+Members, Functions, and Exceptions
+----------------------------------
+
+.. 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.
+
+.. function:: open(file, [mode, [buffering, [encoding, [errors, [newline, [closefd]]]]]]])
+
+   Open *file* and return a stream.
+
+   *file* is a string giving the name of the file or an integer file descriptor
+   of the file to be wrapped.
+
+   *mode* option mode string consists of several characters:
+     ========= ===============================================================
+     Character Meaning
+     --------- ---------------------------------------------------------------
+     'r'       open for reading (default)
+     'w'       open for writing, truncating the file first
+     'a'       open for writing, appending to the end of the file if it exists
+     'b'       binary mode
+     't'       text mode (default)
+     '+'       open a disk file for updating (reading and writing)
+     'U'       universal newline mode (for backwards compatibility)
+     ========= ===============================================================
+
+   *buffering* is an optional argument controling the buffering of the returned
+   stream.  A value of 0 means no buffering, 1 means line buffered, and a
+   greater value means full buffering.  Buffering cannot be disabled in text
+   mode.
+
+   *encoding* is the name of the encoding used to decode or encode the file.
+   This may only be used in text mode.
+
+   *errors* specifies how the encoding should treat errors.  "strict", the
+   default raises a :exc:`ValueError` on problems.  See the *errors* argument
+   of :func:`codecs.open` for more information.
+
+   *newline* controls how universal newlines works.  It can be :keyword:`None`,
+   '', '\n', '\r', and '\r\n'.  It works as follows:
+
+         * On input, if *newline* is :keyword:`None`, universal newlines mode is
+           enabled.  Lines in the input can end in '\n', '\r', or '\r\n', and
+           these are translated into '\n' before being returned to the caller.
+           If it is '', universal newline mode is enabled, but line endings are
+           returned to the caller untranslated.  If it has any of the other
+           legal values, input lines are only terminated by the given string,
+           and the line ending is returned to the caller untranslated.
+
+         * On output, if *newline* is :keyword:`None`, any '\n' characters
+           written are translated to the system default line separator,
+           :data:`os.linesep`.  If *newline* is '', no translation takes place.
+           If *newline* is any of the other legal values, any '\n' characters
+           written are translated to the given string.
+
+   If *closefd* is :keyword:`False`, the underlying file descriptor will be keep
+   open.  This does not work when a file name is given.
+
+
+.. exception:: BlockingIOError
+
+   Error raised when blocking would occur on a non-blocking stream.  It inherits
+   :exc:`IOError`.
+
+In addition to those of :exc:`IOERrror`, :exc:`BlockingIOError` has one
+attribute:
+
+
+.. attribute:: characters_written
+
+   An int containing the number of characters written to the stream before it
+   blocked.
+
+
+.. exception:: UnsupportedOperation
+
+   An exception inheriting :exc:`IOError` and :exc:`ValueError` that is raised
+   when an unsupported operation is called on a stream.
+
+
+I/O Classes
+-----------
+
+:class:`IOBase` objects
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The abstract base class for all I/O classes.
+
+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.
+
+Even though :class:`IOBase` does not declare read(), readinto(), seek(), or
+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.
+
+Note that calling any method (even inquiries) on a closed file is undefined.
+Implementations may raise IOError in this case.
+
+IOBase (and its subclasses) also supports the with statement.  In this example,
+fp is closed after the block under the with statment is complete::
+
+    fp = open("spam.txt", "r")
+    with fp:
+       fp.write("Spam and eggs!")
+
+.. class:: IOBase
+
+   There is no public constructor.
+
+IOBase provides these methods:
+
+
+.. method:: IOBase.close()
+
+   Flushes and closes this stream.
+   
+   This method has no affect when called multiple times.
+
+.. method:: IOBase.closed()
+
+   Tell if a stream is closed.
+
+.. method:: IOBase.fileno()
+
+   Return the underlying file descriptor of the stream, if it exists.
+
+.. method:: IOBase.flush()
+
+   Flush the write buffers of the stream if applicable.
+
+.. method:: IOBase.isatty()
+
+   Tell if a stream is interactive (connected to a tty device).
+
+.. method:: IOBase.readable()
+
+   Tell if a stream can be read from.
+
+.. method:: IOBase.readline([limit])
+
+   Read and return a line from the stream.  If *limit* is specified, at most
+   *limit* bytes will be read.
+
+.. method:: IOBase.readlines([hint])
+
+   Return list of lines from the stream.  *hint* can be specified to control the
+   number of lines read.
+
+.. method:: IOBase.seekable()
+
+   Tell if a stream supports random IO access.
+
+.. method:: IOBase.tell()
+
+   Return an int the current position in the stream.
+
+.. method:: IOBase.writeable()
+
+   Tell if a stream supports writing.
+
+.. method:: IOBase.writelines(lines)
+
+   Write a list of lines to the stream.
+
+
+:class:`RawIOBase` objects
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Base class for raw binary I/O.  It inherits :class:`IOBase`.
+
+RawIOBase provides or overrides these methods in addition to those from
+:class:`IOBase`:
+
+.. class:: RawIOBase
+
+   There is no public constructor.
+
+
+.. method:: RawIOBase.read([n])
+
+   Read and return everything on the stream until EOF, or if *n* is specified,
+   up to *n* bytes.  An empty bytes array is returned on EOF and
+   :keyword:`None`, or if the object is set not to block and has no data to
+   read.
+
+.. method:: RawIOBase.readall()
+
+   Read and return everything on the stream until EOF.
+
+
+:class:`FileIO` objects
+^^^^^^^^^^^^^^^^^^^^^^^
+
+:class:`FileIO` implements the :class:`RawIOBase` interface (and therefore the
+:class:`IOBase` interface, too) for OS files.
+
+.. class:: FileIO(name, [mode])
+
+   Open a file.  The *mode* can be 'r', 'w' or 'a' for reading (default),
+   writing, or appending.  The file will be created if it doesn't exist when
+   opened for 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`:
+
+.. method:: FileIO.read([size])
+
+   Read and return bytes at most *size* bytes.  Only one system call is made, so
+   less data than requested may be returned.  In non-blocking mode,
+   :keyword:`None` is returned when no data is available.
+
+.. method:: FileIO.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, ''
+   is returned.
+
+.. method:: FileIO.readinto(bytearray)
+
+   This method should not be used on :class:`FileIO` objects.
+
+.. method:: FileIO.seek(offset, [whence])
+
+   Move to a new file position.  The first argument, *offset*, is a byte count
+   to move.  The second optional argument, *whence*, gives the relative position
+   that the *offset* should start from.  It defaults to 0, meaning the *offset*
+   is from start of file.  (In this case, the *offset* should be >= 0.)  A value
+   of 1 causes *offset* to move from the current position.  (*offset* can be
+   negative or positive.)  Passing 2 sets the relative marker to the end of the
+   file.  (*offset* is usually negative, although many platforms allow seeking
+   beyond the end of a file.)
+
+.. method:: FileIO.truncate(size)
+
+   Truncate the file to at most *size* bytes.  Size defaults to the current file
+   position, as returned by :meth:`tell()`.
+
+.. method:: FileIO.write(b)
+
+   Write 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.
+
+
+:class:`BufferedIOBase` objects
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Base class for streams that support buffering.  It inherits :class:`IOBase`.
+
+The main difference with RawIOBase is that the read() method supports omitting
+the size argument, and does not have a default implementation that defers to
+readinto().
+
+In addition, read(), readinto(), and write() may raise BlockingIOError if the
+underlying raw stream is in non-blocking mode and not ready; unlike their raw
+counterparts, they will never return :keyword:`None`.
+
+A typical implementation should not inherit from a RawIOBase implementation, but
+wrap one like :class:`BufferedWriter` and :class:`BufferedReader`.
+
+.. class:: BufferedIOBase
+
+   No public constructor.
+
+:class:`BufferedIOBase` provides or overrides these methods in addition to those
+from :class:`IOBase`:
+
+
+.. method:: BufferedIOBase.read([n])
+
+   Read and return up to *n* bytes.  If the argument is omitted,
+   :keyword:`None`, or negative, data is read and returned until EOF is
+   reached. An empty byte array is returned if the stream is already at EOF.
+
+   If the argument is positive, and the underlying raw stream is not
+   interactive, multiple raw reads may be issued to satisfy the byte count
+   (unless EOF is reached first).  But for interactive raw streams, at most one
+   raw read will be issued, and a short result does not imply that EOF is
+   imminent.
+
+   A :exc:`BlockingIOError` is raised if the underlying raw stream has no data
+   at the moment.
+
+.. method:: BufferedIOBase.readinto(b)
+
+   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
+   stream, unless the latter is 'iteractive.'
+
+   A :exc:`BlockingIOError` is raised if the underlying raw stream has no data
+   at the moment.
+
+.. method:: BufferedIOBase.seek(pos, [whence])
+
+   Move the position of the raw stream by *pos*. The optional argument,
+   *whence*, dictates the position the *pos* offset will move by.  If *whence*
+   is 0, the default, the *pos* is moved from the start of the stream.  If
+   *whence* is 1, *pos* is from the current position in the stream, and if
+   *whence* is 2, *pos* is from the end of the stream.
+
+.. method:: BufferedIOBase.write(b)
+
+   Write the given bytes 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.
+
+
+:class:`BytesIO` objects
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+A stream implementation using an in-memory bytes buffer.  It inherits
+:class:`BufferedIOBase`.
+
+.. class:: BytesIO([initial_bytes])
+
+   Create a BytesIO object with an optional initial bytearray.
+
+:class:`BytesIO` provides or overrides these methods in addition to those from
+:class:`BufferedIOBase` and :class:`IOBase`:
+
+
+.. method:: BytesIO.getvalue()
+
+   Returns the bytes value of the buffer.
+
+.. method:: BytesIO.read1()
+
+   In :class:`BytesIO`, this is the same as :meth:`read()`.
+
+.. method:: BytesIO.truncate([size])
+
+   Truncates the stream to at most *size*.  If *size* is not given, the stream
+   is truncated to the current position.
+
+
+:class:`BufferedReader` objects
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A buffer for a readable sequential RawIO object.  It inherits
+:class:`BufferedIOBase`.
+
+.. class:: BufferedReader(raw, [buffer_size])
+
+   Create a :class:`BufferedReader` for the given readable raw stream and buffer
+   size.  If *buffer_size* is omitted, :data:`DEFAULT_BUFFER_SIZE` is used.
+
+:class:`BufferedReader` provides or overrides these methods in addition to those
+from :class:`BufferedIOBase` and :class:`IOBase`:
+
+
+.. method:: BufferedReader.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.
+
+.. method:: BufferedReader.read([n])
+
+   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:: BufferedReader.read1(n)
+
+   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.
+
+
+:class:`BufferedWriter` objects
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A buffer for a writeable sequential RawIO object.  It inherits
+:class:`BufferedIOBase`.
+
+.. class:: BufferedWriter(raw, [buffer_size, [max_buffer_size]])
+
+   Create a :class:`BufferedWriter` for the given writeable raw stream.  If the
+   buffer size is not given, it defaults to :data:`DEAFULT_BUFFER_SIZE`.  If the
+   maximum buffer size is omitted, it defaults to twice the buffer size.
+
+:class:`BufferedWriter` provides or overrides these methods in addition to those
+from :class:`BufferedIOBase` and :class:`IOBase`:
+
+
+.. method:: BufferedWriter.flush()
+
+   Force bytes held in the buffer into the raw stream.  A :exc:`BlockingIOError`
+   is be raised if the raw stream blocks.
+
+.. method:: BufferedWriter.write(b)
+
+   Write bytes *b* onto the raw stream and return the number written.  A
+   :exc:`BlockingIOError` is raised when the raw stream blocks.
+
+
+:class:`BufferedRWPair` objects
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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`.
+
+.. class:: BufferedRWPair(reader, writer, [buffer_size, [max_buffer_size]])
+
+   Create a :class:`BufferedRWPair`.  reader and writer and :class:`RawIOBase`
+   objects that are readable and writeable respectively. If a *buffer_size* is
+   omitted it defaults to :data:`DEFAULT_BUFFER_SIZE`.  The maximum buffer size
+   (for the buffered writer) defaults to twice the buffer size.
+
+:class:`BufferedRWPair` implements all of :class:`BufferedIOBase`'s methods.
+
+
+:class:`BufferedRandom` objects
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A buffered interface to random access streams.  It inherits
+:class:`BufferedReader` and :class:`BufferedWriter`.
+
+.. class:: BufferedRandom(raw, [buffer_size, [max_buffer_size]])
+
+   Create a new :class:`BufferedRandom` reader and writer for a seekable raw
+   stream named in the first argument.  If the *buffer_size* is omitted it
+   defaults to :data:`DEFAULT_BUFFER_SIZE`.  The maximum buffer size (for the
+   buffered writer) defaults to twice the buffer size.
+
+:class:`BufferedRandom` is capable of anything :class:`BufferedReader` or
+:class:`BufferedWriter` can do.
+
+
+:class:`TextIOBase` objects
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Base class for text streams.  This class provides a character and line based
+interface to stream I/O.  There is not readinto() because character string as
+immutable.  It inherits :class:`IOBase`.
+
+.. class:: TextIOBase
+
+   No public constructor
+
+:class:`TextIOBase` provides or overrides these methods in addition to those
+from :class:`IOBase`:
+
+
+.. method:: TextIOBase.encoding()
+
+   Return the name of the encoding used to decode the stream into text.
+
+.. method:: TextIOBase.newlines()
+
+   Return a str, tuple of strs, or :keyword:`None` containing the newlines
+   translated so far.
+
+.. method:: TextIOBase.read(n)
+
+   Read and return at most *n* characters from the stream.  If *n* is negative
+   or :keyword:`None`, read to EOF.
+
+.. method:: TextIOBase.readline()
+
+   Read until newline of EOF and return.  If the stream is already at EOF, an
+   empty stream is returned.
+
+.. method:: TextIOBase.truncate([pos])
+
+   Truncate size to *pos*. If *pos* is not specified, it is assumed to be the
+   current position.
+
+.. method:: TextIOBase.write(s)
+
+   Write str *s* to the stream and return the number of characters written.
+
+
+:class:`TextIOWrapper` objects
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A buffered text stream over a :class:`BufferedIOBase` raw stream.  It inherits
+:class:`TextIOBase`.
+
+.. class:: TextIOWrapper(buffer, [encoding, [errors, [newline,
+.. [line_buffering]]]])
+
+   Create a :class:`TextIOWrapper` for the :class:`BufferIOBase` stream, *buffer*.
+
+   *encoding* gives the name of the encoding that the stream will be decoded or
+   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".
+
+   *newline* can be :keyword:`None`, '', '\n', '\r', or '\r\n'.  It controls the
+    handling of line endings.  If it is none, universal newlines is enabled.
+    With this enabled, on input, the lines endings "\n", "\r", or "\r\n" are
+    translated to "\n" before being returned to the caller.  Conversly, on
+    output, "\n" is translated to the system default line seperator,
+    :data:`os.linsep`.  If *newline* is any other of its legal values, that
+    newline becomes the newline when the file is read and it is returned
+    untranslated.  On ouput, "\n" is converted to the *newline*.
+
+    If *line_buffering* is :keyword:`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:`TextIOBase` and its parents:
+
+
+.. method:: TextIOWrapper.errors()
+
+   Return the encoding and decoding error setting.
+
+.. method:: TextIOWrapper.line_buffering()
+
+   Return whether line buffering is enabled.
+   
+
+:class:`StringIO` objects
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+An in-memory stream for text. It in inherits :class:`TextIOWrapper`.
+
+.. class:: StringIO([initial_value, [encoding, [errors, [newline]]]])
+
+   Create a new StringIO stream with an inital value, encoding, error handling,
+   and newline setting. See :class:`TextIOWrapper`'s constructor for more
+   information.
+
+:class:`StringIO` provides these methods in addition to those from
+:class:`TextIOWrapper` and its parents:
+
+
+.. method:: StringIO.getvalue()
+
+   Return a str representation of the contents of the internal buffer.
+
+
+:class:`IncrementalNewlineDecoder` objects
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A helper codec that decodes newlines.  It inherits
+:class:`codecs.IncrementalDecoder`.
+