classification
Title: urllib.splituser is not documented
Type: Stage: resolved
Components: Documentation Versions: Python 3.2, Python 3.3, Python 2.7
process
Status: closed Resolution: wont fix
Dependencies: Superseder:
Assigned To: orsenthil Nosy List: docs@python, ezio.melotti, orsenthil, sandro.tosi, techtonik, vinay.sajip
Priority: normal Keywords:

Created on 2011-01-25 20:24 by techtonik, last changed 2013-10-08 18:58 by georg.brandl. This issue is now closed.

Messages (7)
msg127047 - (view) Author: anatoly techtonik (techtonik) Date: 2011-01-25 20:24
I'm studying old code that uses urllib.splituser() call and can't find description of this function in Python 2.6.6 docs.
msg130551 - (view) Author: Senthil Kumaran (orsenthil) * (Python committer) Date: 2011-03-11 09:25
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.
msg130553 - (view) Author: Sandro Tosi (sandro.tosi) * (Python committer) Date: 2011-03-11 09:53
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.
msg130558 - (view) Author: Senthil Kumaran (orsenthil) * (Python committer) Date: 2011-03-11 10:55
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.
msg172738 - (view) Author: Vinay Sajip (vinay.sajip) * (Python committer) Date: 2012-10-12 10:52
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.
msg172947 - (view) Author: anatoly techtonik (techtonik) Date: 2012-10-15 07:20
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?
msg173767 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-10-25 16:32
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.
History
Date User Action Args
2013-10-08 18:58:49georg.brandlsetstatus: open -> closed
2012-10-25 16:32:44ezio.melottisetstatus: pending -> open
nosy: + ezio.melotti
messages: + msg173767

2012-10-15 07:20:50techtoniksetstatus: closed -> pending

messages: + msg172947
2012-10-12 10:52:50vinay.sajipsetnosy: + vinay.sajip
messages: + msg172738
2011-03-11 10:55:17orsenthilsetnosy: orsenthil, techtonik, sandro.tosi, docs@python
messages: + msg130558
2011-03-11 09:53:17sandro.tosisetnosy: orsenthil, techtonik, sandro.tosi, docs@python
messages: + msg130553
2011-03-11 09:25:22orsenthilsetstatus: open -> closed

assignee: docs@python -> orsenthil

nosy: + orsenthil
messages: + msg130551
resolution: wont fix
stage: resolved
2011-03-08 21:22:06sandro.tosisetnosy: + sandro.tosi

versions: + Python 2.7, Python 3.2, Python 3.3, - Python 2.6
2011-01-25 20:24:37techtonikcreate