Using the `pydoc` command (with examples)

Python provides a built-in command-line tool called pydoc that allows developers to access offline Python documentation. This tool is particularly useful for quickly looking up information about Python keywords, topics, functions, modules, packages, etc. In this article, we will explore different use cases of the pydoc command and illustrate each one with code examples.

1: Print documentation on a subject

To print documentation on a specific subject, such as a Python keyword, topic, function, module, or package, you can use the following command:

pydoc subject

• Motivation: When working with Python, it is common to come across unfamiliar keywords, functions, or modules. Using pydoc, you can quickly retrieve relevant information about these subjects without leaving the command line.
• Explanation: The subject argument represents the keyword, topic, function, module, or package for which you want to display the documentation.
• Example: Let’s say we want to retrieve information about the print function. We can use the following command:

pydoc print

• Output:

Help on built-in function print in module builtins:

print(...)
    print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False)
    
    Prints the values to a stream, or to sys.stdout by default.
    Optional keyword arguments:
    file:  a file-like object (stream); defaults to the current sys.stdout.
    flush: whether to forcibly flush the stream.
...

The output provides a detailed description of the print function, including its signature, parameters, and purpose.

2: Start an HTTP server to view documentation

Another useful feature of pydoc is the ability to start an HTTP server and open a browser to view the documentation. This can be achieved by using the following command:

pydoc -b

• Motivation: Sometimes, it is more convenient to browse through the Python documentation using a web browser instead of the command line. By starting an HTTP server, you can access the documentation through a graphical user interface.
• Explanation: The -b flag tells pydoc to start an HTTP server and open a browser to display the documentation.
• Example: When running the following command:

pydoc -b

• Output: The pydoc command will start an HTTP server on an arbitrary unused port (e.g., http://localhost:1234/) and automatically open the default web browser to display the documentation. You can then navigate through the documentation using hyperlinks and search for specific subjects.

3: Display help

To display general help about the pydoc command and its usage, you can simply run the following command:

pydoc

• Motivation: If you are unfamiliar with the available options and functionalities of the pydoc command, using the pydoc command by itself will provide a brief overview of its usage.
• Explanation: Running pydoc without any arguments will display usage information and available options.
• Example: By executing the following command:

pydoc

• Output:

pydoc - the Python documentation tool

pydoc [options] [name ...]

    ...
    

The output provides a brief explanation of the pydoc command and its available options.

By exploring these different use cases of the pydoc command, developers can leverage this tool to quickly access Python documentation and gather information about various subjects. Whether it’s printing documentation, opening a browser-based interface, or simply getting general help, pydoc enhances the development experience by providing easy access to offline Python documentation.