Python 3.x 中如何使用 doctest 模块进行文档测试

引言：
在编写代码的过程中，经常需要写文档来解释函数或类的使用方法和预期输出。然而，文档容易变得过时或者不准确，这就会导致出现预期意外或错误的结果。为了解决这个问题，Python 提供了一个内置模块 doctest，它允许你编写文档字符串中的示例代码，并在执行时检查是否符合预期结果。

一、doctest 模块简介
doctest 模块是 Python 的一个内置模块，它提供了一种简单而可靠的方法来测试代码示例。它通过执行文档字符串中给定的示例代码，并验证其输出与预期输出是否匹配。doctest 将编写文档和编写测试合二为一，使得测试更加易于维护。

二、如何编写 doctest
在编写 doctest 时，我们需要在模块、函数或方法的文档字符串中编写示例代码，并在预期结果后使用 >>> 标记来表示示例代码和预期输出。比如以下的例子：

def add(a, b):
    """
    计算两个数的和
    
    示例：
    >>> add(2, 3)
    5
    
    >>> add(10, 5)
    15
    """
    return a + b

三、如何执行 doctest
我们可以使用 doctest 模块提供的 testmod() 函数来执行 doctest。这个函数会自动查找模块中的文档字符串并执行其中的示例代码，然后和预期输出进行比对。

import doctest

doctest.testmod()

四、运行结果
执行 doctest 后，如果所有示例代码的输出与预期输出相符，那么输出为空；如果有示例代码的输出与预期输出不符，那么会打印出错误信息。

下面是示例代码的运行结果：

**********************************************************************
File "example.py", line 5, in __main__.add
Failed example:
    add(2, 3)
Expected:
    5
Got:
    6
**********************************************************************
File "example.py", line 9, in __main__.add
Failed example:
    add(10, 5)
Expected:
    15
Got:
    16
**********************************************************************
1 items had failures:
   2 of   2 in __main__.add
***Test Failed*** 2 failures.

在这个例子中，我们可以看到有两个测试用例(add(2, 3) 和 add(10, 5))的结果与预期输出不符，因此 doctest 报告了两个失败。

五、如何扩展 doctest
除了简单的示例代码和预期输出之外，doctest 还支持更多高级的测试方式。比如，我们可以使用 ... 来表示多行输出，使用 # 来表示注释等。下面是一个更复杂的示例：

def average(numbers):
    """
    计算列表中数字的平均值
    
    示例：
    >>> average([1, 2, 3, 4, 5])
    3
    
    >>> average([10, 20, 30])
    20
    
    >>> average([])
    0
    
    >>> average([1, 2, 3, 4, 5, ...])
    3
    """
    if len(numbers) == 0:
        return 0
    return sum(numbers) / len(numbers)

这个示例使用了 ... 来表示多行输出，在最后一个示例中我们用 ... 来表示该列表后面还有更多的元素，但并不关心它们具体是什么。

六、结论
本文介绍了 Python 3.x 中如何利用 doctest 模块进行文档测试，它可以帮助我们编写清晰、准确的文档，并通过自动化测试来验证文档的正确性。通过编写测试用例的方式，我们可以更好地理解函数或类的使用方法，并确保它们能按预期工作。

通过合理使用 doctest 模块，可以大大提高代码质量和可维护性。建议在编写代码时，为函数和类编写文档字符串，并在其中编写测试用例。这将有助于保持代码的可靠性，并为其他人在阅读文档时提供实用的示例代码。