Using pydocby Cameron Laird
You're merrily coding along in your high-productivity Python way
when your memory grows fuzzy -- to do date calculations, do you need a
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.
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,
inspect. He credits Tommy
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.
Pages: 1, 2