A brief guide to Pydoc — Documentation generator and online help system

 

[ad_1]

Development Tools for python

The modules described in this chapter help you write software. For example, the pydoc module takes a module and generates documentation based on the module’s contents. The doctest and unittest modules contains frameworks for writing unit tests that automatically exercise code and verify that the expected output is produced. 2to3 can translate Python 2.x source code into valid Python 3.x code.

The list of modules described in this chapter is:

  • typing — Support for type hints
    • Type aliases
    • NewType
    • Callable
    • Generics
    • User-defined generic types
    • The Any type
    • Nominal vs structural subtyping
    • Classes, functions, and decorators
  • pydoc — Documentation generator and online help system
  • doctest — Test interactive Python examples
    • Simple Usage: Checking Examples in Docstrings
    • Simple Usage: Checking Examples in a Text File
    • How It Works
      • Which Docstrings Are Examined?
      • How are Docstring Examples Recognized?
      • What’s the Execution Context?
      • What About Exceptions?
      • Option Flags
      • Directives
      • Warnings
    • Basic API
    • Unittest API
    • Advanced API
      • DocTest Objects
      • Example Objects
      • DocTestFinder objects
      • DocTestParser objects
      • DocTestRunner objects
      • OutputChecker objects
    • Debugging
    • Soapbox
  • unittest — Unit testing framework
    • Basic example
    • Command-Line Interface
      • Command-line options
    • Test Discovery
    • Organizing test code
    • Re-using old test code
    • Skipping tests and expected failures
    • Distinguishing test iterations using subtests
    • Classes and functions
      • Test cases
        • Deprecated aliases
      • Grouping tests
      • Loading and running tests
        • load_tests Protocol
    • Class and Module Fixtures
      • setUpClass and tearDownClass
      • setUpModule and tearDownModule
    • Signal Handling
  • unittest.mock — mock object library
    • Quick Guide
    • The Mock Class
      • Calling
      • Deleting Attributes
      • Mock names and the name attribute
      • Attaching Mocks as Attributes
    • The patchers
      • patch
      • patch.object
      • patch.dict
      • patch.multiple
      • patch methods: start and stop
      • patch builtins
      • TEST_PREFIX
      • Nesting Patch Decorators
      • Where to patch
      • Patching Descriptors and Proxy Objects
    • MagicMock and magic method support
      • Mocking Magic Methods
      • Magic Mock
    • Helpers
      • sentinel
      • DEFAULT
      • call
      • create_autospec
      • ANY
      • FILTER_DIR
      • mock_open
      • Autospeccing
      • Sealing mocks
  • unittest.mock — getting started
    • Using Mock
      • Mock Patching Methods
      • Mock for Method Calls on an Object
      • Mocking Classes
      • Naming your mocks
      • Tracking all Calls
      • Setting Return Values and Attributes
      • Raising exceptions with mocks
      • Side effect functions and iterables
      • Mocking asynchronous iterators
      • Mocking asynchronous context manager
      • Creating a Mock from an Existing Object
    • Patch Decorators
    • Further Examples
      • Mocking chained calls
      • Partial mocking
      • Mocking a Generator Method
      • Applying the same patch to every test method
      • Mocking Unbound Methods
      • Checking multiple calls with mock
      • Coping with mutable arguments
      • Nesting Patches
      • Mocking a dictionary with MagicMock
      • Mock subclasses and their attributes
      • Mocking imports with patch.dict
      • Tracking order of calls and less verbose call assertions
      • More complex argument matching
  • 2to3 – Automated Python 2 to 3 code translation
    • Using 2to3
    • Fixers
    • lib2to3 – 2to3’s library
  • test — Regression tests package for Python
    • Writing Unit Tests for the test package
    • Running tests using the command-line interface
  • test.support — Utilities for the Python test suite
  • test.support.script_helper — Utilities for the Python execution tests

The pydoc module automatically generates documentation from Python modules. The documentation can be presented as pages of text on the console, served to a Web browser, or saved to HTML files.

For modules, classes, functions and methods, the displayed documentation is derived from the docstring (i.e. the __doc__ attribute) of the object, and recursively of its documentable members. If there is no docstring, pydoc tries to obtain a description from the block of comment lines just above the definition of the class, function or method in the source file, or at the top of the module (see inspect.getcomments()).

The built-in function help() invokes the online help system in the interactive interpreter, which uses pydoc to generate its documentation as text on the console. The same text documentation can also be viewed from outside the Python interpreter by running pydoc as a script at the operating system’s command prompt. For example, running

pydoc sys

at a shell prompt will display documentation on the sys module, in a style similar to the manual pages shown by the Unix man command. The argument to pydoc can be the name of a function, module, or package, or a dotted reference to a class, method, or function within a module or module in a package. If the argument to pydoc looks like a path (that is, it contains the path separator for your operating system, such as a slash in Unix), and refers to an existing Python source file, then documentation is produced for that file.

Note

In order to find objects and their documentation, pydoc imports the module(s) to be documented. Therefore, any code on module level will be executed on that occasion. Use an if __name__ == '__main__': guard to only execute code when a file is invoked as a script and not just imported.

When printing output to the console, pydoc attempts to paginate the output for easier reading. If the PAGER environment variable is set, pydoc will use its value as a pagination program.

Specifying a -w flag before the argument will cause HTML documentation to be written out to a file in the current directory, instead of displaying text on the console.

Specifying a -k flag before the argument will search the synopsis lines of all available modules for the keyword given as the argument, again in a manner similar to the Unix man command. The synopsis line of a module is the first line of its documentation string.

You can also use pydoc to start an HTTP server on the local machine that will serve documentation to visiting Web browsers. pydoc -p 1234 will start a HTTP server on port 1234, allowing you to browse the documentation at http://localhost:1234/ in your preferred Web browser. Specifying 0 as the port number will select an arbitrary unused port.

pydoc -n <hostname> will start the server listening at the given hostname. By default the hostname is ‘localhost’ but if you want the server to be reached from other machines, you may want to change the host name that the server responds to. During development this is especially useful if you want to run pydoc from within a container.

pydoc -b will start the server and additionally open a web browser to a module index page. Each served page has a navigation bar at the top where you can Get help on an individual item, Search all modules with a keyword in their synopsis line, and go to the Module index, Topics and Keywords pages.

When pydoc generates documentation, it uses the current environment and path to locate modules. Thus, invoking pydoc spam documents precisely the version of the module you would get if you started the Python interpreter and typed import spam.

Module docs for core modules are assumed to reside in  where X and Y are the major and minor version numbers of the Python interpreter. This can be overridden by setting the PYTHONDOCS environment variable to a different URL or to a local directory containing the Library Reference Manual pages.

Changed in version 3.2: Added the -b option.

Changed in version 3.3: The -g command line option was removed.

Changed in version 3.4: pydoc now uses inspect.signature() rather than inspect.getfullargspec() to extract signature information from callables.

[ad_2]

This article has been published from the source link without modifications to the text. Only the headline has been changed.

Source link