Merged revisions 59605-59624 via svnmerge from

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

........
  r59606 | georg.brandl | 2007-12-29 11:57:00 +0100 (Sat, 29 Dec 2007) | 2 lines

  Some cleanup in the docs.
........
  r59611 | martin.v.loewis | 2007-12-29 19:49:21 +0100 (Sat, 29 Dec 2007) | 2 lines

  Bug #1699: Define _BSD_SOURCE only on OpenBSD.
........
  r59612 | raymond.hettinger | 2007-12-29 23:09:34 +0100 (Sat, 29 Dec 2007) | 1 line

  Simpler documentation for itertools.tee().  Should be backported.
........
  r59613 | raymond.hettinger | 2007-12-29 23:16:24 +0100 (Sat, 29 Dec 2007) | 1 line

  Improve docs for itertools.groupby().  The use of xrange(0) to create a unique object is less obvious than object().
........
  r59620 | christian.heimes | 2007-12-31 15:47:07 +0100 (Mon, 31 Dec 2007) | 3 lines

  Added wininst-9.0.exe executable for VS 2008
  Integrated bdist_wininst into PCBuild9 directory
........
  r59621 | christian.heimes | 2007-12-31 15:51:18 +0100 (Mon, 31 Dec 2007) | 1 line

  Moved PCbuild directory to PC/VS7.1
........
  r59622 | christian.heimes | 2007-12-31 15:59:26 +0100 (Mon, 31 Dec 2007) | 1 line

  Fix paths for build bot
........
  r59623 | christian.heimes | 2007-12-31 16:02:41 +0100 (Mon, 31 Dec 2007) | 1 line

  Fix paths for build bot, part 2
........
  r59624 | christian.heimes | 2007-12-31 16:18:55 +0100 (Mon, 31 Dec 2007) | 1 line

  Renamed PCBuild9 directory to PCBuild
........

1 files changed, 44 insertions, 19 deletions

diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index 49bc8b6..0ec255f 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -202,8 +202,6 @@ Numbers
       operation except left shift, if it yields a result in the plain integer domain
       without causing overflow, will yield the same result when using mixed operands.
 
-      .. % Integers
-
    Floating point numbers
       .. index::
          object: floating point
@@ -229,8 +227,6 @@ Numbers
       The real and imaginary parts of a complex number ``z`` can be retrieved through
       the read-only attributes ``z.real`` and ``z.imag``.
 
-   .. % Numbers
-
 Sequences
    .. index::
       builtin: len
@@ -302,8 +298,6 @@ Sequences
          parentheses must be usable for grouping of expressions).  An empty
          tuple can be formed by an empty pair of parentheses.
 
-      .. % Immutable sequences
-
    Mutable sequences
       .. index::
          object: mutable sequence
@@ -341,10 +335,6 @@ Sequences
       The extension module :mod:`array` provides an additional example of a
       mutable sequence type.
 
-      .. % Mutable sequences
-
-   .. % Sequences
-
 Set types
    .. index::
       builtin: len
@@ -379,8 +369,6 @@ Set types
       :term:`hashable`, it can be used again as an element of another set, or as
       a dictionary key.
 
-   .. % Set types
-
 Mappings
    .. index::
       builtin: len
@@ -418,8 +406,6 @@ Mappings
       The extension modules :mod:`dbm`, :mod:`gdbm`, and :mod:`bsddb` provide
       additional examples of mapping types.
 
-   .. % Mapping types
-
 Callable types
    .. index::
       object: callable
@@ -652,8 +638,6 @@ Modules
    object used to initialize the module (since it isn't needed once the
    initialization is done).
 
-   .. % 
-
    Attribute assignment updates the module's namespace dictionary, e.g., ``m.x =
    1`` is equivalent to ``m.__dict__["x"] = 1``.
 
@@ -992,12 +976,53 @@ Internal types
       described above, under "User-defined methods". Class method objects are created
       by the built-in :func:`classmethod` constructor.
 
-   .. % Internal types
-
-.. % =========================================================================
 
 .. _newstyle:
 
+New-style and classic classes
+=============================
+
+Classes and instances come in two flavors: old-style or classic, and new-style.
+
+Up to Python 2.1, old-style classes were the only flavour available to the user.
+The concept of (old-style) class is unrelated to the concept of type: if *x* is
+an instance of an old-style class, then ``x.__class__`` designates the class of
+*x*, but ``type(x)`` is always ``<type 'instance'>``.  This reflects the fact
+that all old-style instances, independently of their class, are implemented with
+a single built-in type, called ``instance``.
+
+New-style classes were introduced in Python 2.2 to unify classes and types.  A
+new-style class neither more nor less than a user-defined type.  If *x* is an
+instance of a new-style class, then ``type(x)`` is the same as ``x.__class__``.
+
+The major motivation for introducing new-style classes is to provide a unified
+object model with a full meta-model.  It also has a number of immediate
+benefits, like the ability to subclass most built-in types, or the introduction
+of "descriptors", which enable computed properties.
+
+For compatibility reasons, classes are still old-style by default.  New-style
+classes are created by specifying another new-style class (i.e. a type) as a
+parent class, or the "top-level type" :class:`object` if no other parent is
+needed.  The behaviour of new-style classes differs from that of old-style
+classes in a number of important details in addition to what :func:`type`
+returns.  Some of these changes are fundamental to the new object model, like
+the way special methods are invoked.  Others are "fixes" that could not be
+implemented before for compatibility concerns, like the method resolution order
+in case of multiple inheritance.
+
+This manual is not up-to-date with respect to new-style classes.  For now,
+please see http://www.python.org/doc/newstyle.html for more information.
+
+.. index::
+   single: class
+   single: class
+   single: class
+
+The plan is to eventually drop old-style classes, leaving only the semantics of
+new-style classes.  This change will probably only be feasible in Python 3.0.
+new-style classic old-style
+
+
 .. _specialnames:
 
 Special method names