Python中doctest如何嵌入代码？

doctest通过在文档字符串中嵌入交互式示例来测试代码，使用>>>表示输入和期望输出，运行方式包括在模块中调用doctest.testmod()或命令行执行python -m doctest，支持多行输出、异常处理及模糊匹配，适用于函数、类和模块的docstring，确保文档与代码一致性。

在Python中，doctest通过将测试用例写在函数、类或模块的文档字符串（docstring）中来嵌入源码。这些测试看起来就像在交互式Python解释器中的输入输出，doctest会自动提取并运行它们。

基本格式：
在三引号的文档字符串里，使用>>>表示输入，后接期望的输出。例如：

def add(a, b):
    """
    返回两个数的和。

    >>> add(2, 3)
    5
    >>> add(-1, 1)
    0
    """
    return a + b

如何运行嵌入的doctest？

方法一：在代码末尾添加以下内容，直接运行模块：

if __name__ == "__main__":
    import doctest
    doctest.testmod()

保存为 calc.py 后，在命令行执行：
python calc.py —— 如果没有输出，说明所有测试通过。
加上 -v 参数可查看详细过程：python calc.py -v

方法二：从命令行单独运行doctest：

python -m doctest calc.py
python -m doctest -v calc.py  # 显示详情

支持多行输出与异常测试

doctest能处理复杂场景，比如多行返回值或异常：

def divide(a, b):
    """
    执行除法，b为0时抛出异常。

    >>> divide(6, 2)
    3.0

    >>> divide(1, 3)  # doctest: +ELLIPSIS
    0.33...

    >>> divide(1, 0)  # doctest: +IGNORE_EXCEPTION_DETAIL
    Traceback (most recent call last):
    ZeroDivisionError: division by zero
    """
    return a / b

• 使用 # doctest: +ELLIPSIS 可模糊匹配部分输出。
• # doctest: +IGNORE_EXCEPTION_DETAIL 忽略异常类型的细节，只检查是否抛出指定异常。

适用位置灵活

doctest可嵌入：

• 函数的 docstring
• 类的 docstring
• 模块的 docstring（文件开头）

只要包含符合格式的交互示例，都能被识别和执行。

基本上就这些。把测试写进文档，既保证了文档的准确性，又实现了轻量级测试。