[issue11009] urllib.splituser is not documented
New submission from anatoly techtonik <techtonik@gmail.com>: I'm studying old code that uses urllib.splituser() call and can't find description of this function in Python 2.6.6 docs. ---------- assignee: docs@python components: Documentation messages: 127047 nosy: docs@python, techtonik priority: normal severity: normal status: open title: urllib.splituser is not documented versions: Python 2.6 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11009> _______________________________________
Changes by Sandro Tosi <sandro.tosi@gmail.com>: ---------- nosy: +sandro.tosi versions: +Python 2.7, Python 3.2, Python 3.3 -Python 2.6 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11009> _______________________________________
Senthil Kumaran <orsenthil@gmail.com> added the comment: splituser is an internal API. It has never been exposed through Docs anytime and there are good reasons for that too. We never want internal helper functions (even tough they don't startwith _) be exposed through docs as it may clutter the API Documentation. If you find a good use for splituser like function, it would good to discuss and build upon current one before exposing. I am closing this as wontfix. ---------- assignee: docs@python -> orsenthil nosy: +orsenthil resolution: -> wont fix stage: -> committed/rejected status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11009> _______________________________________
Sandro Tosi <sandro.tosi@gmail.com> added the comment: Hi Senthil, what do you think about "documenting" those methods are private ones in the urllib code (if not using _, at least a short comment above them)? at least we have a mark it's an implementation decision and in case someone has the crazy idea :) to scan the module to fill in the missing methods in the doc, he'd know they are not to be exposed. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11009> _______________________________________
Senthil Kumaran <orsenthil@gmail.com> added the comment: Sandro, I don't think is a required. Those functions serve the purpose of making the module code modular. They are helper functions for the module and are not really useful outside of it, when used standalone. Think about , splituser, splitpath, splitport etc etc. I think, it is best that they remain as such, undocumented. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11009> _______________________________________
Vinay Sajip added the comment: Note that at least splituser is being used outside the stdlib: packaging (which was intended to be part of the stdlib) used it, and hence so do distutils2 and distlib (by sharing parts of their codebases). Of course these last two are outside the stdlib. Similar functions are reimplemented outside the stdlib (e.g. see parse_credentials in pip.download). If the only reason for not exposing these is documentation clutter, surely there are approaches to minimise this. If the reason is that future implementations may change or remove them, that should be clarified. But since the basics of an url are unlikely to change, I don't see why these functions might be removed in the future. ---------- nosy: +vinay.sajip _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11009> _______________________________________
anatoly techtonik added the comment: Why not to follow the convention and add underscore _ to the names to remove the ambiguity and future reports and confusion about that thees functions are not documented? ---------- status: closed -> pending _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11009> _______________________________________
Ezio Melotti added the comment: Doing that now will be backward incompatible, because people might be using these functions already even if they are not documented. An alias could be created, but I'm not sure it's worth doing it. ---------- nosy: +ezio.melotti status: pending -> open _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11009> _______________________________________
Changes by Georg Brandl <georg@python.org>: ---------- status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11009> _______________________________________
participants (6)
-
anatoly techtonik -
Ezio Melotti
-
Georg Brandl
-
Sandro Tosi
-
Senthil Kumaran
-
Vinay Sajip