[issue11448] docs for HTTPConnection.set_tunnel are ambiguous

[Roundup Robot]

Roundup Robot added the comment:

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

--
nosy: +python-dev
resolution:  - fixed
stage:  - committed/rejected
status: open - closed

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11448
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11448] docs for HTTPConnection.set_tunnel are ambiguous

[Nikolaus Rath]

Nikolaus Rath added the comment:

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.

--
Added file: http://bugs.python.org/file33674/issue11448_r3.patch

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11448
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11448] docs for HTTPConnection.set_tunnel are ambiguous

[Nikolaus Rath]

Nikolaus Rath added the comment:

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.

--
nosy: +ezio.melotti, georg.brandl
versions:  -Python 3.5
Added file: http://bugs.python.org/file33609/issue11448_r2.patch

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11448
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11448] docs for HTTPConnection.set_tunnel are ambiguous

[Georg Brandl]

Georg Brandl added the comment:

The first sentence of the second new paragraph is a bit ungrammatical, right?

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11448
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11448] docs for HTTPConnection.set_tunnel are ambiguous

[karl]

karl added the comment:

ooops right, my bad.

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

better?

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11448
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11448] docs for HTTPConnection.set_tunnel are ambiguous

[Nikolaus Rath]

Nikolaus Rath added the comment:

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.

--
nosy: +Nikratio

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11448
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11448] docs for HTTPConnection.set_tunnel are ambiguous

[Nikolaus Rath]

Changes by Nikolaus Rath nikol...@rath.org:


--
type:  - enhancement
versions: +Python 3.4, Python 3.5

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11448
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11448] docs for HTTPConnection.set_tunnel are ambiguous

[karl]

karl added the comment:

Ah thanks Eric, I will fix that.

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11448
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11448] docs for HTTPConnection.set_tunnel are ambiguous

[karl]

karl added the comment:

ok made a proper patch on the rst file with hg diff.
See issue-11448-1.patch

--
Added file: http://bugs.python.org/file29293/issue-11448-1.patch

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11448
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11448] docs for HTTPConnection.set_tunnel are ambiguous

[Éric Araujo]

Éric Araujo added the comment:

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

--
nosy: +eric.araujo

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11448
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11448] docs for HTTPConnection.set_tunnel are ambiguous

[karl]

karl added the comment:

This is a possible additional example for set_tunnel, modification of 
python3.3/html/_sources/library/http.client.txt

Hope it helps.

--
nosy: +karlcow
Added file: http://bugs.python.org/file29243/http.client.patch

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11448
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11448] docs for HTTPConnection.set_tunnel are ambiguous

[Michael Stahn]

Michael Stahn added the comment:

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..

--
nosy: +m1kes

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11448
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11448] docs for HTTPConnection.set_tunnel are ambiguous

[Ryan Kelly]

New submission from Ryan Kelly r...@rfk.id.au:

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.

--
assignee: docs@python
components: Documentation
files: set_tunnel_doc.diff
keywords: patch
messages: 130396
nosy: docs@python, rfk
priority: normal
severity: normal
status: open
title: docs for HTTPConnection.set_tunnel are ambiguous
versions: Python 3.3
Added file: http://bugs.python.org/file21056/set_tunnel_doc.diff

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11448
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11448] docs for HTTPConnection.set_tunnel are ambiguous

[Senthil Kumaran]

Senthil Kumaran orsent...@gmail.com added the comment:

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?

--
assignee: docs@python - orsenthil
nosy: +orsenthil

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue11448
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue11448] docs for HTTPConnection.set_tunnel are ambiguous

[Ryan Kelly]

Ryan Kelly r...@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 rep...@bugs.python.org
http://bugs.python.org/issue11448
___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com