在函数的文档字符串的“引发”部分中，是否也应该间接列出引发的异常？

问题描述

例如，对于：

def foo(a):
    if a == 10:
        raise FooError
    return 1 / a

foo的文档字符串中应包含以下内容：

"""Raises:
    FooError: if a is equal to 10.
    ZeroDivisionError: if a is equal to 0.
"""

还是应该只列出函数本身引发的异常，即。 e。 FooError？谢谢任何关于更好的见解。

解决方法

TLDR：列出与代码用户相关的所有例外情况，而与实现无关。

---

文档字符串针对功能/类的用户。就像适当的类接口一样，docstring不应与函数/类的实现细节有关。文档字符串的内容应仅反映内容，而不是方法。

这意味着在同一事物的不同实现之间，是否记录错误应该不有所不同。

---

考虑将引发错误的代码移至帮助程序：

class Bar:
    def foo(self,a):
        if a == 10:
            raise FooBarError
        return 1 / a

    def bar(self,a):
        self._reject(a,10)
        return 1 / a

    def _reject(self,value,forbidden):
        if value == forbidden:
            raise FooBarError

foo和bar在功能上均等同于客户端代码。它们的内部验证逻辑仅仅是实现细节，不会改变使用它们的方式。