[docs] [issue11448] docs for HTTPConnection.set_tunnel are ambiguous

[Ryan Kelly]

Ryan Kelly <ryan at rfk.id.au> added the comment:

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 :-)

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue11448>
_______________________________________