Add items

Doc/whatsnew/2.6.rst

@@ -746,7 +746,70 @@ XXX give example
 PEP 3116: New I/O Library
 =====================================================
 
-XXX write this.
+Python's built-in file objects support a number of methods, but
+file-like objects don't necessarily support all of them.  Objects that
+imitate files usually support :meth:`read` and :meth:`write`, but they
+may not support :meth:`readline`.  Python 3.0 introduces a layered I/O
+library in the :mod:`io` module that separates buffering and
+text-handling features from the fundamental read and write operations.
+
+There are three levels of abstract base classes provided by
+the :mod:`io` module:
+
+* :class:`RawIOBase`: defines raw I/O operations: :meth:`read`,
+  :meth:`readinto`, 
+  :meth:`write`, :meth:`seek`, :meth:`tell`, :meth:`truncate`,
+  and :meth:`close`.
+  Most of the methods of this class will often map to a single system call.
+  There are also :meth:`readable`, :meth:`writable`, and :meth:`seekable`
+  methods for determining what operations a given object will allow.
+
+  Python 3.0 has concrete implementations of this class for files and
+  sockets, but Python 2.6 hasn't restructured its file and socket objects
+  in this way.
+
+  .. XXX should 2.6 register them in io.py?
+
+* :class:`BufferedIOBase`: is an abstract base class that 
+  buffers data in memory to reduce the number of 
+  system calls used, making I/O processing more efficient.
+  It supports all of the methods of :class:`RawIOBase`, 
+  and adds a :attr:`raw` attribute holding the underlying raw object.
+
+  There are four concrete classes implementing this ABC:
+  :class:`BufferedWriter` and 
+  :class:`BufferedReader` for objects that only support
+  writing or reading and don't support random access,
+  :class:`BufferedRandom` for objects that support the :meth:`seek` method
+  for random access,
+  and :class:`BufferedRWPair` for objects such as TTYs that have 
+  both read and write operations that act upon unconnected streams of data.
+
+* :class:`TextIOBase`: Provides functions for reading and writing
+  strings (remember, strings will be Unicode in Python 3.0),
+  and supporting universal newlines.  :class:`TextIOBase` defines 
+  the :meth:`readline` method and supports iteration upon 
+  objects.   
+
+  There are two concrete implementations.  :class:`TextIOWrapper`
+  wraps a buffered I/O object, supporting all of the methods for
+  text I/O and adding a :attr:`buffer` attribute for access 
+  to the underlying object.  :class:`StringIO` simply buffers
+  everything in memory without ever writing anything to disk.
+
+  (In current 2.6 alpha releases, :class:`io.StringIO` is implemented in
+  pure Python, so it's pretty slow.   You should therefore stick with the 
+  existing :mod:`StringIO` module or :mod:`cStringIO` for now.  At some 
+  point Python 3.0's :mod:`io` module will be rewritten into C for speed,
+  and perhaps the C implementation will be  backported to the 2.x releases.)
+
+  .. XXX check before final release: is io.py still written in Python?
+
+In Python 2.6, the underlying implementations haven't been
+restructured to build on top of the :mod:`io` module's classes.  The
+module is being provided to make it easier to write code that's 
+forward-compatible with 3.0, and to save developers the effort of writing
+their own implementations of buffering and text I/O.
 
 .. seealso::
 
@@ -1571,7 +1634,7 @@ complete list of changes, or look through the CVS logs for all the details.
        (3, 1), (3, 2), (3, 4), 
        (4, 1), (4, 2), (4, 3)]
 
-  ``itertools.chain(*iterables)` is an existing function in
+  ``itertools.chain(*iterables)`` is an existing function in
   :mod:`itertools` that gained a new constructor in Python 2.6.
   ``itertools.chain.from_iterable(iterable)`` takes a single 
   iterable that should return other iterables.  :func:`chain` will