[docs] [issue35681] urllib.request.HTTPPasswordMgr.add_password requires more information for HTTPPasswordMgrWithDefaultRealm

[Tatz Sekine]

New submission from Tatz Sekine <tsekine at 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 at python
components: Documentation
messages: 333189
nosy: docs at 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 <report at bugs.python.org>
<https://bugs.python.org/issue35681>
_______________________________________