Merged default into 3.4 branch. 3.4 branch is now effectively 3.4.1rc1.

7 files changed, 57 insertions, 138 deletions

diff --git a/Doc/Makefile b/Doc/Makefile
index 82f5bef..d85fb94 100644
--- a/Doc/Makefile
+++ b/Doc/Makefile
@@ -5,7 +5,7 @@
 
 # You can set these variables from the command line.
 PYTHON       = python
-SVNROOT      = http://svn.python.org/projects
+SPHINXBUILD  = sphinx-build
 SPHINXOPTS   =
 PAPER        =
 SOURCES      =
@@ -14,14 +14,13 @@ DISTVERSION  = $(shell $(PYTHON) tools/sphinxext/patchlevel.py)
 ALLSPHINXOPTS = -b $(BUILDER) -d build/doctrees -D latex_paper_size=$(PAPER) \
                 $(SPHINXOPTS) . build/$(BUILDER) $(SOURCES)
 
-.PHONY: help checkout update build html htmlhelp latex text changes linkcheck \
+.PHONY: help build html htmlhelp latex text changes linkcheck \
 	suspicious coverage doctest pydoc-topics htmlview clean dist check serve \
 	autobuild-dev autobuild-stable
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
 	@echo "  clean      to remove build files"
-	@echo "  update     to update build tools"
 	@echo "  html       to make standalone HTML files"
 	@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"
@@ -37,30 +36,8 @@ help:
 	@echo "  check      to run a check for frequent markup errors"
 	@echo "  serve      to serve the documentation on the localhost (8000)"
 
-# Note: if you update versions here, do the same in make.bat and README.txt
-checkout:
-	@if [ ! -d tools/sphinx ]; then \
-	  echo "Checking out Sphinx..."; \
-	  svn checkout $(SVNROOT)/external/Sphinx-1.2/sphinx tools/sphinx; \
-	fi
-	@if [ ! -d tools/docutils ]; then \
-	  echo "Checking out Docutils..."; \
-	  svn checkout $(SVNROOT)/external/docutils-0.11/docutils tools/docutils; \
-	fi
-	@if [ ! -d tools/jinja2 ]; then \
-	  echo "Checking out Jinja..."; \
-	  svn checkout $(SVNROOT)/external/Jinja-2.3.1/jinja2 tools/jinja2; \
-	fi
-	@if [ ! -d tools/pygments ]; then \
-	  echo "Checking out Pygments..."; \
-	  svn checkout $(SVNROOT)/external/Pygments-1.6/pygments tools/pygments; \
-	fi
-
-update: clean checkout
-
-build: checkout
-	mkdir -p build/$(BUILDER) build/doctrees
-	$(PYTHON) tools/sphinx-build.py $(ALLSPHINXOPTS)
+build:
+	$(SPHINXBUILD) $(ALLSPHINXOPTS)
 	@echo
 
 html: BUILDER = html
@@ -120,10 +97,6 @@ htmlview: html
 
 clean:
 	-rm -rf build/*
-	-rm -rf tools/sphinx
-	-rm -rf tools/pygments
-	-rm -rf tools/jinja2
-	-rm -rf tools/docutils
 
 dist:
 	rm -rf dist
@@ -184,7 +157,6 @@ serve:
 
 # for development releases: always build
 autobuild-dev:
-	make update
 	make dist SPHINXOPTS='-A daily=1 -A versionswitcher=1'
 	-make suspicious
 
diff --git a/Doc/README.txt b/Doc/README.txt
index 4a157d5..f4f6d81 100644
--- a/Doc/README.txt
+++ b/Doc/README.txt
@@ -3,36 +3,34 @@ Python Documentation README
 
 This directory contains the reStructuredText (reST) sources to the Python
 documentation.  You don't need to build them yourself, prebuilt versions are
-available at http://docs.python.org/download/.
+available at <http://docs.python.org/download/>.
 
 Documentation on the authoring Python documentation, including information about
 both style and markup, is available in the "Documenting Python" chapter of the
-developers guide (http://docs.python.org/devguide/documenting.html).
-There's also a chapter intended to point out differences to
-those familiar with the previous docs written in LaTeX.
+developers guide <http://docs.python.org/devguide/documenting.html>.
 
 
 Building the docs
 =================
 
-You need to have Python 2.4 or higher installed; the toolset used to build the
-docs is written in Python.  It is called *Sphinx*, it is not included in this
-tree, but maintained separately.  Also needed are the docutils, supplying the
-base markup that Sphinx uses, Jinja, a templating engine, and optionally
-Pygments, a code highlighter.
+You need to have Sphinx <http://sphinx-doc.org/> installed; it is the toolset
+used to build the docs.  It is not included in this tree, but maintained
+separately and available from PyPI <http://pypi.python.org/pypi/Sphinx>.
 
 
 Using make
 ----------
 
-Luckily, a Makefile has been prepared so that on Unix, provided you have
-installed Python and Subversion, you can just run ::
+A Makefile has been prepared so that on Unix, provided you have installed
+Sphinx, you can just run ::
 
    make html
 
-to check out the necessary toolset in the `tools/` subdirectory and build the
-HTML output files.  To view the generated HTML, point your favorite browser at
-the top-level index `build/html/index.html` after running "make".
+to build the HTML output files.  To view the generated HTML, point your favorite
+browser at the top-level index `build/html/index.html` after running "make".
+
+On Windows, we try to emulate the Makefile as closely as possible with a
+``make.bat`` file.
 
 To use a Python interpreter that's not called ``python``, use the standard
 way to set Makefile variables, using e.g. ::
@@ -74,43 +72,21 @@ Available make targets are:
    `tools/sphinxext/pyspecific.py` -- pydoc needs these to show topic and
    keyword help.
 
-A "make update" updates the Subversion checkouts in `tools/`.
+ * "suspicious", which checks the parsed markup for text that looks like
+   malformed and thus unconverted reST.
 
 
 Without make
 ------------
 
-You'll need to install the Sphinx package, either by checking it out via ::
-
-   svn co http://svn.python.org/projects/external/Sphinx-1.0.7/sphinx tools/sphinx
-
-or by installing it from PyPI.
-
-Then, you need to install Docutils, either by checking it out via ::
-
-   svn co http://svn.python.org/projects/external/docutils-0.6/docutils tools/docutils
-
-or by installing it from http://docutils.sf.net/.
-
-You also need Jinja2, either by checking it out via ::
-
-   svn co http://svn.python.org/projects/external/Jinja-2.3.1/jinja2 tools/jinja2
-
-or by installing it from PyPI.
-
-You can optionally also install Pygments, either as a checkout via ::
-
-   svn co http://svn.python.org/projects/external/Pygments-1.3.1/pygments tools/pygments
-
-or from PyPI at http://pypi.python.org/pypi/Pygments.
-
+Install the Sphinx package and its dependencies from PyPI.
 
-Then, make an output directory, e.g. under `build/`, and run ::
+Then, from the ``Docs`` directory, run ::
 
-   python tools/sphinx-build.py -b<builder> . build/<outputdirectory>
+   sphinx-build -b<builder> . build/<builder>
 
-where `<builder>` is one of html, text, latex, or htmlhelp (for explanations see
-the make targets above).
+where ``<builder>`` is one of html, text, latex, or htmlhelp (for explanations
+see the make targets above).
 
 
 Contributing
diff --git a/Doc/library/asyncio-subprocess.rst b/Doc/library/asyncio-subprocess.rst
index 861bcc0..44ef504 100644
--- a/Doc/library/asyncio-subprocess.rst
+++ b/Doc/library/asyncio-subprocess.rst
@@ -107,6 +107,8 @@ Process
          The data read is buffered in memory, so do not use this method if the
          data size is large or unlimited.
 
+      This method is a :ref:`coroutine <coroutine>`.
+
    .. method:: kill()
 
       Kills the child. On Posix OSs the function sends :py:data:`SIGKILL` to
@@ -129,11 +131,13 @@ Process
       to the child. On Windows the Win32 API function
       :c:func:`TerminateProcess` is called to stop the child.
 
-   .. method:: wait(self):
+   .. method:: wait():
 
       Wait for child process to terminate.  Set and return :attr:`returncode`
       attribute.
 
+      This method is a :ref:`coroutine <coroutine>`.
+
 
 Example
 -------
diff --git a/Doc/library/http.client.rst b/Doc/library/http.client.rst
index d4cdfd3..8ece400 100644
--- a/Doc/library/http.client.rst
+++ b/Doc/library/http.client.rst
@@ -451,11 +451,25 @@ HTTPConnection Objects
 
 .. method:: HTTPConnection.set_tunnel(host, port=None, headers=None)
 
-   Set the host and the port for HTTP Connect Tunnelling. Normally used when it
-   is required to a HTTPS Connection through a proxy server.
+   Set the host and the port for HTTP Connect Tunnelling. This allows running
+   the connection through a proxy server.
 
-   The headers argument should be a mapping of extra HTTP headers to send
-   with the CONNECT request.
+   The host and port arguments specify the endpoint of the tunneled connection
+   (i.e. the address included in the CONNECT request, *not* the address of the
+   proxy server).
+
+   The headers argument should be a mapping of extra HTTP headers to send with
+   the CONNECT request.
+
+   For example, to tunnel through a HTTPS proxy server running locally on port
+   8080, we would pass the address of the proxy to the :class:`HTTPSConnection`
+   constructor, and the address of the host that we eventually want to reach to
+   the :meth:`~HTTPConnection.set_tunnel` method::
+
+      >>> import http.client
+      >>> conn = http.client.HTTPSConnection("localhost", 8080)
+      >>> conn.set_tunnel("www.python.org")
+      >>> conn.request("HEAD","/index.html")
 
    .. versionadded:: 3.2
 
diff --git a/Doc/make.bat b/Doc/make.bat
index d6f7074..0b5b56e 100644
--- a/Doc/make.bat
+++ b/Doc/make.bat
@@ -1,7 +1,6 @@
 @@echo off
 setlocal
 
-set SVNROOT=http://svn.python.org/projects
 if "%PYTHON%" EQU "" set PYTHON=py -2
 if "%HTMLHELP%" EQU "" set HTMLHELP=%ProgramFiles%\HTML Help Workshop\hhc.exe
 if "%DISTVERSION%" EQU "" for /f "usebackq" %%v in (`%PYTHON% tools/sphinxext/patchlevel.py`) do set DISTVERSION=%%v
@@ -14,15 +13,11 @@ if "%1" EQU "text" goto build
 if "%1" EQU "suspicious" goto build
 if "%1" EQU "linkcheck" goto build
 if "%1" EQU "changes" goto build
-if "%1" EQU "checkout" goto checkout
-if "%1" EQU "update" goto update
 
 :help
 set this=%~n0
 echo HELP
 echo.
-echo %this% checkout
-echo %this% update
 echo %this% html
 echo %this% htmlhelp
 echo %this% latex
@@ -33,20 +28,6 @@ echo %this% changes
 echo.
 goto end
 
-:checkout
-svn co %SVNROOT%/external/Sphinx-1.2/sphinx tools/sphinx
-svn co %SVNROOT%/external/docutils-0.11/docutils tools/docutils
-svn co %SVNROOT%/external/Jinja-2.3.1/jinja2 tools/jinja2
-svn co %SVNROOT%/external/Pygments-1.6/pygments tools/pygments
-goto end
-
-:update
-svn update tools/sphinx
-svn update tools/docutils
-svn update tools/jinja2
-svn update tools/pygments
-goto end
-
 :build
 if not exist build mkdir build
 if not exist build\%1 mkdir build\%1
diff --git a/Doc/tools/sphinx-build.py b/Doc/tools/sphinx-build.py
deleted file mode 100644
index a446dfa..0000000
--- a/Doc/tools/sphinx-build.py
+++ /dev/null
@@ -1,28 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-    Sphinx - Python documentation toolchain
-    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-    :copyright: 2007-2010 by Georg Brandl.
-    :license: Python license.
-"""
-
-import sys
-import warnings
-
-# Get rid of UserWarnings reported by pkg_resources.
-warnings.filterwarnings('ignore', category=UserWarning, module='jinja2')
-
-if __name__ == '__main__':
-
-    if sys.version_info[:3] < (2, 4, 0) or sys.version_info[:3] > (3, 0, 0):
-        sys.stderr.write("""\
-Error: Sphinx needs to be executed with Python 2.4 or newer (not 3.0 though).
-(If you run this from the Makefile, you can set the PYTHON variable
-to the path of an alternative interpreter executable, e.g.,
-``make html PYTHON=python2.5``).
-""")
-        sys.exit(1)
-
-    from sphinx import main
-    sys.exit(main(sys.argv))
diff --git a/Doc/tools/sphinxext/pyspecific.py b/Doc/tools/sphinxext/pyspecific.py
index 4e41446..31d8c06 100644
--- a/Doc/tools/sphinxext/pyspecific.py
+++ b/Doc/tools/sphinxext/pyspecific.py
@@ -16,6 +16,7 @@ from docutils import nodes, utils
 
 import sphinx
 from sphinx.util.nodes import split_explicit_title
+from sphinx.util.compat import Directive
 from sphinx.writers.html import HTMLTranslator
 from sphinx.writers.latex import LaTeXTranslator
 from sphinx.locale import versionlabels
@@ -27,7 +28,9 @@ Body.enum.converters['loweralpha'] = \
     Body.enum.converters['lowerroman'] = \
     Body.enum.converters['upperroman'] = lambda x: None
 
-if sphinx.__version__[:3] < '1.2':
+SPHINX11 = sphinx.__version__[:3] < '1.2'
+
+if SPHINX11:
     # monkey-patch HTML translator to give versionmodified paragraphs a class
     def new_visit_versionmodified(self, node):
         self.body.append(self.starttag(node, 'p', CLASS=node['type']))
@@ -88,8 +91,6 @@ def source_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
 
 # Support for marking up implementation details
 
-from sphinx.util.compat import Directive
-
 class ImplementationDetail(Directive):
 
     has_content = True
@@ -142,10 +143,6 @@ class PyDecoratorMethod(PyDecoratorMixin, PyClassmember):
 
 # Support for documenting version of removal in deprecations
 
-from sphinx.locale import versionlabels
-from sphinx.util.compat import Directive
-
-
 class DeprecatedRemoved(Directive):
     has_content = True
     required_arguments = 2
@@ -171,16 +168,16 @@ class DeprecatedRemoved(Directive):
             messages = []
         if self.content:
             self.state.nested_parse(self.content, self.content_offset, node)
-        if len(node):
             if isinstance(node[0], nodes.paragraph) and node[0].rawsource:
                 content = nodes.inline(node[0].rawsource, translatable=True)
                 content.source = node[0].source
                 content.line = node[0].line
                 content += node[0].children
                 node[0].replace_self(nodes.paragraph('', '', content))
-            node[0].insert(0, nodes.inline('', '%s: ' % text,
-                                           classes=['versionmodified']))
-        else:
+            if not SPHINX11:
+                node[0].insert(0, nodes.inline('', '%s: ' % text,
+                                               classes=['versionmodified']))
+        elif not SPHINX11:
             para = nodes.paragraph('', '',
                 nodes.inline('', '%s.' % text, classes=['versionmodified']))
             node.append(para)
@@ -188,6 +185,9 @@ class DeprecatedRemoved(Directive):
         env.note_versionchange('deprecated', version[0], node, self.lineno)
         return [node] + messages
 
+# for Sphinx < 1.2
+versionlabels['deprecated-removed'] = DeprecatedRemoved._label
+
 
 # Support for including Misc/NEWS