Merged revisions 61440-61441,61443,61445-61448,61451-61452,61455-61457,61459-61464,61466-61467,61469-61470,61476-61477,61479,61481-61482,61485,61487,61490,61493-61494,61497,61499-61502,61505-61506,61508,61511-61514,61519,61521-61522,61530-61531,61533-61537,61541-61555,61557-61558,61561-61562,61566-61569,61572-61574,61578-61579,61583-61584,61588-61589,61592,61594,61598-61601,61603-61604,61607-61612,61617,61619-61620,61624,61626,61628-61630,61635-61638,61640-61643,61645,61648,61653-61655,61659-61662,61664,61666,61668-61671,61673,61675,61679-61680,61682,61685-61686,61689-61695,61697-61699,61701-61703,61706,61710,61713,61717,61723,61726-61730,61736,61738,61740,61742,61745-61752,61754-61760,61762-61764,61768,61770-61772,61774-61775,61784-61787,61789-61792,61794-61795,61797-61806,61808-61809,61811-61812,61814-61819,61824,61826-61833,61835-61840,61843-61845,61848,61850,61854-61862,61865-61866,61868,61872-61873,61876-61877,61883-61888,61890-61891,61893-61899,61901-61903,61905-61912,61914,61917,61920-61921,61927,61930,61932-61934,61939,61941-61942,61944-61951,61955,61960-61963,61980,61982-61983,61991,61994-61996,62001-62003,62008-62010,62016-62017,62022,62024,62027,62031-62034,62041,62045-62046,62055-62058,62060-62066,62068-62074,62076-62079,62081-62083,62086-62089,62092-62094,62098,62101,62104,62106-62109,62115-62122,62124-62125,62128,62130,62132,62134-62135,62137,62139-62140,62144,62146,62151,62155,62157,62162-62174 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/trunk

........
  r62167 | martin.v.loewis | 2008-04-05 17:45:25 +0200 (Sa, 05 Apr 2008) | 1 line

  Extend sizes of various fields, to support the CRT90 merge module.
........
  r62168 | martin.v.loewis | 2008-04-05 17:48:36 +0200 (Sa, 05 Apr 2008) | 1 line

  Add two features to distinguish between private and SxS CRT.
........
  r62169 | martin.v.loewis | 2008-04-05 17:50:58 +0200 (Sa, 05 Apr 2008) | 1 line

  Add script to merge msvcr90.
........
  r62170 | andrew.kuchling | 2008-04-05 17:57:46 +0200 (Sa, 05 Apr 2008) | 1 line

  Markup fixes; write PEP 3118 section
........
  r62173 | georg.brandl | 2008-04-05 19:45:58 +0200 (Sa, 05 Apr 2008) | 2 lines

  Mention that the tuple returned by __reduce__ is pickled as normal.
........
  r62174 | andrew.kuchling | 2008-04-05 20:15:30 +0200 (Sa, 05 Apr 2008) | 1 line

  Write PEP 3119 section
........

1 files changed, 180 insertions, 37 deletions

diff --git a/Doc/whatsnew/2.6.rst b/Doc/whatsnew/2.6.rst
index 26f5169..2098508 100644
--- a/Doc/whatsnew/2.6.rst
+++ b/Doc/whatsnew/2.6.rst
@@ -156,15 +156,18 @@ http://svn.python.org/view/tracker/importer/.
 
 .. seealso::
 
-  http://bugs.python.org: The Python bug tracker.
+  http://bugs.python.org 
+    The Python bug tracker.
 
-  http://bugs.jython.org: The Jython bug tracker.
+  http://bugs.jython.org:
+    The Jython bug tracker.
 
-  http://roundup.sourceforge.net/: Roundup downloads and documentation.
+  http://roundup.sourceforge.net/
+    Roundup downloads and documentation.
 
 
-New Documentation Format: ReStructured Text
---------------------------------------------------
+New Documentation Format: ReStructured Text Using Sphinx
+-----------------------------------------------------------
 
 Since the Python project's inception around 1989, the documentation
 had been written using LaTeX.  At that time, most documentation was
@@ -191,16 +194,20 @@ The input format is reStructured Text,
 a markup commonly used in the Python community that supports
 custom extensions  and directives.   Sphinx concentrates 
 on HTML output, producing attractively styled 
-and modern HTML, but printed output is still supported through 
-conversion to LaTeX as an output format.
+and modern HTML, though printed output is still supported through 
+conversion to LaTeX.  Sphinx is a standalone package that
+can be used in documenting other projects.
 
 .. seealso::
 
-   `Docutils <http://docutils.sf.net>`__: The fundamental
-   reStructured Text parser and toolset.
+   :ref:`documenting-index`
+       Describes how to write for Python's documentation.
+
+   `Sphinx <http://sphinx.pocoo.org/>`__
+     Documentation and code for the Sphinx toolchain.
 
-   :ref:`documenting-index`: Describes how to write for 
-   Python's documentation.
+   `Docutils <http://docutils.sf.net>`__
+     The underlying reStructured Text parser and toolset.
 
 
 PEP 343: The 'with' statement
@@ -487,8 +494,7 @@ can now be used in scripts running from inside a package.
     .. seealso::
 
        :pep:`370` - XXX
-
-       PEP written by XXX; implemented by Christian Heimes.
+         PEP written by XXX; implemented by Christian Heimes.
 
   
 .. ======================================================================
@@ -633,9 +639,8 @@ PEP 3105: ``print`` As a Function
 =====================================================
 
 The ``print`` statement becomes the :func:`print` function in Python 3.0.
-Making :func:`print` a function makes it easier to replace within a
-module by doing 'def print(...)' or importing a new 
-function from somewhere else. 
+Making :func:`print` a function makes it easier to change 
+by doing 'def print(...)' or importing a new function from somewhere else. 
 
 Python 2.6 has a ``__future__`` import that removes ``print`` as language 
 syntax, letting you use the functional form instead.  For example::
@@ -750,13 +755,50 @@ XXX write this.
 PEP 3118: Revised Buffer Protocol
 =====================================================
 
-The buffer protocol is a C-level API that lets Python extensions 
-XXX
+The buffer protocol is a C-level API that lets Python types
+exchange pointers into their internal representations.  A 
+memory-mapped file can be viewed as a buffer of characters, for
+example, and this lets another module such as :mod:`re`
+treat memory-mapped files as a string of characters to be searched.
+
+The primary users of the buffer protocol are numeric-processing
+packages such as NumPy, which can expose the internal representation
+of arrays so that callers can write data directly into an array instead
+of going through a slower API.  This PEP updates the buffer protocol in light of experience 
+from NumPy development, adding a number of new features
+such as indicating the shape of an array, 
+locking memory .
+
+The most important new C API function is 
+``PyObject_GetBuffer(PyObject *obj, Py_buffer *view, int flags)``, which
+takes an object and a set of flags, and fills in the
+``Py_buffer`` structure with information 
+about the object's memory representation.  Objects
+can use this operation to lock memory in place 
+while an external caller could be modifying the contents,
+so there's a corresponding 
+``PyObject_ReleaseBuffer(PyObject *obj, Py_buffer *view)`` to
+indicate that the external caller is done.
+
+The **flags** argument to :cfunc:`PyObject_GetBuffer` specifies
+constraints upon the memory returned.  Some examples are:
+
+ * :const:`PyBUF_WRITABLE` indicates that the memory must be writable.
+ 
+ * :const:`PyBUF_LOCK` requests a read-only or exclusive lock on the memory.
+
+ * :const:`PyBUF_C_CONTIGUOUS` and :const:`PyBUF_F_CONTIGUOUS`
+   requests a C-contiguous (last dimension varies the fastest) or
+   Fortran-contiguous (first dimension varies the fastest) layout.
+
+.. XXX this feature is not in 2.6 docs yet
 
 .. seealso::
 
    :pep:`3118` - Revising the buffer protocol
-      PEP written by Travis Oliphant and Carl Banks.
+      PEP written by Travis Oliphant and Carl Banks; implemented by
+      Travis Oliphant.
+      
 
 .. ======================================================================
 
@@ -765,41 +807,142 @@ XXX
 PEP 3119: Abstract Base Classes
 =====================================================
 
-XXX write this -- this section is currently just brief notes.
+Some object-oriented languages such as Java support interfaces: declarations
+that a class has a given set of methods or supports a given access protocol.
+Abstract Base Classes (or ABCs) are an equivalent feature for Python. The ABC
+support consists of an :mod:`abc` module containing a metaclass called 
+:class:`ABCMeta`, special handling
+of this metaclass by the :func:`isinstance` and :func:`issubclass` built-ins,
+and a collection of basic ABCs that the Python developers think will be widely
+useful.
+
+Let's say you have a particular class and wish to know whether it supports 
+dictionary-style access.  The phrase "dictionary-style" is vague, however.
+It probably means that accessing items with ``obj[1]`` works.  
+Does it imply that setting items with ``obj[2] = value`` works?  
+Or that the object will have :meth:`keys`, :meth:`values`, and :meth:`items`
+methods?  What about the iterative variants  such as :meth:`iterkeys`?  :meth:`copy`
+and :meth:`update`?  Iterating over the object with :func:`iter`?
+
+Python 2.6 includes a number of different ABCs in the :mod:`collections`
+module.  :class:`Iterable` indicates that a class defines :meth:`__iter__`,
+and :class:`Container` means the class supports  ``x in y`` expressions
+by defining a :meth:`__contains__` method.  The basic dictionary interface of
+getting items, setting items, and 
+:meth:`keys`, :meth:`values`, and :meth:`items`, is defined by the
+:class:`MutableMapping` ABC.
+
+You can derive your own classes from a particular ABC
+to indicate they support that ABC's interface::
+
+    import collections
+  
+    class Storage(collections.MutableMapping):
+        ...
 
-How to identify a file object?
 
-ABCs are a collection of classes describing various interfaces.
-Classes can derive from an ABC to indicate they support that ABC's
-interface.  Concrete classes should obey the semantics specified by 
-an ABC, but Python can't check this; it's up to the implementor.
+Alternatively, you could write the class without deriving from 
+the desired ABC and instead register the class by
+calling the ABC's :meth:`register` method::
 
-A metaclass lets you declare that an existing class or type
-derives from a particular ABC.  You can even 
+    import collections
+    
+    class Storage:
+        ...
+	
+    collections.MutableMapping.register(Storage)
+    
+For classes that you write, deriving from the ABC is probably clearer.
+The :meth:`register`  method is useful when you've written a new
+ABC that can describe an existing type or class, or if you want
+to declare that some third-party class implements an ABC.
+For example, if you defined a :class:`PrintableType` ABC,
+it's legal to do:
+
+  # Register Python's types
+  PrintableType.register(int)
+  PrintableType.register(float)
+  PrintableType.register(str)
+
+Classes should obey the semantics specified by an ABC, but 
+Python can't check this; it's up to the class author to  
+understand the ABC's requirements and to implement the code accordingly.
+
+To check whether an object supports a particular interface, you can
+now write::
+
+    def func(d):
+	if not isinstance(d, collections.MutableMapping):
+	    raise ValueError("Mapping object expected, not %r" % d)        
+
+(Don't feel that you must now begin writing lots of checks as in the 
+above example.  Python has a strong tradition of duck-typing, where 
+explicit type-checking isn't done and code simply calls methods on 
+an object, trusting that those methods will be there and raising an
+exception if they aren't.  Be judicious in checking for ABCs
+and only do it where it helps.)
+
+You can write your own ABCs by using ``abc.ABCMeta`` as the
+metaclass in a class definition::
+
+  from abc import ABCMeta
+
+  class Drawable():
+      __metaclass__ = ABCMeta
+  
+      def draw(self, x, y, scale=1.0):
+	  pass
 
-class AppendableSequence:
-    __metaclass__ = ABCMeta
+      def draw_doubled(self, x, y):
+	  self.draw(x, y, scale=2.0)
 
-AppendableSequence.register(list)
-assert issubclass(list, AppendableSequence)
-assert isinstance([], AppendableSequence)
+	
+  class Square(Drawable):
+      def draw(self, x, y, scale):
+          ...
 
-@abstractmethod decorator -- you can't instantiate classes w/
-an abstract method.
+	  
+In the :class:`Drawable` ABC above, the :meth:`draw_doubled` method
+renders the object at twice its size and can be implemented in terms
+of other methods described in :class:`Drawable`.  Classes implementing
+this ABC therefore don't need to provide their own implementation 
+of :meth:`draw_doubled`, though they can do so.  An implementation
+of :meth:`draw` is necessary, though; the ABC can't provide 
+a useful generic implementation.  You 
+can apply the ``@abstractmethod`` decorator to methods such as 
+:meth:`draw` that must be implemented; Python will 
+then raise an exception for classes that 
+don't define the method::
+
+    class Drawable():
+	__metaclass__ = ABCMeta
+    
+	@abstractmethod
+	def draw(self, x, y, scale):
+	    pass
+
+Note that the exception is only raised when you actually 
+try to create an instance of a subclass without the method::
+
+    >>> s=Square()
+    Traceback (most recent call last):
+      File "<stdin>", line 1, in <module>
+    TypeError: Can't instantiate abstract class Square with abstract methods draw
+    >>> 
 
-::
+Abstract data attributes can be declared using the ``@abstractproperty`` decorator::
 
-    @abstractproperty decorator
     @abstractproperty
     def readonly(self):
        return self._x
 
+Subclasses must then define a :meth:`readonly` property 
 
 .. seealso::
 
    :pep:`3119` - Introducing Abstract Base Classes
       PEP written by Guido van Rossum and Talin.
-      Implemented by XXX.
+      Implemented by Guido van Rossum.
       Backported to 2.6 by Benjamin Aranguren, with Alex Martelli.
 
 .. ======================================================================