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.
........

5 files changed, 33 insertions, 15 deletions

diff --git a/Doc/library/asynchat.rst b/Doc/library/asynchat.rst
index e8a84b1..d4894ea 100644
--- a/Doc/library/asynchat.rst
+++ b/Doc/library/asynchat.rst
@@ -278,8 +278,8 @@ any extraneous data sent by the web client are ignored. ::
 
    class http_request_handler(asynchat.async_chat):
 
-       def __init__(self, conn, addr, sessions, log):
-           asynchat.async_chat.__init__(self, conn=conn)
+       def __init__(self, sock, addr, sessions, log):
+           asynchat.async_chat.__init__(self, sock=sock)
            self.addr = addr
            self.sessions = sessions
            self.ibuffer = []
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
diff --git a/Doc/library/random.rst b/Doc/library/random.rst
index 66db882..da0e663 100644
--- a/Doc/library/random.rst
+++ b/Doc/library/random.rst
@@ -149,7 +149,8 @@ be found in any statistics text.
 
 .. function:: uniform(a, b)
 
-   Return a random floating point number *N* such that ``a <= N < b``.
+   Return a random floating point number *N* such that ``a <= N < b`` for
+   ``a <= b`` and ``b <= N < a`` for ``b < a``.
 
 
 .. function:: triangular(low, high, mode)
diff --git a/Doc/library/select.rst b/Doc/library/select.rst
index bf33c92..8b466cf 100644
--- a/Doc/library/select.rst
+++ b/Doc/library/select.rst
@@ -46,7 +46,7 @@ The module defines the following:
    :ref:`kqueue-objects` below for the methods supported by kqueue objects.
 
 
-.. function:: kqueue(ident, filter=KQ_FILTER_READ, flags=KQ_ADD, fflags=0, data=0, udata=0)
+.. function:: kevent(ident, filter=KQ_FILTER_READ, flags=KQ_ADD, fflags=0, data=0, udata=0)
 
    (Only supported on BSD.)  Returns a kernel event object object; see section
    :ref:`kevent-objects` below for the methods supported by kqueue objects.
@@ -264,12 +264,12 @@ Kqueue Objects
    Return the file descriptor number of the control fd.
 
 
-.. method:: epoll.fromfd(fd)
+.. method:: kqueue.fromfd(fd)
 
    Create a kqueue object from a given file descriptor.
 
 
-.. method:: control(changelist, max_events=0[, timeout=None]) -> eventlist
+.. method:: kqueue.control(changelist, max_events[, timeout=None]) -> eventlist
 
    Low level interface to kevent
 
diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst
index 5efcc32..4ffafb0 100644
--- a/Doc/library/unittest.rst
+++ b/Doc/library/unittest.rst
@@ -591,7 +591,8 @@ failures.
             TestCase.failUnlessAlmostEqual(first, second[, places[, msg]])
 
    Test that *first* and *second* are approximately equal by computing the
-   difference, rounding to the given number of *places*, and comparing to zero.
+   difference, rounding to the given number of decimal *places* (default 7), 
+   and comparing to zero.
    Note that comparing a given number of decimal places is not the same as
    comparing a given number of significant digits. If the values do not compare
    equal, the test will fail with the explanation given by *msg*, or :const:`None`.
@@ -601,7 +602,8 @@ failures.
             TestCase.failIfAlmostEqual(first, second[, places[, msg]])
 
    Test that *first* and *second* are not approximately equal by computing the
-   difference, rounding to the given number of *places*, and comparing to zero.
+   difference, rounding to the given number of decimal *places* (default 7), 
+   and comparing to zero.
    Note that comparing a given number of decimal places is not the same as
    comparing a given number of significant digits. If the values do not compare
    equal, the test will fail with the explanation given by *msg*, or :const:`None`.