Merged revisions 66508,66510,66512-66513,66523-66526,66529-66530,66532,66535,66538,66544,66546 via svnmerge from

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

........
  r66508 | benjamin.peterson | 2008-09-18 18:20:28 -0500 (Thu, 18 Sep 2008) | 1 line

  tabify
........
  r66510 | josiah.carlson | 2008-09-18 21:07:22 -0500 (Thu, 18 Sep 2008) | 2 lines

  Fix for documentation bug.  Fixes issue 3904.
........
  r66512 | raymond.hettinger | 2008-09-19 03:07:48 -0500 (Fri, 19 Sep 2008) | 1 line

  Improve docs for super().
........
  r66513 | lars.gustaebel | 2008-09-19 07:39:23 -0500 (Fri, 19 Sep 2008) | 2 lines

  Correct information about the tarfile module.
........
  r66523 | georg.brandl | 2008-09-21 02:14:44 -0500 (Sun, 21 Sep 2008) | 2 lines

  #3852: fix some select.kqueue and kevent docs.
........
  r66524 | georg.brandl | 2008-09-21 02:15:59 -0500 (Sun, 21 Sep 2008) | 2 lines

  #3912: document default for *places* arg.
........
  r66525 | georg.brandl | 2008-09-21 02:17:00 -0500 (Sun, 21 Sep 2008) | 2 lines

  #3916: fixes for docs wrt. Windows directory layout
........
  r66526 | georg.brandl | 2008-09-21 02:18:28 -0500 (Sun, 21 Sep 2008) | 2 lines

  #3914: add //= to the augmented assign operators.
........
  r66529 | georg.brandl | 2008-09-21 02:24:11 -0500 (Sun, 21 Sep 2008) | 2 lines

  #3901: bsddb fix.
........
  r66530 | georg.brandl | 2008-09-21 02:31:52 -0500 (Sun, 21 Sep 2008) | 2 lines

  #3897: _collections now has an underscore.
........
  r66532 | georg.brandl | 2008-09-21 02:36:22 -0500 (Sun, 21 Sep 2008) | 2 lines

  Update readme and Makefile (web builder doesn't exist).
........
  r66535 | georg.brandl | 2008-09-21 03:03:21 -0500 (Sun, 21 Sep 2008) | 2 lines

  #3918: note that uniform() args can be swapped.
........
  r66538 | georg.brandl | 2008-09-21 05:03:39 -0500 (Sun, 21 Sep 2008) | 2 lines

  Add "dist" target.
........
  r66544 | benjamin.peterson | 2008-09-21 16:27:51 -0500 (Sun, 21 Sep 2008) | 4 lines

  #3879 fix a regression in urllib.getproxies_environment

  reviewers: Benjamin, Georg
........
  r66546 | georg.brandl | 2008-09-21 17:31:59 -0500 (Sun, 21 Sep 2008) | 2 lines

  Fill out download page.
........

1 files changed, 22 insertions, 7 deletions

diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 67a4f06c..b016a32 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -1086,16 +1086,29 @@ are always available.  They are listed here in alphabetical order.
 
    .. XXX updated as per http://www.artima.com/weblogs/viewpost.jsp?thread=208549 but needs checking
 
+   Return a "super" object that acts like the superclass of *type*.
 
-   Return a "super" object that acts like the superclass of *type*.  If the
-   second argument is omitted the super object returned is unbound.  If the
-   second argument is an object, ``isinstance(obj, type)`` must be true.  If the
-   second argument is a type, ``issubclass(type2, type)`` must be
-   true. :func:`super` only works for :term:`new-style class`\es.  Calling
-   :func:`super()` without arguments is equivalent to ``super(this_class,
+   If the second argument is omitted the super object returned is unbound.  If
+   the second argument is an object, ``isinstance(obj, type)`` must be true.  If
+   the second argument is a type, ``issubclass(type2, type)`` must be true.
+   Calling :func:`super` without arguments is equivalent to ``super(this_class,
    first_arg)``.
 
-   A typical use for calling a cooperative superclass method is::
+   There are two typical use cases for "super".  In a class hierarchy with
+   single inheritance, "super" can be used to refer to parent classes without
+   naming them explicitly, thus making the code more maintainable.  This use
+   closely parallels the use of "super" in other programming languages.
+   
+   The second use case is to support cooperative multiple inheritence in a
+   dynamic execution environment.  This use case is unique to Python and is 
+   not found in statically compiled languages or languages that only support 
+   single inheritance.  This makes in possible to implement "diamond diagrams"
+   where multiple base classes implement the same method.  Good design dictates
+   that this method have the same calling signature in every case (because the
+   order of parent calls is determined at runtime and because that order adapts
+   to changes in the class hierarchy).
+
+   For both use cases, a typical superclass call looks like this::
 
       class C(B):
           def method(self, arg):
@@ -1103,6 +1116,8 @@ are always available.  They are listed here in alphabetical order.
 
    Note that :func:`super` is implemented as part of the binding process for
    explicit dotted attribute lookups such as ``super().__getitem__(name)``.
+   It does so by implementing its own :meth:`__getattribute__` method for searching
+   parent classes in a predictable order that supports cooperative multiple inheritance.
    Accordingly, :func:`super` is undefined for implicit lookups using statements or
    operators such as ``super()[name]``. Also, :func:`super` is not
    limited to use inside methods: under the hood it searches the stack