怎么用python-mdoctest测文档里的示例?

季宁
季宁
发布时间:2026-11-20| 6人浏览过
原创

详细讲解如何使用 python -m doctest 自动化测试 Markdown、reStructuredText 及纯文本文档中的 Python 示例代码,包含 REPL 语法规范、调试比对技巧、高级指令及 CI 自动化落地。

怎么用python-mdoctest测文档里的示例?

在维护开源库或接口文档时,最常见的技术脱节莫过于文档里的代码无法运行——函数改了参数、重构调整了返回值,而文档里的示例依然停留在几个月前的老版本,直接导致初学者复制代码后遭遇报错。解决这个问题的直接手段,就是使用 Python 原生内置的 doctest 模块,即通过命令行 python -m doctest 目标文档路径,直接提取 Markdown、reStructuredText 或纯文本中的交互式代码段并自动执行测试。本文将拆解如何书写规范的交互式文档代码、如何运行与排查差异,以及如何将文档测试接入持续集成流程。

一、python -m doctest 的核心机制

开发者常说的 python-mdoctest,实际上是指通过 Python 解释器的 -m 开关运行内置的 doctest 模块。Python 官方文档通常将 doctest 用在代码文件的 docstring 内部,但它同样原生支持对独立文本文件(如 README.md、tutorial.rst 或纯文本文件)进行全量扫描。

当执行 python -m doctest 文件名 时,测试引擎并不会关心外层的文档排版、图片或非代码文字,而是逐行扫描文本流,专门定位带有 Python 交互式提示符(即 >>> 和连续输入提示符 ...)的代码行。引擎会在一个独立的命名空间中执行这些指令,抓取标准输出与求值结果,再与紧随其后的文本行进行精确比对。如果输出完全相符,则判定用例通过;若存在字符差异或抛出未声明的异常,则打印差异报告(Diff)并抛出非零退出码。

怎么用python-mdoctest测文档里的示例?
图 1:python -m doctest 对文档的扫描、求值与比对判定执行流

二、文档内代码示例的正确书写规范

许多开发者尝试在 Markdown 中运行 python -m doctest 时失败,根本原因并非工具本身,而是代码块的书写方式不符合 doctest 的语法要求。doctest 原生模拟的是 Python 终端交互式命令行(REPL)的输入输出形态,而不是常规的纯脚本文件。

1. 关键书写规则

  • 必须带有 REPL 提示符: 每段待测代码的首行必须以 >>> (三个大于号加一个空格)开头。如果不写 >>>,doctest 会将其视为普通的叙述性文字而直接跳过。
  • 多行代码与缩进使用 ...: 如果代码包含函数定义、if 分支或跨行列表,后续行必须以 ... (三个英文点加一个空格)开头,保持与 Python 交互式命令行一致的缩进格式。
  • 预期输出紧随其后: 表达式求值结果或 print() 输出必须紧跟在命令行的下一行,不要加 >>>。
  • 空行截断规则: doctest 默认将代码下方的首个空白行视为“输出结束标记”。如果示例的预期输出本身包含空行,需要使用特殊占位符 <BLANKLINE> 标记。
怎么用python-mdoctest测文档里的示例?
图 2:可被 doctest 识别的 REPL 结构与常规代码块的书写对比

三、具体操作步骤:从本地执行到验证诊断

掌握了格式规范后,我们可以通过一个完整的演练过程,在本地运行文档测试并理解其反馈机制。

第 1 步:创建待测文档

在项目根目录下创建一个 README.md,写入以下包含基础运算、导入和异常场景的交互式示例:

# 数学工具箱示例

这是一个演示文档。以下代码块展示了模块的核心用法:

```python
>>> from math import ceil, floor
>>> ceil(4.2)
5
>>> floor(4.8)
4
>>> 1 / 0
Traceback (most recent call last):
  ...
ZeroDivisionError: division by zero
```

第 2 步:运行基础测试命令

在终端中切换到该文件所在目录,执行以下命令:

python -m doctest README.md

如果没有任何屏幕输出,且终端返回码为 0,这代表文档内的所有用例全部测试通过。为了确认其退出状态码,可以在 Linux/macOS 终端紧接着输入 echo $?(Windows CMD 对应 echo %ERRORLEVEL%),返回值应为 0。

第 3 步:开启详细模式(-v)查看测试明细

在开发或调试阶段,直接返回空白往往让人缺乏直观感受。添加 -v(verbose)参数可以列出每个用例的尝试细节、期望值以及判定结果:

python -m doctest -v README.md
终端示例输出(-v 模式)
Trying:
    from math import ceil, floor
Expecting nothing
ok
Trying:
    ceil(4.2)
Expecting:
    5
ok
Trying:
    floor(4.8)
Expecting:
    4
ok
Trying:
    1 / 0
Expecting:
    Traceback (most recent call last):
      ...
    ZeroDivisionError: division by zero
ok
1 items passed all tests:
   4 tests in README.md
4 tests in 1 items.
4 passed and 0 failed.
Test passed.
怎么用python-mdoctest测文档里的示例?
图 3:从文档示例编写到命令行诊断与 CI 验证的标准四步实战闭环

四、处理常见比对失败与高频指令(Directives)

在实际测试中,直接字面比对往往会遭遇动态数据的干扰。例如对象的内存地址(<object at 0x7fa...>)、浮点数末尾微小扰动、多重空格或者异常堆栈里的环境绝对路径。直接比对必然导致测试崩溃。Python 为此提供了内联指令系统(Directives),以注释形式写在待测行末尾,灵活控制比对策略。

1. 省略动态不确定内容:+ELLIPSIS

当输出内容包含会随环境变化的动态字符(如内存地址、时间戳或超长列表中间部分)时,在代码行末尾加上 # doctest: +ELLIPSIS,即可用 ... 代表任意长度的字符:

```python
>>> class User:
...     pass
>>> User() # doctest: +ELLIPSIS
<__main__.User object at 0x...>
```

2. 忽略空白符差异:+NORMALIZE_WHITESPACE

Markdown 渲染或排版时,连续空格、制表符或换行符容易被意外合并或修改。+NORMALIZE_WHITESPACE 会将多余的连续空白字符视作单个空格,并允许跨行对其:

```python
>>> [1, 2, 3, 4, 5] # doctest: +NORMALIZE_WHITESPACE
[1, 2,
 3, 4, 5]
```

3. 跳过特定示例:+SKIP

如果某些文档示例依赖特定操作系统环境、需要网络连接或执行时间过长,可以使用 +SKIP 跳过当前行:

```python
>>> import os
>>> os.remove('/etc/hosts') # doctest: +SKIP
```
实用建议: 如果一个示例需要组合多个指令,可以用逗号在注释中连续声明,例如:# doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE。

五、工程化落地:接入 CI/CD 与 Pytest

仅靠开发者在本地手动运行 python -m doctest 难以彻底杜绝文档腐化。最有效的实践是将其固化为团队提交代码时的强制卡点。

1. 与 Pytest 深度整合

现代化 Python 项目通常使用 pytest 作为统一测试运行器。通过安装并指定参数,pytest 可以直接在执行常规单元测试的同时,自动搜寻 Markdown 文档并运行其中的 doctest:

pytest --doctest-glob="*.md"

如果希望项目每次运行 pytest 时默认测试文档,可以在根目录的 pyproject.toml 或 setup.cfg 中固化配置:

# pyproject.toml 配置示例
[tool.pytest.ini_options]
addopts = "--doctest-modules --doctest-glob='*.md'"

2. GitHub Actions 自动化门禁

在持续集成流水线中加入文档测试步骤非常轻量,不需要安装重型依赖:

# .github/workflows/docs-test.yml
name: 文档示例自动化测试

on: [push, pull_request]

jobs:
  test-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: 设置 Python 环境
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - name: 安装项目依赖
        run: |
          pip install .
      - name: 运行 README 文档测试
        run: |
          python -m doctest README.md
怎么用python-mdoctest测文档里的示例?
图 4:doctest 覆盖语法、指令、诊断与自动化工程四层防护体系

六、总结与实践建议

通过 python -m doctest 文档路径 测试 Markdown 或文本中的代码,核心价值不仅在于验证代码本身是否能跑通,更在于促使维护者以严肃的态度对待文档中的每一处承诺。文档不再只是静止的说明文本,而是整个项目测试用例集的一部分。

在实际落地时,建议保持两点原则:一是示例尽量小而精,将复杂流程拆解为简明输入输出,避免在文档中编写耗时过长或依赖复杂外部环境的代码;二是善用内联指令化解偶发抖动,使用 +ELLIPSIS 和 +NORMALIZE_WHITESPACE 保持比对的鲁棒性。配合 CI 自动构建流水线,即可在最低维护成本下,永久终结“文档代码一跑就错”的尴尬局面。

相关专题:

免责声明:本文内容仅供参考,不代表本站观点。转载或引用请注明出处。

Python 相关产品和应用

全部下载
Selenium

Selenium

4.51.0 · Windows

用于浏览器自动化和 Web 测试的 Python 工具。

scikit-learn

scikit-learn

1.9.1 · Windows

常用 Python 机器学习算法与模型评估工具库。

Black

Black

26.10.1 · Windows

强调一致性的 Python 自动代码格式化工具。

Ruff

Ruff

0.17.1 · macOS

由 Rust 编写的高速 Python 代码检查和格式化工具。

pytest

pytest

9.1.1 · Windows

简洁而强大的 Python 自动化测试框架。

FastAPI

FastAPI

0.146.0 · Windows

高性能 Python API 框架,支持类型提示和自动接口文档。

Flask

Flask

3.1.3 · Windows

轻量灵活的 Python Web 应用框架。

Django

Django

6.1.2 · Windows

成熟的 Python Web 框架,适合构建内容站点和业务系统。

Spyder

Spyder

6.1.7 · Windows

面向科学计算与数据分析的 Python 集成开发环境。

SciPy

SciPy

1.18.1 · Windows

面向科学、工程和技术计算的 Python 算法库。