From a48d9eaa5ccb3d8d0e224e78471bd660605116ec Mon Sep 17 00:00:00 2001 From: Benjamin Peterson Date: Sun, 16 Mar 2014 15:55:39 -0500 Subject: improve set_tunnel docs (closes #11448) Patch by Ryan Kelly, karl, and Nikolaus Rath. --- Doc/library/http.client.rst | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/Doc/library/http.client.rst b/Doc/library/http.client.rst index 783a596..bb30f24 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 -- cgit v0.12