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
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
- User-defined generic types
- 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
- Basic API
- Unittest API
- Advanced API
- DocTest Objects
- Example Objects
- DocTestFinder objects
- DocTestParser objects
- DocTestRunner objects
- OutputChecker objects
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
- Test cases
- Class and Module Fixtures
- setUpClass and tearDownClass
- setUpModule and tearDownModule
- Signal Handling
unittest.mock— mock object library
- Quick Guide
- The Mock Class
- Deleting Attributes
- Mock names and the name attribute
- Attaching Mocks as Attributes
- The patchers
- patch methods: start and stop
- patch builtins
- Nesting Patch Decorators
- Where to patch
- Patching Descriptors and Proxy Objects
- MagicMock and magic method support
- Mocking Magic Methods
- Magic Mock
- 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
- Using Mock
- 2to3 – Automated Python 2 to 3 code translation
- Using 2to3
lib2to3– 2to3’s library
test— Regression tests package for Python
- Writing Unit Tests for the
- Running tests using the command-line interface
- Writing Unit Tests for the
test.support— Utilities for the Python test suite
test.support.script_helper— Utilities for the Python execution tests
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
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
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.
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.
-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.
-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
Module docs for core modules are assumed to reside in
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
Changed in version 3.3: The
-g command line option was removed.