sphinx.ext.doctest --文档中的测试代码段¶
在文档中包含代码片段并演示执行它们的结果通常很有帮助。但重要的是要确保文档与代码保持最新。
该扩展允许您以一种自然的方式在文档中测试此类代码片段。如果您按如下所示标记代码块， doctest Builder将收集它们并将其作为doctest测试运行。
在每个文档中，可以将每个代码段分配给 group 。每个小组由以下人员组成：
零个或更多 setup code 块(例如，导入要测试的模块)
一个或多个 test 块
在使用 doctest 生成器，为每个文档收集组并一个接一个地运行，首先执行安装代码块，然后按测试块在文件中出现的顺序执行它们。
测试块有两种：
doctest-style 块通过交错Python代码(包括解释器提示符)和输出来模拟交互会话。
code-output-style 块由一段普通的Python代码组成，也可以选择由该代码的一段输出组成。
指令¶
这个 group 下面的参数解释如下：如果为空，则将该块分配给名为的组 default 。如果是的话 * ，则将该块分配给所有组(包括 default 组)。否则，它必须是逗号分隔的组名列表。
- .. testsetup:: [group]¶
设置代码块。这段代码没有显示在其他构建器的输出中，而是在它所属的组(S)的doctest之前执行。
选项
- :skipif: condition (text)¶
如果pPython表达，则跳过该指令 condition 是真的看到 skipping tests conditionally .
- .. testcleanup:: [group]¶
清理代码块。这段代码没有显示在其他构建器的输出中，而是在它所属的组(S)的doctest之后执行。
Added in version 1.1.
选项
- :skipif: condition (text)¶
如果pPython表达，则跳过该指令 condition 是真的看到 skipping tests conditionally .
- .. doctest:: [group]¶
Doctest样式的代码块。您可以使用标准的
doctest用于控制如何将实际输出与您提供的输出进行比较的标志。默认标志集由doctest_default_flags配置变量。选项
- :hide:¶
在其他构建器中隐藏doctest块。默认情况下，它显示为一个突出显示的doctest块。
- :options: doctest flags (comma separated list)¶
应用于测试中每个示例的docTest标志的逗号分隔列表。 (You仍然可以为每个示例提供明确的标志，并带有docTest注释，但它们也会显示在其他构建器中。）
或者，您可以提供内联docTest选项，就像docTest中的那样：
>>> datetime.date.now() datetime.date(2008, 1, 1)
运行测试时将尊重它们，但默认情况下将从演示文稿输出中删除。您可以使用该选项防止脱衣
doctest:no-trim-doctest-flags.
- :pyversion: (text)¶
为要测试的示例指定所需的Python版本。例如，在以下情况下，该示例将仅针对大于3.12的Python版本进行测试：
.. doctest:: :pyversion: > 3.12
支持以下操作数：
~=：Compatible Release条款==：版本匹配子句!=：版本排除条款<=，>=：包含性有序比较条款<，>：排他性有序比较条款===：武断的平等条款。
pyversion选项后跟随 PEP-440: Version Specifiers 。Added in version 1.6.
在 1.7 版本发生变更: 支持的PEP-440操作数和符号
- :trim-doctest-flags:¶
- :no-trim-doctest-flags:¶
是否修剪删除docTest标志（评论看起来像
# doctest: FLAG, ...）在线的末端和<BLANKLINE>个体标记。 默认值为trim-doctest-flags.请注意，与标准文档测试一样，您必须使用
<BLANKLINE>以表示预期输出中的空行。这个<BLANKLINE>在生成演示文稿输出(HTML、LaTeX等)时被删除。
- :skipif: condition (text)¶
如果pPython表达，则跳过该指令 condition 是真的看到 skipping tests conditionally .
- .. testcode:: [group]¶
用于代码输出样式测试的代码块。
选项
- :hide:¶
隐藏其他构建器中的代码块。默认情况下，它显示为突出显示的代码块。
- :trim-doctest-flags:¶
- :no-trim-doctest-flags:¶
是否修剪删除docTest标志（评论看起来像
# doctest: FLAG, ...）在线的末端和<BLANKLINE>个体标记。 默认值为trim-doctest-flags.
- :skipif: condition (text)¶
如果pPython表达，则跳过该指令 condition 是真的看到 skipping tests conditionally .
备注
中的代码。
testcode块始终一次全部执行，无论它包含多少条语句。因此，产出将 not 为裸露的表达式生成--使用print。示例：：.. testcode:: 1+1 # this will give no output! print(2+2) # this will give output .. testoutput:: 4
另外，请注意，由于doctest模块不支持在同一个代码段中混合使用常规输出和异常消息，因此这也适用于测试代码/测试输出。
- .. testoutput:: [group]¶
的对应输出或异常消息。
testcode阻止。- :hide:¶
在其他构建器中隐藏doctest块。默认情况下，它显示为一个突出显示的doctest块。
- :options: doctest flags (comma separated list)¶
docTest标志的逗号分隔列表。
- :trim-doctest-flags:¶
- :no-trim-doctest-flags:¶
是否修剪删除docTest标志（评论看起来像
# doctest: FLAG, ...）在线的末端和<BLANKLINE>个体标记。 默认值为trim-doctest-flags.
- :skipif: condition (text)¶
如果pPython表达，则跳过该指令 condition 是真的看到 skipping tests conditionally .
示例：：
.. testcode:: print('Output text.') .. testoutput:: :hide: :options: -ELLIPSIS, +NORMALIZE_WHITESPACE Output text.
以下是这些指令的用法示例。测试通过 doctest 和测试通过 testcode 和 testoutput 是等价的。**
The parrot module
=================
.. testsetup:: *
import parrot
The parrot module is a module about parrots.
Doctest example:
.. doctest::
>>> parrot.voom(3000)
This parrot wouldn't voom if you put 3000 volts through it!
Test-Output example:
.. testcode::
parrot.voom(3000)
This would output:
.. testoutput::
This parrot wouldn't voom if you put 3000 volts through it!
有条件地跳过测试¶
skipif ，一个字符串选项，可用于有条件地跳过指令。例如，当应根据环境(硬件、网络/VPN、可选依赖项或依赖项的不同版本)运行一组不同的测试时，这可能很有用。这个 skipif 选项受所有doctest指令支持。以下是以下的典型用例 skipif 当用于不同的指令时：
testsetupandtestcleanup有条件地跳过测试设置和/或清理
根据环境自定义设置/清理代码
-
有条件地跳过测试及其输出验证
-
有条件地跳过一次测试
根据环境定制测试代码
-
有条件地跳过跳过的测试的输出断言
根据环境的不同，期望不同的产量
它的价值在于 skipif 选项作为Python表达式进行求值。如果结果为真值，则该指令将从测试运行中省略，就像它根本不存在于文件中一样。
不是重复一个表达式，而是 doctest_global_setup 配置选项可用于将其赋给一个变量，然后可改为使用该变量。
下面是一个在未安装Pandas的情况下跳过一些测试的示例：
extensions = ['sphinx.ext.doctest']
doctest_global_setup = '''
try:
import pandas as pd
except ImportError:
pd = None
'''
.. testsetup::
:skipif: pd is None
data = pd.Series([42])
.. doctest::
:skipif: pd is None
>>> data.iloc[0]
42
.. testcode::
:skipif: pd is None
print(data.iloc[-1])
.. testoutput::
:skipif: pd is None
42
配置¶
Doctest扩展使用以下配置值：
- doctest_default_flags¶
- 类型:
int- 默认:
ELLIPSIS | IGNORE_EXCEPTION_DETAIL | DONT_ACCEPT_TRUE_FOR_1
默认情况下，以下选项处于启用状态：
ELLIPSIS，允许您在预期输出中放置与实际输出中的任何内容匹配的省略号；IGNORE_EXCEPTION_DETAIL，导致异常名称中最左侧冒号之后的所有内容和任何模块信息都被忽略；DONT_ACCEPT_TRUE_FOR_1，在给出“1”的输出中拒绝“True”--接受此替换的默认行为是早期版本Python2.2的遗迹。
Added in version 1.5.
- doctest_show_successes¶
- 类型:
bool- 默认:
True
控制是否报告成功。
对于具有多个doctest的项目，将其设置为
False以仅突出显示故障。Added in version 7.2.
- doctest_global_setup¶
- 类型:
str- 默认:
''
被视为被放入
testsetup指令适用于 every 已测试的文件，并针对每个组。例如，您可以使用它来导入您在文档测试中始终需要的模块。Added in version 0.6.
- doctest_global_cleanup¶
- 类型:
str- 默认:
''
被视为被放入
testcleanup指令适用于 every 已测试的文件，并针对每个组。例如，您可以使用它来删除测试留下的任何临时文件。Added in version 1.1.
- doctest_test_doctest_blocks¶
- 类型:
str- 默认:
'default'
如果这是一个非空字符串，则标准的reStructuredtext docTest块也将被测试。他们将被分配到给定的组名称。
reStructuredtext doctests块只是将doctests放入自己的段落中，就像这样：：
Some documentation text. >>> print(1) 1 Some more documentation text.
(请注意，没有特殊的
::用于引入doctest块；docutils将它们与前导>>>。此外，没有使用额外的缩进，尽管它不会造成伤害。)如果将此值保留为其默认值，则doctest构建器将完全按照以下方式解释上面的代码片段：
Some documentation text. .. doctest:: >>> print(1) 1 Some more documentation text.
此功能使您可以轻松地在随
autodoc扩展，而无需使用特殊指令标记它们。不过请注意，reStructuredtext docTest块中不能有空白行。它们将被解释为一个区块结束和另一个区块开始。此外，删除
<BLANKLINE>和# doctest:选项仅适用于doctest块，尽管您可以设置trim_doctest_flags以在所有具有Python控制台内容的代码块中实现这一目标。
- doctest_fail_fast¶
- 类型:
bool- 默认:
False
当遇到第一个故障时退出。
Added in version 8.3.