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

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

考虑这个功能

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

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

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

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

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应该是无效输入，在这种情况下你需要手动处理它们。

不可以。文档字符串应该描述预期的输入。 如果这是我的功能，我会在docstring中包含这样的内容：

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

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

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

问题描述

1楼

2楼