在 python 文档字符串中记录其他函数中可能发生的异常

Question

在 Python 中，我们是否应该在文档字符串中记录除了当前函数/方法主体中提出的函数/类之外可以在其他函数/类中引发的异常？

Obs.：我正在考虑谷歌Python文档字符串风格的 https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html

我已经很久没有玩Java了，但是在那里你会明确地说出你的方法可能会用"throws"关键字引发什么样的异常。

例如：

class MyException(Exception):
pass
class A(object):
def foo(self):
"""This class does foo
Returns:
Int: The number of foo.
Raises:
MyException - In case something happen
"""
if True:
raise MyException
return 0
class B(object):
def __init__(self):
self._a = A()
def bar(self):
"""This class does bar
Returns:
Int: number of bar
Raises:
MyException ????? Should this be here?
"""
return self._a.foo()

Answer 1

是的，您应该记录bar()(和foo()(可以引发MyException。这样，对于任何即将使用bar()的人来说，调用它时可能发生的异常都是显而易见的。