Question

在python中编写doc字符串时，我想知道docstring是否应该包含隐式引发的异常，或者它是否还应该包含我明确提出的异常。

考虑功能

def inv(a):
    if a == 0:
        raise ZeroDivisionError
    else:
        return 1/a

因此，在“Raises”关键字下的文档字符串中，我肯定会放置ZeroDivisionError。但是，根据输入，我也会期望TypeError。那么你也会把它放在docstring中吗？

由于EAFP原则（如果我理解正确的话）我不想在这里检查类型，对吗？任何提示（也在代码示例上）都是受欢迎的。

Answer 1

这取决于你为什么（或谁）编写文档字符串。对于自动转换为API文档，我喜欢Google-style docstrings，它看起来像：

def inv(a):
    """Return the inverse of the argument.

    Arguments:
      a (int): The number to invert.

    Returns:
      float: The inverse of the argument.

    Raises:
      TypeError: If 1 cannot be divided by the argument.
      ZeroDivisionError: If the argument is zero.

    """
    return 1 / a

这里我已经包含了该函数可能引发的所有异常。请注意，不需要明确raise ZeroDivisionError - 如果您尝试除以零，这将自动发生。

但是，如果您不是从docstring创建文档，我可能只需要包含这样一个简单函数的描述行：

def inv(a):
    """Return the inverse of the argument."""
    return 1 / a

使用它的任何人都可能知道你无法反转，例如字符串。

我不想在这里检查类型，对吗？

我不会 - 如果用户在阅读您的文档后决定通过，例如一个字符串进入他们应该期望获取TypeError的函数，并且没有必要测试参数类型然后自己引发相同的异常，无论如何代码都会引发（同样，请参阅也是ZeroDivisionError！）即，除非例如float或complex数字应该是无效输入，在这种情况下，您需要手动处理它们。

Answer 2

没有。 docstring应该描述预期的输入。如果这是我的功能，我会在docstring中包含这样的内容：

"""Return the inverse of an integer.  ZeroDivisionError is raised if zero is
passed to this function."""

因此指定输入应为整数。指定该函数可以引发TypeError只会过度复杂化文档字符串。

docstring是否应该只包含函数显式引发的异常？

2 个答案: