[Python-Dev] Pydoc Improvements / Rewrite

Ron Adam rrr at ronadam.com
Thu Jan 4 17:14:54 CET 2007


Laurent Gautier wrote:
> Ron,
> 
> I agree that pydoc could benefit a bit from some cleanup.
> As you point it out, the ability to write quick viewers would be
> very helpful. I came across that when wanting to develop script
> on a remote web server for which I only had FTP access: I ended
> up having to study pydoc more than I wanted in order to be able
> to build a display-the-doc cgi.
> 
> However having two different modules might not be needed.

I think weather it is two modules or more, or a package, is still an open issue. 
  Others have suggested it may be better for it to be package so I'm continuing 
in that direction.


> Introspection is probably already available in the separate module 
> 'inspect',
> and what a code pydoc would have to do is model the documentation
> (as a tree) and offer convenience function to navigate the data. Beside 
> that,
> there would be sub-modules for the different viewers for the documentation
> data - the interactive console being just one of the viewers.

Pydoc currently uses functions from the inspect module along with directly 
accessing attributes and other information where it is available.  It's not a 
replacement for the inspect module.

My first attempt used an xml tree to store the information, but to make that 
work requires also storing a fair amount of meta information in the tree as 
well.  I found parsing the tree and the meta information to be more complex than 
using an objective approach which is (to me) more readable and easier to extend. 
  But if you want to try it again, please do.  You may come up with something 
far better than I did.


> Finally, I would suspect that an API-breaking modification of the module 
> would
> need time to be accepted. 

I was considering this for python 3.0, but one of the developers suggested it 
would be nice to have in python 2.6 and to move the discussion here.

I think any API issues could be worked out.  Are there any programs you know of, 
(yours?), that import pydoc besides the python console?


May be the original author of pydoc is
> considering
> changes as well, and joining effort would be possible ?

AUTHOR
     Ka-Ping Yee <ping at lfw.org>

CREDITS
     Guido van Rossum, for an excellent programming language.
     Tommy Burnette, the original creator of manpy.
     Paul Prescod, for all his work on onlinehelp.
     Richard Chamberlain, for the first implementation of textdoc.


Ka-Ping reads python-dev but I'm cc'ing this to him just in case.  (I Used his 
python-dev email address since I don't know if the above one is current.)


Pydoc is a fairly complex program and it would definitely help if others took a 
look at various parts and made contributions and or suggestions to making it better.

I may have also gotten a bit over my head, but I'm willing to stick it out and 
try to get it finished with any suggestions (and help) that any one is willing 
to give me.  There are also too many important issues for me to be decided, so 
this isn't something that can be done in isolation.

The download link again is:

     http://ronadam.com/dl/_pydoc.zip

It's not fully functional yet, but does run. Some parts like the command line 
file output options still need to be reimplemented. Some output formatting still 
needs to be cleaned up, and the MRO tree parsing section still needs to be put 
back in.


One question that I have at the moment is:

* Would it be good to have the "KEYWORD" and "TOPICS" info as included data 
objects or files, and possibly use that to generate the python html (and other) 
documentation for these?  (Instead of the other way around like it is now.)

This would eliminate the requirement to install something extra in order for 
help on these items to work.

> L.
> 
> PS: I would also not go for a module name deliberately prefixed with "_"
> (as some people might associate that with protected or private objects).

The underscore was just a "temporary" convenience to avoid the name conflict 
with the existing module.  Weather to reuse the old name or use a new name is 
still one of the many open issues I think.

Ron



More information about the Python-Dev mailing list