[Python-checkins] cpython (3.3): improve set_tunnel docs (closes #11448)

[benjamin.peterson]

http://hg.python.org/cpython/rev/68a257ca6be6
changeset:   89690:68a257ca6be6
branch:      3.3
parent:      89686:2150053d77ca
user:        Benjamin Peterson <benjamin at python.org>
date:        Sun Mar 16 15:55:39 2014 -0500
summary:
  improve set_tunnel docs (closes #11448)

Patch by Ryan Kelly, karl, and Nikolaus Rath.

files:
  Doc/library/http.client.rst |  22 ++++++++++++++++++----
  1 files changed, 18 insertions(+), 4 deletions(-)


diff --git a/Doc/library/http.client.rst b/Doc/library/http.client.rst
--- a/Doc/library/http.client.rst
+++ b/Doc/library/http.client.rst
@@ -451,11 +451,25 @@
 
 .. 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
 

-- 
Repository URL: http://hg.python.org/cpython