Interacting with the help subsystem

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 the help() 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 enter quit as a topic, we'll return to the REPL.
• Using Windows, we'll see the -- More -- prompt: When we evaluate something like help(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 the help() output. At the Windows command line, entering more /? 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 the help() 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, enter h for help while viewing the help() output. At the command prompt, enter less -? 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.

Using the pydoc program

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 math module:

  MacBookPro-SLott:~ slott$ python3 -m pydoc math
  

• It 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.