doctest Advanced API

基本的API是一个简单的包装，旨在使doctest易于使用。它相当灵活，应该满足大多数用户的需求; 但是，如果您需要对测试进行更精细的控制，或者希望扩展doctest的功能，那么您应该使用高级API。

高级API围绕两个容器类进行，这两个容器类用于存储从doctest案例中提取的交互式示例：

• Example：一个Python 语句，与它的预期输出配对。

• DocTest：Examples 的集合，通常从单个文档字符串或文本文件中提取。

定义其他处理类来查找，分析和运行，并检查doctest示例：

• DocTestFinder：查找给定模块中的所有文档字符串，并使用DocTestParsera DocTest从包含交互式示例的每个文档字符串中创建一个。

• DocTestParser：DocTest从字符串中创建一个对象（例如对象的文档字符串）。

• DocTestRunner：执行DocTest中的例子，并使用一个OutputChecker来验证它们的输出。

• OutputChecker：将doctest示例中的实际输出与预期输出进行比较，并确定它们是否匹配。

下图总结了这些处理类之间的关系：

                            list of:
+------+                   +---------+
|module| --DocTestFinder-> | DocTest | --DocTestRunner-> results
+------+    |        ^     +---------+     |       ^    (printed)
            |        |     | Example |     |       |
            v        |     |   ...   |     v       |
           DocTestParser   | Example |   OutputChecker
                           +---------+

DocTest Objects

class doctest.DocTest(examples, globs, name, filename, lineno, docstring)

应该在单个命名空间中运行的doctest示例的集合。构造函数参数用于初始化相同名称的属性。

2.4版本中的新功能。

DocTest定义了以下属性。它们由构造函数初始化，不应该直接修改。

examples

Example编码应该由此测试运行的各个交互式Python示例的对象列表。

globs

应该运行示例的名称空间（又称全局变量）。这是一个将名称映射到值的字典。globs在测试运行之后，示例所做的任何对名称空间的更改（例如绑定新变量）都会反映出来。

name

一个字符串名称标识DocTest。通常，这是测试从中提取的对象或文件的名称。

filename

这DocTest是从中提取的文件的名称; 或者None如果文件名是未知的，或者如果DocTest没有从文件中提取。

lineno

行号在filename哪里DocTest开始，或None行号是否不可用。该行号相对于文件的开头是从零开始的。

docstring

从中提取测试None的字符串，或者字符串不可用，或者测试未从字符串中提取。

示例对象

class doctest.Example(source, want[, exc_msg][, lineno][, indent][, options])

一个交互式示例，由Python语句及其预期输出组成。构造函数参数用于初始化相同名称的属性。

2.4版本中的新功能。

Example定义了以下属性。它们由构造函数初始化，不应该直接修改。

source

包含示例源代码的字符串。这个源代码由一个Python语句组成，并且总是以换行符结尾; 构造函数在必要时添加一个换行符。

want

运行示例源代码的预期输出（来自标准输出，或者异常情况下的回溯）。want除非没有输出，否则以换行符结束，在这种情况下，它是一个空字符串。构造函数在必要时添加一个换行符。

exc_msg

该示例生成的异常消息，如果该示例预计会生成异常; 或者None如果不希望产生异常。该异常消息与返回值进行比较traceback.format_exception_only()。exc_msg除非是换行符，否则以换行符结尾None。如果需要，构造函数会添加一个换行符。

lineno

包含示例开始处的示例的字符串中的行号。该行号相对于包含字符串的开头是从零开始的。

indent

包含字符串中的示例缩进，即示例第一个提示之前的空格字符数。

options

从选项标记到Trueor的字典映射False，用于覆盖此示例的默认选项。任何未包含在此字典中的选项标志都保留默认值（由DocTestRunners 指定optionflags）。默认情况下，不设置任何选项。

DocTestFinder对象

class doctest.DocTestFinder([verbose][, parser][, recurse][, exclude_empty])

一个处理类，用于DocTest从文档字符串及其包含对象的文档字符串中提取与给定对象相关的s。DocTests可以从下列对象类型中提取：模块，函数，类，方法，静态方法，类方法和属性。

可选参数verbose可用于显示查找器搜索的对象。它默认为False（不输出）。

可选参数解析器指定DocTestParser用于从文档字符串中提取文档测试的对象（或插入替换）。

如果可选参数recurse为false，那么DocTestFinder.find()将只检查给定的对象，而不检查任何包含的对象。

如果可选参数exclude_empty为false，DocTestFinder.find()则将包含具有空文档字符串的对象的测试。

2.4版本中的新功能。

DocTestFinder 定义了以下方法：

find(obj[, name][, module][, globs][, extraglobs])

返回DocTest由obj的文档字符串或其包含的任何对象的文档字符串定义的s 的列表。

可选参数名称指定对象的名称; 这个名字将被用来为返回的DocTests 构造名字。如果没有指定名称，则obj.__name__使用。

可选参数模块是包含给定对象的模块。如果模块没有被指定或者是None，则测试发现者将尝试自动确定正确的模块。使用该对象的模块：

• 作为默认命名空间，如果没有指定globs。

• 阻止DocTestFinder从其他模块导入的对象中提取DocTests。（包含模块以外的模块的包含对象将被忽略。）

• 查找包含该对象的文件的名称。

• 帮助查找文件中对象的行号。

如果模块是False，则不会尝试找到该模块。这是很晦涩的，主要用于测试doctest本身：如果module是False，或者是None但不能自动找到，那么所有对象都被认为属于（不存在的）模块，因此所有包含的对象将（递归地）被搜索为doctests。

对于每个全局DocTest通过组合形成水珠和extraglobs（在绑定extraglobs倍率绑定在水珠）。为每个字典创建一个新的globals字典的浅表副本DocTest。如果未指定globs，则默认为模块的___dict__ （如果已指定）或{}以其他方式指定。如果_extraglobs没有被指定，那么它默认为{}。

DocTestParser对象

class doctest.DocTestParser

一个处理类，用于从字符串中提取交互式示例，并使用它们创建DocTest对象。

2.4版本中的新功能。

DocTestParser 定义了以下方法：

get_doctest(string, globs, name, filename, lineno)

从给定的字符串中提取所有doctest示例，并将它们收集到一个DocTest对象中。

globs，name，filename和lineno是新DocTest对象的属性。请参阅文档以DocTest获取更多信息。

get_examples(string[, name])

从给定的字符串中提取所有doctest示例，并将它们作为Example对象列表返回。行号是从0开始的。可选参数名称是标识此字符串的名称，仅用于错误消息。

parse(string[, name])

将给定的字符串分成示例和干预文本，并将它们作为交替Examples和字符串的列表返回。Examples的行号是基于0的。可选参数名称是标识此字符串的名称，仅用于错误消息。

DocTestRunner对象

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

处理类用于执行和验证DocTest中的交互式示例。

预期产出与实际产出之间的比较由OutputChecker。这种比较可以用许多选项标志来定制; 有关更多信息，请参阅选项标志部分。如果选项标志不足，则可以通过OutputChecker向构造函数传递一个子类来定制比较。

测试运行者的显示输出可以通过两种方式进行控制。首先，可以传递一个输出函数TestRunner.run(); 这个函数将会被显示的字符串调用。它默认为sys.stdout.write。如果捕获的输出不充分，则显示输出也可以通过继承DocTestRunner，并覆盖方法定制report_start()，report_success()，report_unexpected_exception()，和report_failure()。

可选的关键字参数检查器指定OutputChecker应该用于比较预期输出与doctest示例的实际输出的对象（或插入替换）。

可选的关键字参数verbose控制着DocTestRunner冗长。如果详细是True，则会在每个示例运行时打印信息。如果详细是False，则只打印故障。如果verbose未指定，或者None使用详细输出，则使用命令行开关-v。

可选的关键字参数optionflags可用于控制测试运行器如何将预期输出与实际输出进行比较，以及它如何显示故障。有关更多信息，请参见选项标志部分。

2.4版本中的新功能。

DocTestParser 定义了以下方法：

report_start(out, test, example)

报告测试运行人员即将处理给出的示例。提供此方法以允许其子类DocTestRunner定制其输出；它不应该直接调用。

例子就是要处理的例子。测试是包含示例的测试。out是传递给的输出函数DocTestRunner.run()。

report_success(out, test, example, got)

报告给出的示例已成功运行。提供此方法以允许其子类DocTestRunner定制其输出；它不应该直接调用。

例子就是要处理的例子。得到的是实例的实际输出。测试是包含示例的测试。out是传递给的输出函数DocTestRunner.run()。

report_failure(out, test, example, got)

报告给出的例子失败。提供此方法以允许其子类DocTestRunner定制其输出; 它不应该直接调用。

例子就是要处理的例子。得到的是实例的实际输出。测试是包含示例的测试。out是传递给的输出函数DocTestRunner.run()。

report_unexpected_exception(out, test, example, exc_info)

报告给出的示例引发了意外的异常。提供此方法以允许其子类DocTestRunner定制其输出; 它不应该直接调用。

例子就是要处理的例子。exc_info是包含有关意外异常（由返回的sys.exc_info()）的信息的元组。测试是包含示例的测试。out是传递给的输出函数DocTestRunner.run()。

run(test[, compileflags][, out][, clear_globs])

运行在实施例中测试（一个DocTest对象），并使用写入器功能显示结果出来。

这些示例在命名空间中运行test.globs。如果clear_globs为true（缺省值），那么该名称空间将在测试运行后清除，以帮助进行垃圾回收。如果您想在测试完成后检查名称空间，请使用clear_globs = False。

compileflags给出了运行示例时Python编译器应该使用的一组标志。如果未指定，则它将默认为适用于globs的future-import标志集。

每个示例的输出都使用DocTestRunner输出检查器进行检查，并且结果由这些DocTestRunner.report_*()方法进行格式化。

summarize([verbose])

打印由此DocTestRunner运行的所有测试用例的摘要，并返回一个指定的元组 TestResults(failed, attempted)。

可选的详细参数控制摘要的详细程度。如果没有指定DocTestRunner详细程度，则使用冗长度。

在版本2.6中更改：使用命名的元组。

OutputChecker对象

class doctest.OutputChecker

用于检查doctest示例的实际输出是否与预期输出匹配的类。OutputChecker定义了两种方法：check_output()，它比较给定的一对输出，如果匹配则返回真; 并output_difference()返回一个描述两个输出之间差异的字符串。

2.4版本中的新功能。

OutputChecker 定义了以下方法：

check_output(want, got, optionflags)

True如果示例（got）的实际输出与预期输出（想要）匹配，则返回。如果这些字符串相同，则始终认为它们匹配；但取决于测试运行器使用的选项标志，还可以使用几种非精确匹配类型。有关选项标志的更多信息，请参见选项标志部分。

output_difference(example, got, optionflags)

返回一个字符串，描述给定示例（示例）的预期输出与实际输出（获得）之间的差异。optionflags是用来比较想要和得到的选项标志的集合。