[New-bugs-announce] [issue35681] urllib.request.HTTPPasswordMgr.add_password requires more information for HTTPPasswordMgrWithDefaultRealm
report at bugs.python.org
Mon Jan 7 18:09:03 EST 2019
New submission from Tatz Sekine <tsekine at google.com>:
HTTPPasswordMgrWithDefaultRealm.add_password() doesn't have proper documentation.
All known version of urllib.request (or urllib2 in Python 2.x) documentaion have the same issue.
HTTPPasswordMgrWithDefaultRealm object doesn't have its own documentation. Instead of that, HTTPPasswordMgr's doc have information for those 2 objects:
Both objects have just 2 functions: add_password() and find_user_password(). The doc for find_user_password() has explanation how different between those 2 objects, while the one for add_password() doesn't.
One of the missing explanation for HTTPPasswordMgrWithDefaultRealm.add_passowrd() is the value of realm. The document has now "realm, user and passwd must be strings.", but realm could be None for HTTPPasswordMgrWithDefaultRealm, to set default realm-less password.
That's typical use case of HTTPPasswordMgrWithDefaultRealm.add_password(), or, that's exactly urllib howto doc mentions in
So, documentation of HTTPPasswordMgr.add_passoword() should have additional explanation for realm which could be None for HTTPPasswordMgrWithDefaultRealm. Or, HTTPPasswordMgrWithDefaultRealm objects could have independent section from HTTPPasswordMgr, to clarify its usage.
Why is this matter?
Typeshed (https://github.com/python/typeshed) depends on the doc. I (or somebody else in the company) will report it separately.
assignee: docs at python
nosy: docs at python, tsekine
title: urllib.request.HTTPPasswordMgr.add_password requires more information for HTTPPasswordMgrWithDefaultRealm
versions: Python 2.7, Python 3.4, Python 3.5, Python 3.6, Python 3.7, Python 3.8
Python tracker <report at bugs.python.org>
More information about the New-bugs-announce