Description: Advanced Usage
Keywords: lib

## 5.2.5 Advanced Usage

Several module level functions are available for controlling how doctests are run.

`debug`( | module, name)

  Debug a single docstring containing doctests.

  Provide the module (or dotted name of the module) containing the docstring to be debugged and the name (within the module) of the object with the docstring to be debugged.

  The doctest examples are extracted (see function `testsource()`), and written to a temporary file. The Python debugger, `pdb`, is then invoked on that file. New in version 2.3.

`testmod`( | )

  This function provides the most basic interface to the doctests. It creates a local instance of class `Tester`, runs appropriate methods of that class, and merges the results into the global `Tester` instance, `master`.

  To get finer control than `testmod()` offers, create an instance of `Tester` with custom policies, or run methods of `master` directly. See `Tester.__doc__` for details.

`testsource`( | module, name)

  Extract the doctest examples from a docstring.

  Provide the module (or dotted name of the module) containing the tests to be extracted and the name (within the module) of the object with the docstring containing the tests to be extracted.

  The doctest examples are returned as a string containing Python code. The expected output blocks in the examples are converted to Python comments. New in version 2.3.

`DocTestSuite`( | [module])

  Convert doctest tests for a module to a ``unittest`.TestSuite`.

  The returned `TestSuite` is to be run by the unittest framework and runs each doctest in the module. If any of the doctests fail, then the synthesized unit test fails, and a `DocTestTestFailure` exception is raised showing the name of the file containing the test and a (sometimes approximate) line number.

  The optional module argument provides the module to be tested. It can be a module object or a (possibly dotted) module name. If not specified, the module calling this function is used.

  Example using one of the many ways that the `unittest` module can use a `TestSuite`:

          import unittest
          import doctest
          import my_module_with_doctests

          suite = doctest.DocTestSuite(my_module_with_doctests)
          runner = unittest.TextTestRunner()
          runner.run(suite)

  New in version 2.3. Warning: This function does not currently search `M.__test__` and its search technique does not exactly match `testmod()` in every detail. Future versions will bring the two into convergence.