classification
Title: Make generally useful pydoc functions public
Type: enhancement Stage: resolved
Components: Documentation, Library (Lib) Versions: Python 3.3
process
Status: closed Resolution: not a bug
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, eric.araujo, georg.brandl, rhettinger, ron_adam, techtonik, terry.reedy
Priority: normal Keywords:

Created on 2010-01-28 15:26 by techtonik, last changed 2011-09-11 08:58 by rhettinger. This issue is now closed.

Messages (9)
msg98463 - (view) Author: anatoly techtonik (techtonik) Date: 2010-01-28 15:26
pydoc contains some useful methods like "pager()" that could be reused in many python application, and it would be handy to have a documentation for them in Python manual http://docs.python.org/library/pydoc
msg98572 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2010-01-30 17:59
Very likely, these functions are not meant to be anything but utilities.  As API functions, they also don't belong into pydoc.
msg98671 - (view) Author: anatoly techtonik (techtonik) Date: 2010-02-01 17:51
I won't mind against the pager module in the main library.
msg113186 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-08-07 18:06
Pydoc has a number of useful things that might be moved elsewhere and imported. An example is the no-yes filter _split_list. Documenting them in place would create something of a jumble. So I think this issue should be either closed (and possibly another opened) or renamed "Extract pydoc.page into a separate stdlib module." and reclassified.
msg113208 - (view) Author: Ron Adam (ron_adam) * Date: 2010-08-07 21:24
I think a good place for the pager is in the cmd module.  I have a separated version of it I could upload if there is consensus on this.

I've extracted the text server, but it's in a minimum 'works for pydoc' stage. (See issue 2001)

Both of these need some more eye to look at the api's before they get documented.
msg113870 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-08-14 05:20
pager is a general utility whereas cmd is for building REPLs, so I don’t think cmd is a good place. Can’t find a better one, though; shutil maybe. I have another feature in mind for a new module dedicated to the console: color codes, as seen duplicated in apps like Pygments, Sphinx, Mercurial, etc.
msg130400 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-03-09 02:38
I have looked at the pydoc module.  Everything except help() is intended to be private. The author says within the file that __all__, when present, defines public interface and uses that definition within help() to decide what to display. So I do not think anything else should be documented unless it is made 'public' by being added to pydoc.__all__ or moved to another module. In either case, the result would be a new code feature. Doc addition would naturally follow. Also, if a function is made public, the interface and code could be reconsidered for possible modification for general usage.
msg143630 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-09-06 16:39
I’ve looked hard at pydoc and opened distinct bug reports so that each piece of maybe-useful functionality can be discussed independently:

#12918 New module for terminal utilities
#12917 Make visiblename and allmethods functions public
#12916 Add inspect.splitdoc
#12915 Add inspect.locate and inspect.resolve
#12914 Add cram function to textwrap
msg143857 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2011-09-11 08:58
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.
History
Date User Action Args
2016-04-29 17:04:44berker.peksaglinkissue18956 superseder
2011-09-11 08:58:16rhettingersetnosy: + rhettinger
messages: + msg143857
2011-09-06 16:39:39eric.araujosetstatus: open -> closed
resolution: not a bug
messages: + msg143630

stage: needs patch -> resolved
2011-03-09 02:38:23terry.reedysetassignee: docs@python

components: + Library (Lib)
title: document pydoc methods -> Make generally useful pydoc functions public
nosy: + docs@python
versions: + Python 3.3, - Python 3.1, Python 2.7, Python 3.2
messages: + msg130400
2010-08-14 05:20:40eric.araujosetmessages: + msg113870
2010-08-07 21:24:18ron_adamsetnosy: + ron_adam
messages: + msg113208
2010-08-07 18:06:46terry.reedysetnosy: + terry.reedy

messages: + msg113186
versions: - Python 2.6
2010-02-16 05:50:56eric.araujosetnosy: + eric.araujo
2010-02-01 17:51:18techtoniksetmessages: + msg98671
2010-01-30 17:59:09georg.brandlsetassignee: georg.brandl -> (no value)
messages: + msg98572
2010-01-28 22:26:22brian.curtinsetpriority: normal
stage: needs patch
versions: + Python 3.1, Python 2.7, Python 3.2
2010-01-28 15:26:39techtonikcreate