Python's interactive help utility provides a great deal of useful information about modules, classes, functions, and objects. The help system is an environment that is distinct from Python's REPL; it provides distinct prompts to make this clear.
There are three help modes, each with its unique prompt:
We'll see the
help>prompt from the Python help environment. When we evaluate thehelp()function with no argument value, we'll enter Python's help environment. We can enter different subjects and read about various Python features. When we enterquitas a topic, we'll return to the REPL.Using Windows, we'll see the
-- More --prompt: When we evaluate something likehelp(int)in a Windows environment, the output will be displayed using the MS-DOS more command. For more information, enter?for help on how to page through thehelp()output. At the Windows command line, enteringmore /?will provide additional information on how the more command helps you page through a long file.Using Mac OS X and Linux, we'll see the
:prompt. When we evaluate thehelp()function with a specific argument value—for example,help(float)—in Mac OS X or Linux, we'll get output that's displayed using the less program. For more information on this, enterhfor help while viewing thehelp()output. At the command prompt, enterless -?for more information on how the less program works.
There are additional ways to view the documentation available with Python modules. In IDLE, for example, there's a class browser and path browser that will show documentation about modules and files. This is based on the built-in help() function, but it's displayed in a separate window.
Python includes the pydoc application that we use to view documentation. This application is something that we run from the OS command prompt. We do not use this from the Python >>> prompt; we use it from the OS prompt. While developing, we might want to leave a Terminal window open just to display module documentation.
The pydoc program has two operating modes:
It can show some documentation about a specific package or module. This will use an appropriate program (more on Windows, but otherwise less) to display documentation for the given object. Here's how we can display documentation on the
mathmodule:MacBookPro-SLott:~ slott$ python3 -m pydoc mathIt can start a documentation web server. This will start a server (and also start a browser) to look at Python module documentation. When we use it, we'll have a session that looks like this:
MacBookPro-SLott:~ slott$ python3 -m pydoc -b Server ready at http://localhost:50177/ Server commands: [b]rowser, [q]uit server> q Server stopped
The second example will start a web server as well as a browser. The browser will show the pydoc-produced documentation. This is derived from the module and package structure as well as the documentation strings embedded in the Python code. When we were done reading the documentation, we entered q to quit the web server.
When we write Python packages, modules, classes, and functions, we can (and should) provide the content for pydoc/help() documentation. These documentation strings are part of our programming, and are as important as having programs that work correctly. We'll look at this embedded documentation in Chapter 14, Fit and Finish – Unit Testing, Packaging, and Documentation.