classification
Title: docs for HTTPConnection.set_tunnel are ambiguous
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.3, Python 3.4
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: orsenthil Nosy List: docs@python, eric.araujo, ezio.melotti, georg.brandl, karlcow, m1kes, nikratio, orsenthil, python-dev, rfk
Priority: normal Keywords: patch

Created on 2011-03-09 02:08 by rfk, last changed 2014-03-16 20:56 by python-dev. This issue is now closed.

Files
File name Uploaded Description Edit
set_tunnel_doc.diff rfk, 2011-03-09 02:08 set_tunnel docs patch review
http.client.patch karlcow, 2013-02-26 03:15
issue-11448-1.patch karlcow, 2013-03-03 03:31 review
issue11448_r2.patch nikratio, 2014-01-22 04:49 review
issue11448_r3.patch nikratio, 2014-01-24 04:09 review
Messages (14)
msg130396 - (view) Author: Ryan Kelly (rfk) Date: 2011-03-09 02:08
The docs for HTTPConnection.set_tunnel(host,port) are ambiguous.  They simply say "Set the host and the port for HTTP Connect Tunnelling".  But should I specify the address of the server *through* which I want to tunnel, or the address of the *endpoint* of the tunnel?

Turns out it's the latter, but I just wasted an hour "debugging" thinking it was the former :-(

Attached is a simple doc patch to try to clarify this issue.
msg130401 - (view) Author: Senthil Kumaran (orsenthil) * (Python committer) Date: 2011-03-09 02:39
I am not able to understand what you mean by 'endpoint'.

Actually, when using tunnels people understand that they often 'tunnel through' the proxy server and here is an example code from the tests which is going to use the set_tunnel method.

ph = urllib.request.ProxyHandler(dict(https="proxy.example.com:3128"))
o.add_handler(ph)

It is the proxy server and port. (Is 3128 called the endpoint of proxy?)

Could you please provide some more information on your interpretation and the behavior you observed?
msg130413 - (view) Author: Ryan Kelly (rfk) Date: 2011-03-09 03:41
Sorry, "endpoint" is just a noun that seemed to fit for me, I've no idea if there is a standard term for this.  Perhaps "origin server" if you follow the terminology from the RFC?

By way of example, suppose I'm running a proxy on localhost:3128 and I want to tunnel through it to connect to www.example.com:443.

From the train of thought that "I need to tunnel through localhost:3128 to connect to www.example.com:443" my instinct was to write code like this:

  c = HTTPSConnection("www.example.com",443)
  c.set_tunnel("localhost",3128)
  c.send('...etc...')

This doesn't work; it tries to tunnel through www.example.com to get to localhost.  The correct way around is:

  c = HTTPSConnection("localhost",3128)
  c.set_tunnel("www.example.com",443)
  c.send('...etc...')

Another way to put it:  the arguments to set_tunnel are the host/port to tunnel *to*, not the host/port to tunnel *through*.

I was only able to work this out by looking through to code for urllib2.  It's not clear from the docs.  Then again, sounds like my doc patch didn't make things any clearer :-)
msg181665 - (view) Author: Michael Stahn (m1kes) Date: 2013-02-08 10:18
I thought the same as Ryan when reading the API. The best way would have been to call "set_tunnel" -> "set_proxy" and to implement the behaviour you expect on this: setting a proxy. There are some more places at this code which are not quite clear eg:

def putheader(self, header, *values):
  """Send a request header line to the server.

Here the methodname "putheader" is ok but the documentation is misleading: this just adds a new header-line to the buffer, it won't send it directly. But that's the problem with naming in APIs: once it's in the code you won't get it changed that fast..
msg183017 - (view) Author: karl (karlcow) * Date: 2013-02-26 03:15
This is a possible additional example for set_tunnel, modification of python3.3/html/_sources/library/http.client.txt

Hope it helps.
msg183271 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2013-03-01 18:40
> This is a possible additional example for set_tunnel,
Thanks.  In general, our tooling expects unified diffs, such as produced by hg diff.

> modification of python3.3/html/_sources/library/http.client.txt
That’s a copy for web hosting, the real source is in Doc/library/http.client.rst (see devguide for more info).
msg183358 - (view) Author: karl (karlcow) * Date: 2013-03-03 03:19
Ah thanks Eric, I will fix that.
msg183359 - (view) Author: karl (karlcow) * Date: 2013-03-03 03:31
ok made a proper patch on the rst file with hg diff.
See issue-11448-1.patch
msg207665 - (view) Author: Nikolaus Rath (nikratio) * Date: 2014-01-08 04:48
Is there anything that needs to be done to get this patch applied?

It would be nice if this could be committed together with the patch in issue 7776.
msg208748 - (view) Author: Nikolaus Rath (nikratio) * Date: 2014-01-22 04:49
The patches look fine to me. They are only docpatches, so no testcase is needed.

I have rebased them on current hg tip to avoid fuzz, but otherwise left them unchanged.

I think this is ready to be committed.
msg208752 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2014-01-22 06:39
The first sentence of the second new paragraph is a bit ungrammatical, right?
msg208753 - (view) Author: karl (karlcow) * Date: 2014-01-22 07:26
ooops right, my bad.

s/on port 8080. We first/on port 8080, we first/

better?
msg209033 - (view) Author: Nikolaus Rath (nikratio) * Date: 2014-01-24 04:09
Apologies, I missed that. I'll be more careful in the future. I've attached an updated patch that also adds some extra Sphinx markup, but should IMO still be credited to Ryan and Karl.
msg213758 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-03-16 20:56
New changeset 68a257ca6be6 by Benjamin Peterson in branch '3.3':
improve set_tunnel docs (closes #11448)
http://hg.python.org/cpython/rev/68a257ca6be6

New changeset 5cab0ada97b2 by Benjamin Peterson in branch 'default':
merge 3.3 (#11448)
http://hg.python.org/cpython/rev/5cab0ada97b2
History
Date User Action Args
2014-03-16 20:56:35python-devsetstatus: open -> closed

nosy: + python-dev
messages: + msg213758

resolution: fixed
stage: resolved
2014-01-24 04:09:05nikratiosetfiles: + issue11448_r3.patch

messages: + msg209033
2014-01-22 07:26:11karlcowsetmessages: + msg208753
2014-01-22 06:39:43georg.brandlsetmessages: + msg208752
2014-01-22 04:49:16nikratiosetfiles: + issue11448_r2.patch
versions: - Python 3.5
nosy: + georg.brandl, ezio.melotti

messages: + msg208748
2014-01-08 04:48:51nikratiosettype: enhancement
versions: + Python 3.4, Python 3.5
2014-01-08 04:48:27nikratiosetnosy: + nikratio
messages: + msg207665
2013-03-03 03:31:21karlcowsetfiles: + issue-11448-1.patch

messages: + msg183359
2013-03-03 03:19:00karlcowsetmessages: + msg183358
2013-03-01 18:40:42eric.araujosetnosy: + eric.araujo
messages: + msg183271
2013-02-26 03:15:18karlcowsetfiles: + http.client.patch
nosy: + karlcow
messages: + msg183017

2013-02-08 10:18:53m1kessetnosy: + m1kes
messages: + msg181665
2011-03-09 03:41:31rfksetnosy: orsenthil, rfk, docs@python
messages: + msg130413
2011-03-09 02:39:53orsenthilsetassignee: docs@python -> orsenthil

messages: + msg130401
nosy: + orsenthil
2011-03-09 02:08:48rfkcreate