[docs] [issue7798] Make generally useful pydoc functions public

[Raymond Hettinger]

Raymond Hettinger <raymond.hettinger at gmail.com> added the comment:

Resist the urge to fatten APIs until you're sure that:
* they are needed
* they are well developed (many internal utils fail this test)
* they are worth the extra time it takes to learn what is in a module (adding rarely needed tools has the side-effect of obscuring things people actually need)

Georg's advice is spot on.  There are a lot of little internal routines in the standard library that aren't sufficiently fit to be exposed (perhaps a little too ad-hoc or special purpose, perhaps the API isn't sufficiently general, perhaps the routines rely on non-guaranteed aspects of the implementation).  For example, visiblename() is more heuristic than algorithmic -- right now, we can change that as needed (for instance, the recent updates to accommodate named tuples), but as soon as the method or function becomes public, its API freezes and it is hard for us to make changes.

The pager functions are interesting and non-trivial.  Before making them public in the standard library though, it would be best if it had some life as third-party module to let it mature (i.e. making sure it works as well in other contexts as it does in pydoc).

Also consider whether other documentation tools have already encountered and addressed these use cases, perhaps in a different and better way.

----------
nosy: +rhettinger

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue7798>
_______________________________________