docstring-extraneous-exception (DOC502)

源自 pydoclint 代码检查器。

此规则不稳定且处于预览状态。使用需要 --preview 标志。

作用

检查函数文档字符串，其中声明可能会引发异常，即使它们没有直接在函数体中引发。

为什么这不好？

一些约定倾向于从文档字符串中省略非显式异常。

此规则不适用于抽象方法。 对于“存根函数”也会被忽略：即函数体仅包含pass、...、raise NotImplementedError或类似内容。

示例

def calculate_speed(distance: float, time: float) -> float:
    """Calculate speed as distance divided by time.

    Args:
        distance: Distance traveled.
        time: Time spent traveling.

    Returns:
        Speed as distance divided by time.

    Raises:
        ZeroDivisionError: Divided by zero.
    """
    return distance / time

建议改为

def calculate_speed(distance: float, time: float) -> float:
    """Calculate speed as distance divided by time.

    Args:
        distance: Distance traveled.
        time: Time spent traveling.

    Returns:
        Speed as distance divided by time.
    """
    return distance / time

已知问题

通常最好记录一个函数可能引发的所有异常，即使那些没有使用函数体中的raise语句显式引发的异常。