New submission from Tatz Sekine <tsek...@google.com>:
TL;DR 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. Details: HTTPPasswordMgrWithDefaultRealm object doesn't have its own documentation. Instead of that, HTTPPasswordMgr's doc have information for those 2 objects: https://docs.python.org/3.8/library/urllib.request.html?highlight=httppasswordmgr#http-password-mgr 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 https://docs.python.org/3.8/howto/urllib2.html?highlight=httppasswordmgrwithdefaultrealm Conclusion: 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@python components: Documentation messages: 333189 nosy: docs@python, tsekine priority: normal severity: normal status: open title: urllib.request.HTTPPasswordMgr.add_password requires more information for HTTPPasswordMgrWithDefaultRealm type: behavior versions: Python 2.7, Python 3.4, Python 3.5, Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <rep...@bugs.python.org> <https://bugs.python.org/issue35681> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
