classification
Title: Confusing documentation in the urllib2 HOWTO
Type: Stage: resolved
Components: Documentation Versions: Python 2.7
process
Status: closed Resolution: wont fix
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, michael.foord, mingus, orsenthil, r.david.murray
Priority: normal Keywords:

Created on 2013-09-03 17:30 by mingus, last changed 2013-09-03 22:37 by michael.foord. This issue is now closed.

Messages (6)
msg196854 - (view) Author: Brian Mingus (mingus) Date: 2013-09-03 17:30
The python documentation links to an outside website for info and examples on http basic auth. This documentation is terrible and confusing. The link should be removed, and user's should be advised to use the Requests library.


# this example is from http://www.voidspace.org.uk/python/articles/authentication.shtml
# which is linked to by the official python docs http://docs.python.org/2/howto/urllib2.html

import urllib2
 
theurl = 'http://www.someserver.com/toplevelurl/somepage.htm'
username = 'johnny'
password = 'XXXXXX'
# a great password
 
passman = urllib2.HTTPPasswordMgrWithDefaultRealm()
# this creates a password manager
passman.add_password(None, theurl, username, password)
# because we have put None at the start it will always
# use this username/password combination for  urls
# for which `theurl` is a super-url
 
authhandler = urllib2.HTTPBasicAuthHandler(passman)
# create the AuthHandler
 
opener = urllib2.build_opener(authhandler)
 
urllib2.install_opener(opener)
# All calls to urllib2.urlopen will now use our handler
# Make sure not to include the protocol in with the URL, or
# HTTPPasswordMgrWithDefaultRealm will be very confused.
# You must (of course) use it when fetching the page though.
 
pagehandle = urllib2.urlopen(theurl)
# authentication is now handled automatically for us
msg196865 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2013-09-03 19:00
Suggesting using a 3rd party library in order to explain how to use the python standard library to do something isn't going to work.

Would you like to propose an alternate article or an improvement to the howto, using only stdlib facilities?

(Note that the external web page linked to is that of an active Python core contributor.)
msg196866 - (view) Author: Brian Mingus (mingus) Date: 2013-09-03 19:02
The documentation is confusing. Consider this comment:

# All calls to urllib2.urlopen will now use our handler
# Make sure not to include the protocol in with the URL, or
# HTTPPasswordMgrWithDefaultRealm will be very confused.
# You must (of course) use it when fetching the page though.

In the actual code he provides, he uses the protocol. Furthermore, before showing a simple way to use the libary, he shows a godawfully complex way. 

Either the documentation should made beautiful and comprehensible, or it should not be linked to.
msg196867 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2013-09-03 19:12
The article is *explaining* basic auth, thus the pedegogy of the presentation, and why it is a "see also" and not part of the docs proper.

I'll admit I don't understand the first part of that comment, since the second part says you do have to put the protocol in the URL, which is what the example does.

As I said, would you care to propose a replacement?
msg196868 - (view) Author: Brian Mingus (mingus) Date: 2013-09-03 19:14
Yes - this link was a waste of my time. It would have been better if it had not been there. I propose to replace it with nothing.
msg196875 - (view) Author: Michael Foord (michael.foord) * (Python committer) Date: 2013-09-03 22:37
As David explained, the linked article *explains* basic auth as well as showing how to use the standard library support. I think the article is still of some value, it has certainly been useful to many people.
History
Date User Action Args
2013-09-03 22:37:30michael.foordsetstatus: open -> closed
resolution: wont fix
messages: + msg196875

stage: resolved
2013-09-03 20:31:09orsenthilsetnosy: + orsenthil
2013-09-03 19:14:09mingussetmessages: + msg196868
2013-09-03 19:12:02r.david.murraysetmessages: + msg196867
2013-09-03 19:02:28mingussetmessages: + msg196866
2013-09-03 19:00:37r.david.murraysetnosy: + r.david.murray
messages: + msg196865
2013-09-03 18:16:41ned.deilysetnosy: + michael.foord

title: Python docs link to terrible outsi -> Confusing documentation in the urllib2 HOWTO
2013-09-03 17:30:20minguscreate