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

11 files changed, 111 insertions, 57 deletions

diff --git a/Doc/Makefile b/Doc/Makefile
index 0cbd93f..77b84f5 100644
--- a/Doc/Makefile
+++ b/Doc/Makefile
@@ -9,22 +9,23 @@ SVNROOT      = http://svn.python.org/projects
 SPHINXOPTS   =
 PAPER        =
 SOURCES      =
+DISTVERSION  =
 
 ALLSPHINXOPTS = -b $(BUILDER) -d build/doctrees -D latex_paper_size=$(PAPER) \
                 $(SPHINXOPTS) . build/$(BUILDER) $(SOURCES)
 
-.PHONY: help checkout update build html web htmlhelp clean coverage
+.PHONY: help checkout update build html htmlhelp clean coverage dist
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
 	@echo "  html      to make standalone HTML files"
-	@echo "  web       to make file usable by Sphinx.web"
 	@echo "  htmlhelp  to make HTML files and a HTML help project"
 	@echo "  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
 	@echo "  text      to make plain text files"
 	@echo "  changes   to make an overview over all changed/added/deprecated items"
 	@echo "  linkcheck to check all external links for integrity"
 	@echo "  coverage  to check documentation coverage for library and C API"
+	@echo "  dist      to create a \"dist\" directory with archived docs for download"
 
 checkout:
 	@if [ ! -d tools/sphinx ]; then \
@@ -59,12 +60,6 @@ html: BUILDER = html
 html: build
 	@echo "Build finished. The HTML pages are in build/html."
 
-web: BUILDER = web
-web: build
-	@echo "Build finished; now you can run"
-	@echo "  PYTHONPATH=tools $(PYTHON) -m sphinx.web build/web"
-	@echo "to start the server."
-
 htmlhelp: BUILDER = htmlhelp
 htmlhelp: build
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
@@ -105,6 +100,44 @@ pydoc-topics: build
 
 htmlview: html
 	 $(PYTHON) -c "import webbrowser; webbrowser.open('build/html/index.html')"
+
 clean:
 	-rm -rf build/*
 	-rm -rf tools/sphinx
+
+dist:
+	-rm -rf dist
+	mkdir -p dist
+
+	# archive the HTML
+	make html
+	cp -a build/html dist/python$(DISTVERSION)-docs-html
+	tar -C dist -cf dist/python$(DISTVERSION)-docs-html.tar python$(DISTVERSION)-docs-html
+	bzip2 -9 -k dist/python$(DISTVERSION)-docs-html.tar
+	(cd dist; zip -q -r -9 python$(DISTVERSION)-docs-html.zip python$(DISTVERSION)-docs-html)
+	rm -r dist/python$(DISTVERSION)-docs-html
+	rm dist/python$(DISTVERSION)-docs-html.tar
+
+	# archive the text build
+	make text
+	cp -a build/text dist/python$(DISTVERSION)-docs-text
+	tar -C dist -cf dist/python$(DISTVERSION)-docs-text.tar python$(DISTVERSION)-docs-text
+	bzip2 -9 -k dist/python$(DISTVERSION)-docs-text.tar
+	(cd dist; zip -q -r -9 python$(DISTVERSION)-docs-text.zip python$(DISTVERSION)-docs-text)
+	rm -r dist/python$(DISTVERSION)-docs-text
+	rm dist/python$(DISTVERSION)-docs-text.tar
+	
+	# archive the A4 latex
+	-rm -r build/latex
+	make latex PAPER=a4
+	(cd build/latex; make clean && make all-pdf && make FMT=pdf zip bz2)
+	cp build/latex/docs-pdf.zip dist/python$(DISTVERSION)-docs-pdf-a4.zip
+	cp build/latex/docs-pdf.tar.bz2 dist/python$(DISTVERSION)-docs-pdf-a4.tar.bz2
+
+	# archive the letter latex
+	rm -r build/latex
+	make latex PAPER=letter
+	(cd build/latex; make clean && make all-pdf && make FMT=pdf zip bz2)
+	cp build/latex/docs-pdf.zip dist/python$(DISTVERSION)-docs-pdf-letter.zip
+	cp build/latex/docs-pdf.tar.bz2 dist/python$(DISTVERSION)-docs-pdf-letter.tar.bz2
+
diff --git a/Doc/README.txt b/Doc/README.txt
index fc263f0..03729f6 100644
--- a/Doc/README.txt
+++ b/Doc/README.txt
@@ -43,9 +43,6 @@ Available make targets are:
 
  * "html", which builds standalone HTML files for offline viewing.
 
- * "web", which builds files usable with the Sphinx.web application (used to
-   serve the docs online at http://docs.python.org/).
-
  * "htmlhelp", which builds HTML files and a HTML Help project file usable to
    convert them into a single Compiled HTML (.chm) file -- these are popular
    under Microsoft Windows, but very handy on every platform.
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`.
diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst
index 4fe92ff..9cf0bea 100644
--- a/Doc/reference/simple_stmts.rst
+++ b/Doc/reference/simple_stmts.rst
@@ -247,7 +247,7 @@ operation and an assignment statement:
 
 .. productionlist::
    augmented_assignment_stmt: `target` `augop` (`expression_list` | `yield_expression`)
-   augop: "+=" | "-=" | "*=" | "/=" | "%=" | "**="
+   augop: "+=" | "-=" | "*=" | "/=" | "//=" | "%=" | "**="
         : | ">>=" | "<<=" | "&=" | "^=" | "|="
 
 (See section :ref:`primaries` for the syntax definitions for the last three
diff --git a/Doc/tools/sphinxext/download.html b/Doc/tools/sphinxext/download.html
index a634f09..193a82b 100644
--- a/Doc/tools/sphinxext/download.html
+++ b/Doc/tools/sphinxext/download.html
@@ -1,21 +1,37 @@
 {% extends "layout.html" %}
 {% set title = 'Download' %}
+{% set dlbase = 'http://docs.python.org/ftp/python/doc/' + release %}
 {% block body %}
 
 <h1>Download Python {{ release }} Documentation
   {%- if last_updated %} (last updated on {{ last_updated }}){% endif %}</h1>
 
-<p>Currently, the development documentation isn't packaged for download.</p>
-
-<!--
 <p>To download an archive containing all the documents for this version of
 Python in one of various formats, follow one of links in this table. The numbers
 in the table are the size of the download files in Kilobytes.</p>
 
-{# XXX download links #}
-
-
-<p>These archives contain all the content in the documentation section.</p>
+<table class="docutils">
+  <tr><th>Format</th><th>Packed as .zip</th><th>Packed as .tar.bz2</th></tr>
+  <tr><td>PDF (US-Letter paper size)</td>
+    <td><a href="{{ dlbase }}/python-docs-pdf-letter.zip">Download</a> (ca. 8 MB)</td>
+    <td><a href="{{ dlbase }}/python-docs-pdf-letter.tar.bz2">Download</a> (ca. 8 MB)</td>
+  </tr>
+  <tr><td>PDF (A4 paper size)</td>
+    <td><a href="{{ dlbase }}/python-docs-pdf-a4.zip">Download</a> (ca. 8 MB)</td>
+    <td><a href="{{ dlbase }}/python-docs-pdf-a4.tar.bz2">Download</a> (ca. 8 MB)</td>
+  </tr>
+  <tr><td>HTML</td>
+    <td><a href="{{ dlbase }}/python-docs-html.zip">Download</a> (ca. 6 MB)</td>
+    <td><a href="{{ dlbase }}/python-docs-html.tar.bz2">Download</a> (ca. 4 MB)</td>
+  </tr>
+  <tr><td>Plain Text</td>
+    <td><a href="{{ dlbase }}/python-docs-pdf-text.zip">Download</a> (ca. 2 MB)</td>
+    <td><a href="{{ dlbase }}/python-docs-pdf-text.tar.bz2">Download</a> (ca. 1.5 MB)</td>
+  </tr>
+</table>
+
+
+<p>These archives contain all the content in the documentation.</p>
 
 <h2>Unpacking</h2>
 
@@ -26,15 +42,7 @@ used to handle the ZIP archives if desired. The .tar.bz2 archives provide the
 best compression and fastest download times.</p>
 
 <p>Windows users can use the ZIP archives since those are customary on that
-platform. These are created on Unix using the InfoZIP zip program. They may be
-unpacked using the free WiZ tool (from the InfoZIP developers) or any other
-tool for handling ZIP archives; any of them should work.</p>
-
-<p>Note that the .tar.bz2 files are smaller than the other archives; Windows
-users may want to install the bzip2 tools on their systems as well. Windows
-binaries for a command-line tool are available at <a
-href="http://www.bzip.org">The bzip2 and libbzip2 official home page</a>, but
-most other archiving utilities support the tar and bzip2 formats as well.</p>
+platform. These are created on Unix using the InfoZIP zip program.</p>
 
 
 <h2>Problems</h2>
@@ -42,6 +50,4 @@ most other archiving utilities support the tar and bzip2 formats as well.</p>
 <p>If you have comments or suggestions for the Python documentation, please send
 email to <a href="docs@python.org">docs@python.org</a>.</p>
 
--->
-
 {% endblock %}
diff --git a/Doc/using/windows.rst b/Doc/using/windows.rst
index 2dd236f..aa24933 100644
--- a/Doc/using/windows.rst
+++ b/Doc/using/windows.rst
@@ -140,7 +140,7 @@ directory of your Python distribution, delimited by a semicolon from other
 entries.  An example variable could look like this (assuming the first two
 entries are Windows' default)::
 
-    C:\WINNT\system32;C:\WINNT;C:\Python25
+    C:\WINDOWS\system32;C:\WINDOWS;C:\Python25
 
 Typing :command:`python` on your command prompt will now fire up the Python
 interpreter.  Thus, you can also execute your scripts with command line options,
@@ -276,11 +276,11 @@ releases are built, the source tree contains solutions/project files.  View the
 +====================+==============+=======================+
 | :file:`PC/VC6/`    | 6.0          | 97                    |
 +--------------------+--------------+-----------------------+
-| :file:`PCbuild/`   | 7.1          | 2003                  |
+| :file:`PC/VS7.1/`  | 7.1          | 2003                  |
 +--------------------+--------------+-----------------------+
-| :file:`PCbuild8/`  | 8.0          | 2005                  |
+| :file:`PC/VS8.0/`  | 8.0          | 2005                  |
 +--------------------+--------------+-----------------------+
-| :file:`PCbuild9/`  | 9.0          | 2008                  |
+| :file:`PCbuild/`   | 9.0          | 2008                  |
 +--------------------+--------------+-----------------------+
 
 Note that not all of these build directories are fully supported.  Read the
diff --git a/Doc/whatsnew/2.6.rst b/Doc/whatsnew/2.6.rst
index 04a54a2..9410e22 100644
--- a/Doc/whatsnew/2.6.rst
+++ b/Doc/whatsnew/2.6.rst
@@ -2453,18 +2453,18 @@ changes, or look through the Subversion logs for all the details.
   by calling :func:`sys.getprofile` and :func:`sys.gettrace`.
   (Contributed by Georg Brandl; :issue:`1648`.)
 
-* The :mod:`tarfile` module now supports POSIX.1-2001 (pax) and
-  POSIX.1-1988 (ustar) format tarfiles, in addition to the GNU tar
-  format that was already supported.  The default format
-  is GNU tar; specify the ``format`` parameter to open a file
-  using a different format::
+* The :mod:`tarfile` module now supports POSIX.1-2001 (pax) tarfiles in
+  addition to the POSIX.1-1988 (ustar) and GNU tar formats that were
+  already supported.  The default format is GNU tar; specify the
+  ``format`` parameter to open a file using a different format::
 
     tar = tarfile.open("output.tar", "w",
                        format=tarfile.PAX_FORMAT)
 
-  The new ``errors`` parameter specifies an error handling scheme for
-  character conversions.  ``'strict'``, ``'ignore'``, and
-  ``'replace'`` are the three standard ways Python can handle errors,;
+  The new ``encoding`` and ``errors`` parameters specify an encoding and
+  an error handling scheme for character conversions.  ``'strict'``,
+  ``'ignore'``, and ``'replace'`` are the three standard ways Python can
+  handle errors,;
   ``'utf-8'`` is a special value that replaces bad characters with
   their UTF-8 representation.  (Character conversions occur because the
   PAX format supports Unicode filenames, defaulting to UTF-8 encoding.)