`sphinx.ext.doctest` --文档中的测试片段¶

在文档中包含代码片段并演示执行结果通常很有帮助。但重要的是要确保文档与代码保持同步。

此扩展允许您以自然的方式在文档中测试此类代码段。如果您如图所示标记代码块 doctest 构建器将收集它们并作为doctest测试运行它们。

在每个文档中，可以将每个代码段分配给组 . 每组包括：

零或更多 设置代码 块（例如导入要测试的模块）
一个或多个 test 阻碍

当使用 doctest 为每个文档收集组，并逐个运行，首先执行设置代码块，然后按它们在文件中出现的顺序运行测试块。

有两种试块：

doctest-style 块通过交错Python代码（包括解释器提示）和输出来模拟交互式会话。
code-output-style 块由一段普通的python代码和一段可选的代码输出组成。

指令¶

这个组下面的参数解释如下：如果为空，则将块分配给名为 default . 如果是 * 将块分配给所有组（包括 default 组）。否则，它必须是以逗号分隔的组名列表。

.. testsetup:: [group]¶: 设置代码块。此代码不显示在其他生成器的输出中，而是在它所属的组的doctests之前执行。

.. testcleanup:: [group]¶: 清除代码块。此代码不显示在其他生成器的输出中，而是在它所属的组的doctests之后执行。

Added in version 1.1.

.. doctest:: [group]¶

doctest样式的代码块。您可以使用标准 doctest 用于控制实际输出与作为输出提供的内容进行比较的标志。默认标志集由 doctest_default_flags 配置变量。

该指令支持五个选项：

hide 标志选项，在其他生成器中隐藏doctest块。默认情况下，它显示为突出显示的doctest块。
options 一个字符串选项，可用于给出一个逗号分隔的doctest标志列表，该列表适用于测试中的每个示例。（您仍然可以为每个示例提供带有doctest注释的显式标志，但它们也将显示在其他构建器中。）
pyversion ，一个字符串选项，可用于指定要测试的示例所需的Python版本。例如，在以下情况下，该示例将仅针对高于3.10的Python版本进行测试：
```
.. doctest::
   :pyversion: > 3.10
```
支持以下操作数：
- ~= ：兼容发布子句
- == ：版本匹配子句
- != ：版本排除子句
- <= ， >= ：包含顺序比较子句
- < ， > ：排他有序比较子句
- === ：任意平等条款。
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等）时删除。

此外，还可以提供内联doctest选项，如在doctest中：

>>> datetime.date.now()   # doctest: +SKIP
datetime.date(2008, 1, 1)

当测试运行时，它们会受到尊重，但会从表示输出中剥离出来。

.. testcode:: [group]¶

用于代码输出样式测试的代码块。

此指令支持三个选项：

hide 标志选项，在其他生成器中隐藏代码块。默认情况下，它显示为突出显示的代码块。
trim-doctest-flags 和 no-trim-doctest-flags ，一个标志选项，doctest标志（注释看起来像 # doctest: FLAG, ... ）在线条末端和 <BLANKLINE> 标记被单独移除（或不移除）。默认为 trim-doctest-flags .

备注

A中的代码 testcode 块总是同时执行，不管它包含多少语句。因此，输出将 not 为裸表达式生成--使用 print .例子：：

.. testcode::

   1+1         # this will give no output!
   print(2+2)  # this will give output

.. testoutput::

   4

另外，请注意，由于doctest模块不支持在同一代码段中混合常规输出和异常消息，因此这也适用于testcode/testoutput。

.. testoutput:: [group]¶

最后一个的对应输出或异常消息 testcode 块。

该指令支持四个选项：

hide 标志选项，在其他生成器中隐藏输出块。默认情况下，它显示为不加亮显的文本块。
options 字符串选项，可用于提供doctest标志（逗号分隔），就像在普通doctest块中一样。
trim-doctest-flags 和 no-trim-doctest-flags ，一个标志选项，doctest标志（注释看起来像 # doctest: FLAG, ... ）在线条末端和 <BLANKLINE> 标记被单独移除（或不移除）。默认为 trim-doctest-flags .

例子：：

.. 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 当用于不同指令时：

testsetup and testcleanup
- 有条件地跳过测试设置和/或清理
- 根据环境自定义设置/清理代码
doctest
- 有条件地跳过测试及其输出验证
testcode
- 有条件地跳过测试
- 根据环境自定义测试代码
testoutput
- 跳过测试的有条件跳过输出断言
- 根据不同的环境期望不同的输出

的值 skipif 选项的计算结果为python表达式。如果结果为真值，则在测试运行中省略该指令，就像它根本不存在于文件中一样。

而不是重复一个表达式， doctest_global_setup 可以使用配置选项将其分配给一个变量，然后使用该变量。

下面是一个示例，如果未安装Pandas，则跳过一些测试：

conf.py¶

extensions = ['sphinx.ext.doctest']
doctest_global_setup = '''
try:
    import pandas as pd
except ImportError:
    pd = None
'''

contents.rst¶

.. 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¶

默认情况下，启用这些选项：

ELLIPSIS ，允许在预期输出中放入与实际输出中的任何内容匹配的省略号；
IGNORE_EXCEPTION_DETAIL ，导致忽略最左边冒号后面的所有内容以及异常名称中的任何模块信息；
DONT_ACCEPT_TRUE_FOR_1 ，在给出“1”的输出中拒绝“true”——接受此替换的默认行为是2.2次python之前的遗留行为。

Added in version 1.5.

doctest_show_successes¶

默认为 True 。控制是否报告成功。

对于具有多个doctest的项目，将其设置为 False 以仅突出显示故障。

Added in version 7.2.

doctest_path¶: 将添加到的目录列表 sys.path 当使用doctest生成器时。（确保它包含绝对路径。）

doctest_global_setup¶: 被视为放入 testsetup 指令 每一个 测试的文件，以及每个组的文件。您可以使用它来导入doctest中始终需要的模块。

Added in version 0.6.

doctest_global_cleanup¶: 被视为放入 testcleanup 指令 每一个 测试的文件，以及每个组的文件。您可以使用它来删除测试留下的任何临时文件。

Added in version 1.1.

doctest_test_doctest_blocks¶

如果这是一个非空字符串（默认为 'default' ）也将测试标准的rest doctest块。它们将被分配给给定的组名。

其余的doctest块只是放入自己的段落中的doctest，就像这样：

Some documentation text.

>>> print(1)
1

Some more documentation text.

（注意没有特别的 :: 用于引入doctest块；docutils从前导识别它们 >>> . 此外，虽然不会造成伤害，但不会使用其他压痕。）

如果将此值保留为其默认值，则doctest生成器将对上述代码段进行如下解释：

Some documentation text.

.. doctest::

   >>> print(1)
   1

Some more documentation text.

此功能使您可以方便地测试随附的docstrings中的doctest autodoc 扩展而不使用特殊指令标记它们。

注意，尽管在rest doctest块中不能有空行。它们将被解释为一个块结束，另一个块开始。另外，移除 <BLANKLINE> 和 # doctest: 选项仅适用于 doctest 尽管你可以设置 trim_doctest_flags 在所有包含Python控制台内容的代码块中实现这一点。

Sphinx

On this page

Site navigation

`sphinx.ext.doctest` --文档中的测试片段¶

指令¶

有条件地跳过测试¶

配置¶

Sphinx

sphinx.ext.doctest --文档中的测试片段¶

指令¶

有条件地跳过测试¶

配置¶

`sphinx.ext.doctest` --文档中的测试片段¶