Pages: 1, 2
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,
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
Experienced Python users will recognize that
int.__doc__ holds the same content.
has several advantages over direct
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
syntax. Among other things, pydoc knows to use
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
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.
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:
- the documentation set;
- the pydoc module's class definitions about general-purpose formatting for display of internal information;
- wrappers and shortcuts to make the programming interface available as "stand-alone" processes.
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
cgitb module, also available at his Python site.
cgitb is a tiny traceback printer for CGI fault
management. Here's how Yee describes
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
cgitbfacility, the detailed exception dump shows you all the function names and argument values, and that makes finding and squishing bugs extremely fast and easy.
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.
Return to the Python DevCenter.