当用 python 编写文档字符串时,我想知道文档字符串是否应该包含隐式引发的异常,或者是否还应该包含我显式引发的异常。
考虑功能
def inv(a):
if a == 0:
raise ZeroDivisionError
else:
return 1/a
因此,在“Raises”关键字下的文档字符串中,我肯定会放置 ZeroDivisionError。然而,根据输入,我也期望出现类型错误。那么你会把它也放在文档字符串中吗?
由于 EAFP 原则(如果我理解正确的话),我不想在这里检查类型,对吗?
欢迎任何提示(也包括代码示例)。
这取决于您为什么(或谁)编写文档字符串。对于自动转换为API文档,我喜欢Google 风格的文档字符串 http://sphinxcontrib-napoleon.readthedocs.org/en/latest/example_google.html,看起来像:
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
- 如果您尝试除以零,这会自动发生。
但是,如果您不从文档字符串创建文档,我可能只会包含这样一个简单函数的描述行:
def inv(a):
"""Return the inverse of the argument."""
return 1 / a
使用它的任何人都可能知道你不能反转,例如字符串。
我不想在这里检查类型,对吗?
我不会 - 如果用户在阅读您的文档后决定通过,例如一个字符串到他们应该的函数中expect得到TypeError
,并且测试参数类型然后自己引发代码无论如何都会引发的相同异常是没有意义的(再次,另请参阅ZeroDivisionError
!)也就是说,除非例如float
or complex
数字应该是无效输入,在这种情况下您需要手动处理它们。
本文内容由网友自发贡献,版权归原作者所有,本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容,请联系:hwhale#tublm.com(使用前将#替换为@)