为何模块变量会导致模块doctest失效？附示例解析

这是因为Python的模块级字符串字面量只有在它是模块中第一个非注释、非空的语句时，才会被识别为模块的文档字符串（docstring）。而doctest默认会扫描模块的文档字符串以及函数/类的文档字符串来查找测试用例。

当你取消注释a = 3这一行后，原本位于模块最开头的那个包含doctest用例的字符串不再是模块的第一个语句，它就变成了一个普通的字符串字面量，doctest不会再扫描它，自然就找不到测试用例，看起来像是“停止工作”了。

解决方法 #

• 把包含测试用例的字符串移到模块的最开头，确保它是第一个非注释、非空语句
• 将测试用例放到目标函数的文档字符串中，示例如下：

def factorial(n):
    """
    >>> factorial(5)
    10
    """
    import math
    if not n >= 0:
        raise ValueError("n must be >= 0")
    if math.floor(n) != n:
        raise ValueError("n must be exact integer")
    if n+1 == n:  # 捕获类似1e300的数值
        raise OverflowError("n too large")
    result = 1
    factor = 2
    while factor <= n:
        result *= factor
        factor += 1
    return result

这样不管模块开头有没有其他变量定义，doctest都会扫描函数的文档字符串找到测试用例。

内容的提问来源于stack exchange，提问作者Rufus