doctest跳过带assert的函数的原因及二者搭配使用方法

• Python 规定函数的文档字符串（docstring）必须是函数体内部的第一个语句，只有满足该要求的字符串字面量才会被自动绑定到函数的__doc__属性中。
• doctest 模块的核心运行逻辑是扫描模块内所有函数、类的__doc__属性，从中提取符合格式的测试用例执行。
• 你将assert True放在函数首行后，原有的文档字符串不再是函数体的第一个语句，Python 不会将其识别为函数的 docstring，__doc__属性无对应测试内容，doctest 自然无法识别到测试用例。

优先推荐调整语句顺序，符合 Python 编码规范：

• 保持 docstring 为函数体的第一个语句，将所有 assert 语句放在 docstring 之后即可，不会影响 doctest 的正常识别，示例如下：

def add_one(x):
    """
    这是函数文档，包含doctest测试用例
    >>> add_one(2)
    3
    >>> add_one(-1)
    0
    """
    # assert语句放在文档字符串之后
    assert isinstance(x, int), "参数必须为整数"
    assert True
    return x + 1

如果确实有特殊需求需要将可执行语句放在文档前（不推荐），可以手动给函数绑定__doc__属性：

def add_one(x):
    assert isinstance(x, int), "参数必须为整数"
    assert True
    # 手动赋值__doc__属性，doctest仍能正常读取
    add_one.__doc__ = """
    >>> add_one(2)
    3
    >>> add_one(-1)
    0
    """
    return x + 1

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