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

Question

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

观察:我正在考虑使用 Google 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() 的任何人来说都是显而易见的。调用它时可能发生的异常。