doctest 基本API

函数testmod()和testfile()提供了一个简单的界面，文档测试，应该是足够了最基本的用途。有关这两个函数的不太正式的介绍，请参见简单用法：检查文档字符串和简单用法中的示例：检查文本文件中的示例。

doctest.testfile(filename[, module_relative][, name][, package][, globs][, verbose][, report][, optionflags][, extraglobs][, raise_on_error][, parser][, encoding])

除文件名以外的所有参数都是可选的，并应以关键字形式指定。

在名为filename的文件中测试示例。返回(failure_count, test_count)。

可选参数module_relative指定应如何解释文件名：

• 如果module_relative是True（缺省值），则filename指定一个与操作系统无关的模块相对路径。默认情况下，这个路径是相对于调用模块的目录；但是如果指定了package参数，那么它与该包相关。为了确保OS独立性，文件名应该使用/字符来分隔路径段，并且可能不是绝对路径（即它可能不以开头/）。

• 如果module_relative是False，则filename指定一个OS特定的路径。路径可以是绝对的或相对的; 相对路径相对于当前工作目录被解析。

可选参数名称给出测试的名称; 默认情况下，或者None，os.path.basename(filename)被使用。

可选参数包是一个Python包或一个Python包的名称，其目录应该用作模块相关文件名的基本目录。如果未指定包，则调用模块的目录将用作模块相关文件名的基本目录。如果module_relative是指定包，那是错误的。False

可选参数globs在执行示例时给出了一个用作全局变量的字典。这个词典的一个新的浅拷贝是为doctest创建的，所以它的例子从一个干净的石板开始。默认情况下，或者如果None使用新的空字典。

可选参数extraglobs给出了一个合并到用于执行示例的全局变量中的字典。这适用于dict.update()：如果globs和extraglobs具有共同的键，则extraglobs中的关联值出现在组合字典中。默认情况下，或者如果None，不使用额外的全局变量。这是一个允许doctests参数化的高级功能。例如，可以为基类编写一个doctest，使用该类的通用名称，然后通过传递将泛型名称映射到要测试的子类的extraglobs字典来测试任意数量的子类。

可选参数详细信息如果为true，则会打印大量内容，如果为false，则仅打印失败; 默认情况下，或者如果None，当且仅当'-v'在时才是sys.argv。

可选的参数报告在最后打印摘要时为真，否则在最后不打印任何内容。在详细模式下，摘要是详细的，否则摘要非常简短（实际上，如果所有测试都通过，则为空）。

可选参数optionflags或一起选项标志。请参见选项标志部分。

可选参数raise_on_error默认为false。如果为true，则在例子中发生第一次失败或意外异常时引发异常。这样可以对故障进行事后调试。默认行为是继续运行示例。

可选参数解析器指定DocTestParser应该用于从文件中提取测试的一个（或子类）。它默认为一个普通的解析器（即，DocTestParser()）。

可选的参数编码指定应该用于将文件转换为unicode的编码。

2.4版本中的新功能。

在版本2.5中更改：添加了参数编码。

doctest.testmod([m][, name][, globs][, verbose][, report][, optionflags][, extraglobs][, raise_on_error][, exclude_empty])

所有参数都是可选的，除m外的所有参数都应以关键字形式指定。

在从m开始可以访问的函数和类中的docstrings中的测试示例（或者__main__如果m没有提供或者是None，则为module ），以m.__doc__。开头。

还有可以从字典中获得的测试例子m.__test__，如果它存在与否None。m.__test__将名称（字符串）映射到函数，类和字符串; 函数和类docstrings搜索的例子; 字符串被直接搜索，就好像它们是docstrings一样。

仅搜索附加到属于模块m的对象的文档字符串。

返回(failure_count, test_count)。

可选参数名称给出模块的名称; 默认情况下，或者None，m.__name__被使用。

可选参数exclude_empty默认为false。如果属实，则没有找到doctests的对象将被排除在考虑之外。默认值是向后兼容的黑客，使代码仍然使用doctest.master.summarize()连同testmod()继续得到输出，没有测试对象。新构造函数的exclude_empty参数DocTestFinder默认为true。

可选参数extraglobs，verbose，report，optionflags，raise_on_error和globs与testfile()上述函数相同，只是globs默认为m.__dict__。

在版本2.3中更改：添加了参数optionflags。

在版本2.4中更改：添加了参数extraglobs，raise_on_error和exclude_empty。

在版本2.5中更改：可选参数isprivate，在2.4中弃用，已被删除。

doctest.run_docstring_examples(f, globs[, verbose][, name][, compileflags][, optionflags])

与对象f相关的测试例子; 例如，f可以是字符串，模块，函数或类对象。

字典参数glob的浅拷贝用于执行上下文。

失败消息中使用可选参数名称，缺省值为"NoName"。

如果可选参数verbose为true，则即使没有失败，也会生成输出。默认情况下，仅在发生示例故障时才会生成输出。

可选参数compileflags给出了运行示例时应由Python编译器使用的一组标志。默认情况下，或者如果None，推导的标志对应于在globs中找到的一组未来特征。

可选参数optionflags与testfile()上面的函数一样。