Repolode
提交项目
Erotemic

Erotemic/xdoctest

一个运行 Python 文档字符串中示例代码的工具，基于 AST 解析重写了内置 doctest 模块。

在 GitHub 查看
Star
221
Fork
18
未关闭 Issue
29
最近提交
3天前

这是什么？

Xdoctest 用于执行 doctest，即写在 Python 文档字符串里的示例代码。它是标准库 doctest 模块的重写版本，用基于 Python ast 模块的解析器替代了原来基于正则表达式的解析方式，因此每一行都可以统一使用 >>> 前缀，多行字符串也不需要特殊前缀。

可以通过命令行 xdoctest 指定模块或包路径运行，也可以在 pytest 中加上 --xdoctest 参数启用。原生运行器支持列出所有 doctest、运行全部示例，或按函数名只运行某一个，还能按名字运行无参数函数。解析方面同时支持 Google 风格的 Example 块和自由格式的 >>> 块。

默认的输出比对较为宽松：忽略空白差异，支持 ELLIPSIS 省略匹配，只要标准输出或最终返回值之一匹配即通过。没有 want 语句的测试只需运行不报错即可，因此也可以直接用 assert 做检查。

核心功能

  • 01使用 Python ast 模块解析 doctest，而非正则表达式。
  • 02每一行都可以加 >>> 前缀，无需区分 PS1 与 PS2 行。
  • 03通过 --xdoctest 参数与 pytest 集成。
  • 04提供原生命令行工具，可列出、全部运行或单独运行某个 doctest。
  • 05同时支持 Google 风格和自由格式的 doctest 解析。

适用场景

  • 在 CI 中与单元测试一起运行文档字符串里的用法示例。
  • 在代码变更后检查 Python 包的文档示例是否仍能正常运行。
  • 开发函数时在文档字符串中编写演示输入，并作为测试复用。

快速上手

  1. 1

    从 PyPI 安装 xdoctest

    pip install xdoctest
  2. 2

    运行包或模块中的所有 doctest

    python -m xdoctest /path/to/your/pkg-or-module.py

使用前须知

  • 需要 Python 3.8 或更高版本。

收录于专题

测试框架与自动化测试工具

标签

#python#doctest#testing#pytest#docstrings#pytest-plugin

常见问题

xdoctest 是什么？
一个运行 Python 文档字符串中示例代码的工具，基于 AST 解析重写了内置 doctest 模块。 Xdoctest 用于执行 doctest，即写在 Python 文档字符串里的示例代码。它是标准库 doctest 模块的重写版本，用基于 Python ast 模块的解析器替代了原来基于正则表达式的解析方式，因此每一行都可以统一使用 >>> 前缀，多行字符串也不需要特殊前缀。
xdoctest 可以免费使用吗？用的什么许可证？
xdoctest 以 Apache-2.0 许可证开源。用于商业产品前，请先确认许可证条款。
xdoctest 还在维护吗？
活跃维护中。xdoctest 最近一次提交是在 2026年11月4日。
xdoctest 适合用来做什么？
在 CI 中与单元测试一起运行文档字符串里的用法示例。 在代码变更后检查 Python 包的文档示例是否仍能正常运行。 开发函数时在文档字符串中编写演示输入，并作为测试复用。
xdoctest 怎么安装和运行？
从 PyPI 安装 xdoctest: pip install xdoctest 运行包或模块中的所有 doctest: python -m xdoctest /path/to/your/pkg-or-module.py
在哪里获取 xdoctest？
源代码和安装说明在 GitHub 上：https://github.com/Erotemic/xdoctest

概要由 AI 根据项目 README 生成；GitHub 数据每日更新。

相关项目