##
5.2.7 Debugging

Doctest provides several mechanisms for debugging doctest examples:

- Several functions convert doctests to executable Python programs, which can be run under the Python debugger, `pdb`.
- The `DebugRunner` class is a subclass of `DocTestRunner` that raises an exception for the first failing example, containing information about that example. This information can be used to perform post-mortem debugging on the example.
- The `unittest` cases generated by `DocTestSuite()` support the `debug()` method defined by ``unittest`.TestCase`.
- You can add a call to ``pdb`.set_trace()` in a doctest example, and you'll drop into the Python debugger when that line is executed. Then you can inspect current values of variables, and so on. For example, suppose a.py contains just this module docstring:

      """
      >>> def f(x):
      ...     g(x*2)
      >>> def g(x):
      ...     print x+3
      ...     import pdb; pdb.set_trace()
      >>> f(3)
      9
      """

  Then an interactive Python session may look like this:

      >>> import a, doctest
      >>> doctest.testmod(a)
      --Return--
      > <doctest a[1]>(3)g()->None
      -> import pdb; pdb.set_trace()
      (Pdb) list
        1     def g(x):
        2         print x+3
        3  ->     import pdb; pdb.set_trace()
      [EOF]
      (Pdb) print x
      6
      (Pdb) step
      --Return--
      > <doctest a[0]>(2)f()->None
      -> g(x*2)
      (Pdb) list
        1     def f(x):
        2  ->     g(x*2)
      [EOF]
      (Pdb) print x
      3
      (Pdb) step
      --Return--
      > <doctest a[2]>(1)?()->None
      -> f(3)
      (Pdb) cont
      (0, 3)
      >>>

  Changed in version 2.4: The ability to use ``pdb`.set_trace()` usefully inside doctests was added.

Functions that convert doctests to Python code, and possibly run the synthesized code under the debugger:

`script_from_examples`( | s)

  Convert text with examples to a script.

  Argument s is a string containing doctest examples. The string is converted to a Python script, where doctest examples in s are converted to regular code, and everything else is converted to Python comments. The generated script is returned as a string. For example,

          import doctest
          print doctest.script_from_examples(r"""
              Set x and y to 1 and 2.
              >>> x, y = 1, 2

              Print their sum:
              >>> print x+y
              3
          """)

  displays:

          # Set x and y to 1 and 2.
          x, y = 1, 2
          #
          # Print their sum:
          print x+y
          # Expected:
          ## 3

  This function is used internally by other functions (see below), but can also be useful when you want to transform an interactive Python session into a Python script.

  New in version 2.4.

`testsource`( | module, name)

  Convert the doctest for an object to a script.

  Argument module is a module object, or dotted name of a module, containing the object whose doctests are of interest. Argument name is the name (within the module) of the object with the doctests of interest. The result is a string, containing the object's docstring converted to a Python script, as described for `script_from_examples()` above. For example, if module a.py contains a top-level function `f()`, then

      import a, doctest
      print doctest.testsource(a, "a.f")

  prints a script version of function `f()`'s docstring, with doctests converted to code, and the rest placed in comments.

  New in version 2.3.

`debug`( | module, name[, pm])

  Debug the doctests for an object.

  The module and name arguments are the same as for function `testsource()` above. The synthesized Python script for the named object's docstring is written to a temporary file, and then that file is run under the control of the Python debugger, `pdb`.

  A shallow copy of `module.__dict__` is used for both local and global execution context.

  Optional argument pm controls whether post-mortem debugging is used. If pm has a true value, the script file is run directly, and the debugger gets involved only if the script terminates via raising an unhandled exception. If it does, then post-mortem debugging is invoked, via ``pdb`.post_mortem()`, passing the traceback object from the unhandled exception. If pm is not specified, or is false, the script is run under the debugger from the start, via passing an appropriate `execfile()` call to ``pdb`.run()`.

  New in version 2.3.

  Changed in version 2.4: The pm argument was added.

`debug_src`( | src[, pm][, globs])

  Debug the doctests in a string.

  This is like function `debug()` above, except that a string containing doctest examples is specified directly, via the src argument.

  Optional argument pm has the same meaning as in function `debug()` above.

  Optional argument globs gives a dictionary to use as both local and global execution context. If not specified, or `None`, an empty dictionary is used. If specified, a shallow copy of the dictionary is used.

  New in version 2.4.

The `DebugRunner` class, and the special exceptions it may raise, are of most interest to testing framework authors, and will only be sketched here. See the source code, and especially `DebugRunner`'s docstring (which is a doctest!) for more details:

class `DebugRunner`( | [checker][, verbose][, optionflags])

  A subclass of `DocTestRunner` that raises an exception as soon as a failure is encountered. If an unexpected exception occurs, an `UnexpectedException` exception is raised, containing the test, the example, and the original exception. If the output doesn't match, then a `DocTestFailure` exception is raised, containing the test, the example, and the actual output.

  For information about the constructor parameters and methods, see the documentation for `DocTestRunner` in section 5.2.6.

There are two exceptions that may be raised by `DebugRunner` instances:

exception `DocTestFailure`( | test, example, got)

  An exception thrown by `DocTestRunner` to signal that a doctest example's actual output did not match its expected output. The constructor arguments are used to initialize the member variables of the same names.

`DocTestFailure` defines the following member variables:

`test`
  The `DocTest` object that was being run when the example failed.

`example`
  The `Example` that failed.

`got`
  The example's actual output.

exception `UnexpectedException`( | test, example, exc_info)

  An exception thrown by `DocTestRunner` to signal that a doctest example raised an unexpected exception. The constructor arguments are used to initialize the member variables of the same names.

`UnexpectedException` defines the following member variables:

`test`
  The `DocTest` object that was being run when the example failed.

`example`
  The `Example` that failed.

`exc_info`
  A tuple containing information about the unexpected exception, as returned by `sys.exc_info()`.