[issue18914] Python docs link to terrible outsi
New submission from Brian Mingus: 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 ---------- assignee: docs@python components: Documentation messages: 196854 nosy: docs@python, mingus priority: normal severity: normal status: open title: Python docs link to terrible outsi versions: Python 2.7 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18914> _______________________________________
Changes by Ned Deily <nad@acm.org>: ---------- nosy: +michael.foord title: Python docs link to terrible outsi -> Confusing documentation in the urllib2 HOWTO _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18914> _______________________________________
R. David Murray added the comment: 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.) ---------- nosy: +r.david.murray _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18914> _______________________________________
Brian Mingus added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18914> _______________________________________
R. David Murray added the comment: 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? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18914> _______________________________________
Brian Mingus added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18914> _______________________________________
Changes by Senthil Kumaran <senthil@uthcode.com>: ---------- nosy: +orsenthil _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18914> _______________________________________
Michael Foord added the comment: 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. ---------- resolution: -> wont fix stage: -> committed/rejected status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18914> _______________________________________
participants (5)
-
Brian Mingus -
Michael Foord
-
Ned Deily
-
R. David Murray
-
Senthil Kumaran