doctest 严格比对文档字符串中模拟 python repl 的代码示例与实际输出，要求格式完全一致：包括 >>> 后空格、... 省略符、空行、异常 traceback 全貌等，任何空白或 repr 差异均导致失败。
doctest 能直接运行文档字符串里的代码示例，但前提是示例格式必须严格匹配 Python 交互式会话的输出——包括提示符 >>>、省略号 ... 的用法、空行规则，以及异常 traceback 的完整写法。
doctest 示例必须严格模拟 Python REPL 输出
它不是“执行任意代码”，而是把文档字符串当作一段真实的交互日志来比对。任何格式偏差都会导致测试失败，哪怕只是多了一个空格或少了一行空行。
-
>>>后必须紧跟一个空格，然后才是语句；...（三个英文点）用于表示被省略的 traceback 行或长输出，不能写成…或...（中文省略号或四点） - 表达式结果要写在下一行，且**不能带
>>>或...前缀**；如果结果是空行（比如函数返回None），文档里就得真写一个空行 - 异常测试必须包含完整的
Traceback (most recent call last):行、错误类型和消息，且所有行都要原样写出（可配合...省略中间帧）
def add(a, b):
"""
>>> add(2, 3)
5
>>> add('a', 'b')
'ab'
>>> add(1, '2')
Traceback (most recent call last):
...
TypeError: unsupported operand type(s) for +: 'int' and 'str'
"""
return a + b
运行 doctest 的三种常用方式
最直接的是用命令行跑整个模块：python -m doctest module.py；但默认不输出成功项，容易误以为没跑——加 -v 才能看到每个示例的通过/失败详情。
- 在模块末尾加
if __name__ == '__main__': doctest.testmod()，然后python module.py运行；testmod()默认只检查当前模块，不会递归导入的模块 - 用
doctest.testfile('example.txt')单独测试纯文本文件（如 README.rst），但文件里仍需用>>>标记代码块，且路径需手动指定 - 在 IDE（如 PyCharm）中右键运行时，可能默认不启用 doctest 支持，需确认是否勾选了 “Run doctests” 或在配置里指定
-m doctest
常见失败原因：空格、换行、repr 差异
doctest 对空白字符极其敏感。比如 print('hello') 的输出是 hello\n，而文档里如果写成 'hello'（带引号）就变成 repr() 结果，二者不等价。
- 字典、集合、浮点数顺序或精度不一致：Python 3.7+ 字典有序，但旧版本无序；浮点计算结果可能因平台略有差异，建议用
round(x, 5)或正则断言 - 系统相关输出（如文件路径、时间戳）无法固定，应避免写进 doctest；若必须测试，可用
# doctest: +ELLIPSIS或# doctest: +SKIP控制行为 - 多行字符串中的换行符在 Windows 和 Unix 下可能不同，建议统一用
\n并在 docstring 中用原始字符串r"""..."""
真正难的不是写几个示例，而是让所有示例在不同环境、不同 Python 版本、不同终端宽度下都稳定通过——这要求你对输出的每一处空格、换行、repr 规则都有明确预期。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
