哪些文档字符串被检查？

模块docstring，以及所有函数，类和方法文档字符串。导入模块的对象不被搜索.

另外，如果M.__test__存在且“是真的”，它必须是一个字典，并且eachentry将（字符串）名称映射到函数对象，类对象或字符串。函数和类对象文档字符串从M.__test__搜索，字符串被视为文档字符串。在输出中，K键M.__test__出现名称

<name of M>.__test__.K

发现的任何类都是类似的递归搜索，以测试其包含的方法和嵌套类中的文档字符串.

完全搜索。如何识别文档字符串示例？

在大多数情况下，交互式控制台会话的复制和粘贴工作正常，但doctest并不试图对任何特定的Python shell进行精确模拟.

>>> # comments are ignored>>> x = 12>>> x12>>> if x == 13:...     print("yes")... else:...     print("no")...     print("NO")...     print("NO!!!")...noNONO!!!>>>

任何预期的输出必须紧跟在包含代码的最终">>> "或"... "行之后，并且预期的输出（如果有的话）延伸到下一个">>> "或全空白行。

小字：

• 预期的输出不能包含全空行，因为这样的行是用来表示预期输出的结束。如果预期输出确实包含ablank行，则在你的doctest示例中放置<BLANKLINE>每个地方都需要一个空行.

• 所有硬标签字符都扩展为空格，使用8列制表符停止.Tabs in测试代码生成的输出不会被修改。因为示例输出中的任何硬标签are展开，这意味着如果codeoutput包含硬标签，doctest可以通过的唯一方法是NORMALIZE_WHITESPACE选项或指令有效。或者，可以重写测试以捕获输出并将其作为测试的一部分与预期值进行比较。这种对资源中标签的处理是通过反复试验得出的，并且已被证明是处理它们的极易出错的方式。通过编写自定义DocTestParser class.

• 捕获输出到stdout，但不输出到stderr（异常回溯通过不同的方式捕获）.

• 如果在交互式会话中通过反斜杠继续行，或者出于任何其他原因使用反斜杠，则应使用原始文档字符串，它将在您键入时完全保留反斜杠：

  >>> def f(x):...     r"""Backslashes in a raw docstring: m\n""">>> print(f.__doc__)Backslashes in a raw docstring: m\n

  否则，反斜杠将被解释为字符串的一部分。例如，\n以上将被解释为换行符。或者，您可以在doctest版本中加倍每个反斜杠（而不是使用原始字符串）：

  >>> def f(x):...     """Backslashes in a raw docstring: m\\n""">>> print(f.__doc__)Backslashes in a raw docstring: m\n

• 起始列无关紧要：

  >>> assert "Easy!"      >>> import math          >>> math.floor(1.9)          1

  并且从启动示例的初始">>> "行中出现的许多前导空白字符被删除了.

执行上下文是什么？

默认情况下，每次doctest找到要测试的文档字符串，它使用shallow copy对M的全局变量，因此运行测试不会改变模块的实际全局变量，所以在中进行一次测试M不能留下不小心允许另一个测试工作的后面的错误。这意味着示例可以自由地使用M中顶级定义的任何名称，以及正在运行的docstring中定义的名称。示例无法看到otherdocstrings中定义的名称.

您可以通过将globs=your_dict传递给testmod()或testfile()来强制使用您自己的dict作为执行上下文。

例外怎么办？

没问题，只要回溯是示例产生的唯一输出：只需粘贴回溯即可。[1]由于回溯包含可能快速变化的细节（例如，确切的文件路径和亚麻布），这是一个案例，其中doctest很难灵活地接受它的概念.

简单示例：

>>> [1, 2, 3].remove(42)Traceback (most recent call last):  File "<stdin>", line 1, in <module>ValueError: list.remove(x): x not in list

如果ValueError被提升，那么doctest会成功，list.remove(x):x not in list详细信息如图所示.

异常的预期输出必须以traceback标头开头，它可以是以下两行中的缩进与示例的第一行相同：

Traceback (most recent call last):Traceback (innermost last):

traceback标头后跟一个可选的回溯堆栈，doctest将忽略其内容。回溯堆栈通常被省略，或者从交互式会话中逐字复制.

回溯堆栈后面是最有趣的部分：包含异常类型和细节的行。这通常是atraceback的最后一行，但如果异常具有多行详细信息，则可以扩展到多行：

>>> raise ValueError("multi\n    line\ndetail")Traceback (most recent call last):  File "<stdin>", line 1, in <module>ValueError: multi    linedetail

最后三行（以ValueError开头）与exception的类型和细节进行比较，其余部分被忽略.

最佳做法是省略回溯堆栈，除非它为示例添加了重要的文档值。所以最后一个例子可能更好：

>>> raise ValueError("multi\n    line\ndetail")Traceback (most recent call last):    ...ValueError: multi    linedetail

请注意，回溯的处理非常特殊。特别是在一个例子中，...的使用与doctest的ELLIPSIS选项。这个例子中的省略号可以省略，或者也可以是三（或三百）个逗号或数字，或Monty Python短片的缩进字幕.

你应该阅读一些细节，但是赢了’需要记住：

• Doctest无法猜测您的预期输出是来自异常追踪还是来自普通打印。因此，例如，一个期望ValueError: 42 is prime的例子将通过是否实际调用ValueError或者示例是否仅打印该回溯文本。在实践中，普通输出很少以traceback标题行开头，因此这不会产生实际问题.
• 回溯堆栈的每一行（如果存在）必须在示例的第一行中进一步缩进，or以非字母数字字符开头。跟踪标题后面的第一行缩进相同，并以字母数字开头，作为异常详细信息的开头。当然，这对正版追溯是正确的.
• 当IGNORE_EXCEPTION_DETAIL指定了doctest选项，忽略了最左边冒号后面的所有内容以及异常名称中的任何模块信息.
• 交互式shell省略了某些SyntaxError s的回溯标题行。但doctest使用traceback标题行来区分异常和异常。所以在极少数情况下你需要测试一个省略了traceback标头的SyntaxError，你需要手动将traceback标题行添加到你的测试例中.

• 对于某些SyntaxErrors，Python使用^ marker：

  >>> 1 1  File "<stdin>", line 1    1 1      ^SyntaxError: invalid syntax

  显示thesyntax错误的字符位置由于显示错误位置的行位于异常类型和详细信息之前，因此doctest不会检查它们。例如，以下测试将通过，即使它将^标记放在错误的位置：

  >>> 1 1  File "<stdin>", line 1    1 1    ^SyntaxError: invalid syntax

Option Flags

许多选项标志控制doctest行为的各个方面。标志的符号名称作为模块常量提供，可以按位ORed 一起并传递给各种功能。名称也可用于doctest指令，可以通过-o选项。

第一组选项定义测试语义，控制howdoctest的方面决定实际输出是否与示例的预期输出匹配：

doctest.DONT_ACCEPT_TRUE_FOR_1

默认情况下，如果预期的输出块仅包含1，则仅包含1或仅True的实际输出块被认为是匹配的，类似于0 与 False。什么时候 DONT_ACCEPT_TRUE_FOR_1指定，不允许替换。默认行为迎合了thePython将许多函数的返回类型从integer更改为boolean; doctests期望“小整数”输出仍然适用于这些情况。这个选项可能会消失，但不会好几年.

doctest.DONT_ACCEPT_BLANKLINE

默认情况下，如果预期的输出块包含仅包含字符串<BLANKLINE>，那么该行将匹配实际输出中的空行。因为真正的空行界定了预期的输出，所以这是传达预期空行的唯一方法。当指定DONT_ACCEPT_BLANKLINE时，不允许这种替换.

doctest.NORMALIZE_WHITESPACE

当指定时，所有空格序列（空格和换行符）都被视为等同。预期输出中的任何空格序列都将匹配实际输出中的空格的任何序列。默认情况下，空格必须完全匹配。当一行预期的输出非常长时，NORMALIZE_WHITESPACE特别有用，你想把它包装在你的源代码中的多行中

doctest.ELLIPSIS

指定时，省略号标记（...）在预期的输出中可以在实际输出中使用matchany子串。这包括跨越lineboundaries和空子串的子串，所以最好继续使用这个简单的。复杂的用法可以导致相同类型的“oops，它匹配得太多了！”令人惊讶的是.*很容易在正则表达式中

doctest.IGNORE_EXCEPTION_DETAIL

指定时，如果引发预期类型的​​异常，即使异常详细信息不匹配，也会传递一个期望异常的示例。例如，如果提出的假设是ValueError: 42，那么期待ValueError: 3*14的例子将会通过，但是会失败，例如，如果TypeError被提升了

它也会忽略Python 3 doctest报告中使用的模块名称。因此，无论测试是在Python 2.7或Python 3.2（或更高版本）下运行，这些变体都将与指定的标志一起使用：

>>> raise CustomError("message")Traceback (most recent call last):CustomError: message>>> raise CustomError("message")Traceback (most recent call last):my_module.CustomError: message

注意ELLIPSIS也可用于忽略详细信息异常消息，但这样的测试可能仍然失败，因为模块详细信息是否作为异常名称的一部分打印。使用IGNORE_EXCEPTION_DETAIL和Python 2.3中的细节也是编写doctest的唯一明确方法，它不关心异常细节但仍然在Python 2.3之前传递（这些版本不支持doctest指令并将它们视为不相关的评论）。例如：

>>> (1, 2)[3] = "moo"Traceback (most recent call last):  File "<stdin>", line 1, in <module>TypeError: object doesn"t support item assignment

在Python 2.3和更高版本的Python版本中传递指定的标志，即使Python 2.4中的detail更改为“不”而不是“不”.

更改在版本3.2：IGNORE_EXCEPTION_DETAIL现在也忽略了与包含测试中的异常的模块有关的任何信息.

doctest.SKIP

如果指定，则根本不运行该示例。这在doctest示例同时用作文档和测试用例的情况下非常有用，并且应该包含示例以用于文档目的，但不应该考虑。例如，示例的输出可能是随机的;或者示例可能依赖于测试驱动程序无法使用的资源.

SKIP标志也可以用于临时“注释掉”示例.

doctest.COMPARISON_FLAGS

一个位掩码或者在一起所有的比较标志上面

第二组选项控制如何报告测试失败：

doctest.REPORT_UDIFF

如果指定，涉及多行预期和实际输出的故障将使用统一差异显示

doctest.REPORT_CDIFF

如果指定，涉及多行预期和实际输出的故障将使用上下文差异显示

doctest.REPORT_NDIFF

当指定时，差异由difflib.Differ计算，使用与流行的ndiff.py实用程序相同的算法。这是唯一标记线条和线条之间差异的方法。例如，如果预期输出的行包含数字1，其中实际输出包含字母l，则插入一行，标记不匹配列位置的插入符号

doctest.REPORT_ONLY_FIRST_FAILURE

如果指定，显示每个doctest中的第一个失败示例，但是对所有剩余示例禁止输出。这将阻止doctest报告因早期故障而中断的正确示例;但它也可能隐藏错误的示例，这些示例独立于第一次失败而失败。什么时候REPORT_ONLY_FIRST_FAILURE如果已指定，则剩余的示例仍然会运行，并且仍会计入报告的故障总数;只有输出被抑制.

doctest.FAIL_FAST

当指定时，在第一个失败的例子后退出，不要试图破坏其余的例子。因此，报告的失败次数最多为1次。这个标志在调试过程中可能很有用，因为在第一次失败之后的例子甚至不会产生调试输出.

doctest命令行接受选项-f作为-oFAIL_FAST.

的简写3.4版本中的新功能

doctest.REPORTING_FLAGS

一个位掩码或者将上面的所有报告标志组合在一起.

还有一种方法可以注册新的选项标志名称，尽管除非你打算这样做通过子类化扩展doctest内部：

doctest.register_optionflag（name）

创建一个具有给定名称的新选项标志，并返回新标志的整数值。register_optionflag()可以在子类化OutputChecker或DocTestRunner时使用，以创建子类支持的新选项。register_optionflag()应始终使用以下习语：

MY_FLAG = register_optionflag("MY_FLAG")

指令

Doctest指令可用于修改选项标志以获取单个示例。Doctest指令是一个示例的源代码后的特殊Python注释：

directive             ::=  "#" "doctest:" directive_optionsdirective_options     ::=  directive_option ("," directive_option)\*directive_option      ::=  on_or_off directive_option_nameon_or_off             ::=  "+" \| "-"directive_option_name ::=  "DONT_ACCEPT_BLANKLINE" \| "NORMALIZE_WHITESPACE" \| ...

+或-与指令选项名之间不允许有空格。指令选项名称可以是上面解释的任何选项标志名称.

示例的doctest指令修改doctest对该单个示例的行为。使用+启用命名行为，或-禁用它.

例如，此测试通过：

>>> print(list(range(20))) [0,   1,  2,  3,  4,  5,  6,  7,  8,  9,10,  11, 12, 13, 14, 15, 16, 17, 18, 19]

如果没有指令它会失败，两者都是因为实际输出在单位数列表元素之前没有两个空格，并且因为实际输出在一行上。此测试也通过了，并且还需要指令doso：

>>> print(list(range(20))) [0, 1, ..., 18, 19]

可以在单个物理线路上使用多个指令，由逗号分隔：

>>> print(list(range(20))) [0,    1, ...,   18,    19]

如果单个示例使用多个指令注释，则它们被组合：

>>> print(list(range(20))) ...                        [0,    1, ...,   18,    19]

如前面的示例所示，您可以将...行添加到仅包含指令的示例中。当一个示例太长而且指令太舒适地放在同一行上时，这可能很有用：

>>> print(list(range(5)) + list(range(10, 20)) + list(range(30, 40)))... [0, ..., 4, 10, ..., 19, 30, ..., 39]

请注意，由于默认情况下禁用所有选项，并且指令仅适用于它们出现的示例，因此启用选项（通过+在指令中）通常是唯一有意义的选择。但是，选项标志也可以传递运行doctests的功能，建立不同的默认值。在这种情况下，在指令中通过-禁用选项可能很有用.

警告

doctest认真对待要求预期输出的完全匹配。如果单个字符不匹配，则测试失败。这可能会让您感到惊讶几次，因为您正确切地了解Python的作用并且不保证输出。例如，在打印字典时，Python不保证键值对将以任何特定顺序打印，所以最喜欢

>>> foo(){"Hermione": "hippogryph", "Harry": "broomstick"}

很脆弱！一个解决方法是改为

>>> foo() == {"Hermione": "hippogryph", "Harry": "broomstick"}True

。另一个是做

>>> d = sorted(foo().items())>>> d[("Harry", "broomstick"), ("Hermione", "hippogryph")]

还有其他的，但你明白了.

另一个坏主意就是打印嵌入物体地址的东西，比如

>>> id(1.0) # certain to fail some of the time7948648>>> class C: pass>>> C()   # the default repr() for instances embeds an address<__main__.C instance at 0x00AC18F0>

ELLIPSIS指令为最后一个例子提供了一个很好的方法：

>>> C() <__main__.C instance at 0x...>

浮点数也会受到各种平台的小输出变化的影响，因为Python遵循平台C库进行浮点格式化，而C库的质量差别很大.

>>> 1./7  # risky0.14285714285714285>>> print(1./7) # safer0.142857142857>>> print(round(1./7, 6)) # much safer0.142857

表单的数量I/2.**J在所有平台上都是安全的，我经常会使用doctest示例来生成这种形式的数字：

>>> 3./4  # utterly safe0.75

简单的分数也让人们更容易理解，这使得更好的文档.

DocTest Objects

class doctest.DocTest（examples, globs, name, filename, lineno, docstring）

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

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

examples

的列表 Example编码应该由此测试运行的各个交互式Pythonexamples的对象.

globs

应该运行示例的名称空间（也称为全局变量）。这是adictionary将名称映射到值。对示例所做的命名空间的任何更改（例如绑定新变量）都将反映在globs测试运行后

name

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

filename

这个文件的名称DocTest摘录自;要么None如果文件名未知，或者DocTest是从文件中提取的.

lineno

中的行号filename这个DocTest开始，或None如果行号不可用。这个行号相对于文件的开头从零开始.

docstring

从中提取测试的字符串，或None如果字符串不可用，或者测试没有从字符串中提取出来

示例对象

class doctest.Example（source, want, exc_msg=None, lineno=0, indent=0, options=None）

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

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

source

包含示例源代码的字符串。此源代码由单个Python语句组成，并始终以换行符结束;构造函数在必要时添加换行符.

want

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

exc_msg

示例生成的异常消息，如果预期示例生成异常;或None如果预计不会产生异常。将此异常消息与traceback.format_exception_only(). exc_msg的返回值进行比较，结尾为newline，而不是None。如果需要，构造函数会添加换行符.

lineno

包含此示例的字符串中的行号，其中examplebegins。这个行号相对于包含字符串的开头从零开始.

indent

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

options

A从选项标志到True或False的字典映射，用于覆盖此示例的默认选项。此字典中未包含的任何选项标志都保留其默认值（由DocTestRunner的optionflags指定）。默认情况下，没有设置任何选项.

DocTestFinder对象

class doctest.DocTestFinder（verbose=False, parser=DocTestParser(), recurse=True, exclude_empty=True）

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

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

可选参数parser指定用于提取的DocTestParser对象（或adrop-in替换）来自docstrings的doctests。

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

如果可选参数exclude_empty为false，则DocTestFinder.find()将包含对具有空docstrings的对象的测试.

DocTestFinder定义以下方法：

find（obj[, name][, module][, globs][, extraglobs]）

返回由DocTest‘sdocstring或其任何包含对象’docstrings.obj定义的

s的列表可选参数name指定对象的名称;此名称将用于构造返回的DocTest s的名称。如果没有指定name，则使用obj.__name__.

可选参数module是包含给定对象的模块。如果未指定模块或是None，然后测试发现者将尝试自动确定正确的模块。使用对象的模块：

• 作为默认命名空间，如果没有指定globs.
• 阻止DocTestFinder从其他模块导入的对象中提取DocTests。（忽略包含module以外模块的包含对象。）
• 查找包含该对象的文件的名称.
• 帮助查找对象内的对象的行号它的文件

如果module是False，不会试图找到该模块。这个isobscure，主要用于测试doctest本身：如果module是False，oris None但是无法自动找到，那么所有对象都被认为属于（非存在的模块，所以所有包含的对象将（递归地）搜索doctests.

每个DocTest的全局变量是由globs和extraglobs组合而成的（extraglobs中的绑定覆盖globs中的绑定）。为每个DocTest创建全局字典的newshallow副本。如果globs未指定，那么它默认为模块的__dict__，ifspecified或{}除此以外。如果没有指定extraglobs，则它默认为{}.

DocTestParser对象

class doctest.DocTestParser

用于从字符串中提取交互式示例的处理类，并使用它们创建DocTestobject.

DocTestParser定义了以下方法：

get_doctest（string, globs, name, filename, lineno）

从给定的字符串中提取所有doctest示例，并将它们收集到DocTest object.

globs, name, filename和lineno是新的DocTest宾语。有关更多信息，请参阅DocTest的文档.

get_examples (string, name=”<string>”)

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

parse (string, name=”<string>” )

将给定的字符串分为示例和插入文本，并将它们作为交替的Example s和字符串列表返回。Example s的行号是从0开始的。可选参数name是一个nameidentifying这个字符串，只用于错误消息.

DocTestRunner对象

class doctest.DocTestRunner（checker=None, verbose=None, optionflags=0）

用于执行和验证的处理类DocTest.

中的交互式示例预期输出与实际输出之间的比较由OutputChecker完成。可以使用多个选项标志来定制该比较;有关详细信息，请参阅选项标志。如果选项标志不足，那么比较也可以绕过OutputChecker的子类定制到构造函数.

测试运行器的显示输出可以通过两种方式控制。首先，输出函数可以传递给TestRunner.run();将使用应显示的字符串调用此函数。它默认为sys.stdout.write。如果获取输出是不够的，那么显式输出也可以通过继承DocTestRunner，并覆盖方法report_start(), report_success(),report_unexpected_exception()和report_failure().

可选的关键字参数checker来指定OutputChecker应该用于将期望输出与doctest examples的实际输出进行比较的对象（或插件替换）.

可选关键字参数verbose控制DocTestRunner‘sverbosity。如果verbose是True，则会在运行时打印关于eachexample的信息。如果verbose是False，那么只会打印失败。如果verbose未指定，或None，则使用详细输出命令行开关-v使用.

可选关键字参数optionflags可用于控制testrunner如何将预期输出与实际输出进行比较，以及它如何显示失败。有关更多信息，请参阅选项标志.

DocTestParser定义以下方法：

report_start（out, test, example）

报告测试运行器即将处理给定的示例。提供此方法是为了允许DocTestRunner的子类自定义其输出;它不应该被直接调用.

example是要处理的例子。test是测试containing example. out是传递给DocTestRunner.run().

report_success（out, test, example, got）的输出函数

报告给定的示例成功运行。提供此方法是为了允许DocTestRunner的子类来定制它们的输出;它不应该被直接调用.

example是即将被处理的例子。got是示例中的实际输出。test是包含example. out的测试是输出到DocTestRunner.run().

report_failure（out, test, example, got）的输出函数

报告给定的示例失败了。提供此方法是为了允许DocTestRunner的子类自定义其输出;它不应该直接调用.

example是要处理的例子。got是示例中的实际输出。test是包含example. out的测试是传递给DocTestRunner.run().

report_unexpected_exception（out, test, example, exc_info）的输出函数

报告给出的例子提出了一个意外的例外。提供此方法允许DocTestRunner的子类自定义其输出;它不应该被直接调用.

example是要处理的例子。exc_info是关于意外异常的详细信息（由sys.exc_info()返回）。test是包含example. out的测试是输出到DocTestRunner.run().

run（test, compileflags=None, out=None, clear_globs=True）

运行test（a DocTest object）中的示例，并使用writer函数显示结果out.

这些示例在命名空间test.globs中运行。如果clear_globsistrue（默认值），然后在测试运行后清除此命名空间，以帮助进行垃圾收集。如果您想在测试完成后检查命名空间，那么使用clear_globs=False.

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

使用DocTestRunner‘soutput checker，结果由DocTestRunner.report_*()方法。

summarize（verbose=None）

打印此DocTestRunner运行的所有测试用例的摘要，并返回命名的元组 TestResults(failed, attempted).

可选的verbose参数控制摘要的详细程度。如果未指定详细程度，那么DocTestRunner的详细程度将被使用.

输出检查器对象

class doctest.OutputChecker

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

OutputChecker定义了以下方法：

check_output（want, got, optionflags）

返回True如果示例（got）的实际输出与预期的输出（want）匹配。如果它们相同，则始终认为这些字符串匹配;但是根据测试运行器使用的选项标记，也可以使用几种非精确匹配类型。有关选项标志的详细信息，请参阅选项标志。

output_difference// (example, got, optionflags)

返回描述两者之间差异的字符串agiven示例（example）的预期输出和实际输出（got）。optionflags是用于比较want和got.