笔记｜Python 的 doctest 使用方法

doctest，即在 docstring 中像 Python 交互式代码一样的文本，可以通过执行这些代码来检查它们是否可以像展示的那样正确运行。doctest 具有如下作用：

• 通过验证所有 doctest 是否按预期运行，来检查模块的 docstring 是否是最新的；
• 通过验证来自一个测试对象或一个测试文件的 doctest 是否按预期运行，来进行回归测试；
• 将 doctest 作为输入输出的例子，用以实现一种指导性文档。

doctest 的例子如下：

def fill_ends_missing(array: np.ndarray):
    """使用 numpy 数组首尾两端的第一个非缺失数据，填充 numpy 的首尾缺失（原地修改）

    Parameters
    ----------
    array : np.ndarray
        待填充缺失的数组

    Examples
    --------
    >>> arr = np.array([np.nan, np.nan, np.nan, 1, 2, 3, 4, np.nan, np.nan, np.nan])
    >>> fill_ends_missing(arr)
    >>> arr
    array([1., 1., 1., 1., 2., 3., 4., 4., 4., 4.])
    >>> arr = np.array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
    >>> fill_ends_missing(arr)
    >>> arr
    array([ 1,  2,  3,  4,  5,  6,  7,  8,  9, 10])
    >>> arr = np.array([np.nan, np.nan, np.nan, np.nan, np.nan])
    >>> fill_ends_missing(arr)
    >>> arr
    array([nan, nan, nan, nan, nan])
    >>> arr = np.array([np.nan, 2, np.nan, 4, np.nan])
    >>> fill_ends_missing(arr)
    >>> arr
    array([ 2.,  2., nan,  4.,  4.])
    """
    nan_array = ~np.isnan(array)

    if not np.any(nan_array):  # 如果数组全为 nan，则不做修改，直接返回
        return

    temp_1 = np.cumsum(nan_array)
    temp_2 = np.cumsum(nan_array[::-1])[::-1]
    temp_3 = np.logical_and(temp_1 > 0, temp_2 > 0)

    i_left = np.argmax(temp_3)  # 左侧第一个非空点下标
    i_right = temp_3.shape[0] - np.argmax(temp_3[::-1])-1  # 右侧第一个非空点下标

    array[:i_left] = array[i_left]  # 填充左侧开头缺失
    array[i_right:] = array[i_right]  # 填充右侧结尾缺失

doctest 的运行方法包括：

1. 在 PyCharm 中，在 doctest 上右键，选择 Run 'Doctest fil_ends_missing'（或 Ctrl + Shift + F10）

运行结果如下：

2. 使用 doctest 模块的 testmod() 方法执行

if __name__ == "__main__":
    import doctest

    failures, tries = doctest.testmod()
    print(failures, tries)

运行结果：

0 12

如果执行 doctest.testmod() 没有打印日志，则说明所有测试用例都成功运行了；doctest.testmod() 有两个返回值，第 1 个是失败用例的数量，第 2 个是运行用例的总数。