ONLamp.com    
 Published on ONLamp.com (http://www.onlamp.com/)
 See this if you're having trouble printing code examples


Using pydoc

by Cameron Laird
04/18/2001

You're merrily coding along in your high-productivity Python way when your memory grows fuzzy -- to do date calculations, do you need a module called clock, date, or time? Within the Python 2.1 folder, you click on the "Module Docs" icon, and up pops a small graphical user interface (GUI) control panel. You type in "time", and the application gives you a choice of five distinct selections (Figure 1). Choose the first, and the reference documentation for Python's standard time module appears in a browser on your screen, complete with the answers to all your questions about date calculations.

Screen shot.
Figure 1. Five selections appear in the pydoc dialog box.

That was painless, just as pydoc is intended to be. (Note the GUI browser is titled "pydoc" in the figure above.) The pydoc module extracts module documentation and presents it in HTML or text. The 2.1 release of Python, official this week, is the first to include it as part of the standard library. UC Berkeley graduate student Ka-Ping Yee maintains the module. You can view the current sources at his site. Yee based pydoc on two of his earlier on-line documentation utilities, htmldoc and inspect. He credits Tommy Burnette's manpy and Paul Prescod's onlinehelp as the original inspiration for his version. Yee's module is not directly connected Marc-Andre Lemburg's pydoc, initiated five years ago.

While the figure above originated on a Windows desktop, pydoc behaves properly on MacOS and Unix, also. It has both graphical and command-line interfaces. Details on all the options are, of course, available through "pydoc pydoc". From a Unix command line, for example, "pydoc -k time" lists modules related to time, in analogy with "man -k ...".

Along with GUI and command line, you can use pydoc in three other modes. First let's take a closer look at why you'll want to make pydoc's acquaintance, and then I will show you how you can exploit it in your own programming.

The importance of documentation

Why all this churn about on-line help? It's true that a help system isn't algorithmically profound in the way Python's new list comprehensions or scoping considerations are. However, an efficient documentation system with the right polish has the potential to help every Python developer every day. Even if help systems have been done before, none until pydoc has ever been crafted specifically for the benefit of Python programmers.

Documentation has always been important in the Python world. Many newcomers to Python are struck by the lucidity and completeness of Python documentation. The pydoc module leverages those advantages to underline Python's status as a language that is easy to learn. Python has also gained considerable attention in the last few years for its aptness in team projects. A consistent, comprehensive documentation system is a particular advantage in work that stretches beyond the span of any individual. When it's as conveniently interactive as pydoc is, it becomes what Python developer, Tim Peters, agrees is "a Good and Important Thing." Peters compares pydoc to Emacs, Unix man pages, and the REBOL programming language as examples of earlier successes in interactive help.

Exploiting pydoc

Alongside standalone pydoc, accessed as a separate process launched from a graphical desktop or command line, a third interesting interactive way to exploit pydoc is within the Python shell. Suppose you're at the interpreter's >>> prompt, you request from pydoc import help. Now all the standard Python documentation is one keyword away. help is a function that knows how to retrieve documentation on other functions, classes, and modules. If you type "help(int)", for example, you'll see

Help on built-in function int:

int (no arg info)
  int(x) -> integer

  Convert a string or number to an integer, 
  if possible. A floating point argument will 
  be truncated towards zero.

Another way to reach the same point is simply to command "help" at the interpreter's prompt. Without any arguments, this launches the interactive help browser we've already seen.

Experienced Python users will recognize that int.__doc__ holds the same content. help() has several advantages over direct __doc__ retrieval, though. The former is easier to type, has the intelligence to display docstrings with proper formatting, and knows how to navigate to information that doesn't fit in the function.__doc__ syntax. Among other things, pydoc knows to use sys.path to reach documentation that corresponds to the programming modules the current interpreter is using, and it knows how to display information about inherited modules. Early 2.1 users laud help() as a significant benefit to their work.

An even more powerful form of pydoc is available through a 'Net connection. The publicly available pydoc.org benefits from a special index that knows all docstrings of all objects in all modules, not just the one-line module synopses.

Programmability

Interactive help() and Web-accessibility don't exhaust pydoc's flexibility. To appreciate the final way of using it, think about pydoc itself as a project. It has three elements:

Each of these is simple and completely available as source in the Python distribution. It follows that pydoc is also available as a programmable base. By substituting, subclassing, and rewriting any of the three elements above, programmers can build their own, special-purpose help systems.

The first such substantial project to be built on top of pydoc is Yee's own cgitb module, also available at his Python site. cgitb is a tiny traceback printer for CGI fault management. Here's how Yee describes cgitb:

it uses pydoc and inspect together to produce an elaborate and nicely-formatted display of a traceback whenever an error occurs in a CGI script.

I honestly believe that if "cgitb" gets into the Python distribution or gets otherwise distributed, Python will be so vastly much better an environment for CGI programming that hardly anyone will choose any other language any more. That's because most other languages just quit silently when there's an error in your CGI script, leaving you no information about what went wrong. When you debug scripts with the cgitb facility, the detailed exception dump shows you all the function names and argument values, and that makes finding and squishing bugs extremely fast and easy.

Conclusion

When you install your copy of Python 2.1, one of the first things you should do is exercise pydoc. Learning pydoc will repay you with more efficient ways to learn everything else there is to know about Python. Then when the time comes to implement a help system for one of your own projects, pydoc will make a great starting point.

Cameron Laird is the vice president of Phaseit, Inc. and frequently writes for the O'Reilly Network and other publications.


Return to the Python DevCenter.

Copyright © 2009 O'Reilly Media, Inc.