doctest 调试

Doctest提供了几种调试doctest示例的机制：

• 几个函数将doctests转换为可执行的Python程序，可以在Python调试器下运行pdb。

• DebugRunner类是的一个子类DocTestRunner的是提高用于第一故障的例子的异常，包含有关实施例的信息。该信息可用于对示例执行事后调试。

• unittest通过DocTestSuite()支持由debug()所定义的方法生成的案例unittest.TestCase。

• 您可以pdb.set_trace()在doctest示例中添加调用，并在执行该行时放入Python调试器。然后你可以检查变量的当前值，等等。例如，假设a.py只包含这个模块docstring：

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

然后，一个交互式Python会话可能如下所示：

import a, doctest >>> doctest.testmod(a) --Return-- > (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 print x 6 (Pdb) step --Return-- > (2)f()->None -> g(x*2) (Pdb) list 1 def f(x): 2 -> g(x*2) EOF print x 3 (Pdb) step --Return-- > (1)?()->None -> f(3) (Pdb) cont (0, 3) >>>

在版本2.4中进行了更改：pdb.set_trace()添加了在文档测试中使用有用的功能。

将doctests转换为Python代码的函数，并可能在调试器下运行综合代码：

doctest.script_from_examples(s)

将带有示例的文本转换为脚本。

参数s是一个包含doctest示例的字符串。该字符串被转换为Python脚本，其中s中的doctest示例转换为常规代码，其他所有内容都转换为Python注释。生成的脚本作为字符串返回。例如，

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
""")

显示：

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

该函数在其他函数的内部使用（请参见下文），但是当您想要将交互式Python会话转换为Python脚本时，该函数也很有用。

2.4版本中的新功能。

doctest.testsource(module, name)

将对象的doctest转换为脚本。

参数模块是一个模块对象，或者一个模块的虚线名称，包含其文档感兴趣的对象。参数名称是具有感兴趣的doctests的对象的名称（在模块内）。结果是一个字符串，包含对象的文档字符串转换为Python脚本，script_from_examples()如上所述。例如，如果模块a.py包含顶级函数f()，那么

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

打印函数f()的文档字符串的脚本版本，将文档转换为代码，其余部分放在注释中。

2.3版本的新功能。

doctest.debug(module, name[, pm])

调试对象的doctests。

该模块和名称参数是相同的功能testsource()之上。已命名对象的文档字符串的合成Python脚本被写入临时文件，然后该文件在Python调试器的控制下运行pdb。

module.__dict__本地和全局执行上下文都使用浅表副本。

可选参数pm控制是否使用验尸调试。如果pm具有真值，则脚本文件将直接运行，并且仅当脚本通过引发未处理的异常终止时才会涉及调试器。如果确实如此，则通过pdb.post_mortem()从未处理的异常中传递回溯对象来调用验尸调试。如果pm没有被指定，或者是false，那么通过传递一个适当的execfile()调用来从脚本开始运行脚本pdb.run()。

2.3版本的新功能。

在版本2.4中更改：添加了pm参数。

doctest.debug_src(src[, pm][, globs])

用字符串调试doctests。

这与debug()上面的函数类似，只是通过src参数直接指定了包含doctest示例的字符串。

可选参数pm与debug()上面的函数具有相同的含义。

可选的参数globs给出了一个字典，用作本地和全局执行上下文。如果未指定，或者None使用空字典。如果指定，则使用字典的浅表副本。

2.4版本中的新功能。

DebugRunner级和特殊的例外可能提高，最感兴趣的测试框架的作者，并且只在这里勾勒。查看源代码，尤其DebugRunner是docstring（这是一个doctest！）以获取更多详细信息：

class doctest.DebugRunner([checker][, verbose][, optionflags])

只要DocTestRunner遇到故障，它的一个子类就会引发异常。如果发生意外异常，则会引发UnexpectedException异常，包含测试，示例和原始异常。如果输出不匹配，则会DocTestFailure引发异常，包含测试，示例和实际输出。

有关构造函数参数和方法的信息，请参阅DocTestRunner高级API一节中的文档。

DebugRunner实例可能会引发两个例外情况：

exception doctest.DocTestFailure(test, example, got)

DocTestRunner表示doctest示例的实际输出与预期输出不符的异常。构造函数参数用于初始化相同名称的属性。

DocTestFailure 定义了以下属性：

DocTestFailure.test

DocTest示例失败时正在运行的对象。

DocTestFailure.example

Example失败。

DocTestFailure.got

示例的实际输出。

exception doctest.UnexpectedException(test, example, exc_info)

一个异常DocTestRunner提示表示doctest示例引发了意外异常。构造函数参数用于初始化相同名称的属性。

UnexpectedException 定义了以下属性：

UnexpectedException.test

DocTest示例失败时正在运行的对象。

UnexpectedException.example

Example失败。

UnexpectedException.exc_info

包含有关意外异常的信息的元组，返回的是sys.exc_info()。