为未明确引发异常的函数定义文档字符串引发
Defining docstring raises for functions not explicitly raising exception
import requests
def example():
"""
An example function
:raises KeyError: ?
:raises HttpError: ?
"""
result: Dict = do_something()
log(result["key"])
response = requests.get(url)
return response
上述函数没有明确引发任何异常，但可以看出，它的执行可能会引发 KeyError 和 HTTPError。在文档字符串中提及这些可以吗？最佳做法是什么？
如果异常与使用应该记录的函数的人相关（并且它们是间接的）
这对于评论来说太长了，但这也不是答案，因为它的某些部分相互矛盾。
不关心因使用不当或计算机问题导致磁盘已满等阻止正常程序运行的异常。
如果在正确使用函数时会发生一些异常（应该记录这意味着什么），它们是接口的一部分，应该记录下来。
网络充满了超时、中断、连接失败，所以它们可能被认为是正常的。
例如 requests.get 本身并没有提到它可能引发的异常 (link: https://docs.python-requests.org/en/latest/_modules/requests/api/#get)。它说你会得到回应。但是如果没有有效的回应，你能得到什么？一个例外，没有别的。所以是“暗示”。
import requests
def example():
"""
An example function
:raises KeyError: ?
:raises HttpError: ?
"""
result: Dict = do_something()
log(result["key"])
response = requests.get(url)
return response
上述函数没有明确引发任何异常，但可以看出，它的执行可能会引发 KeyError 和 HTTPError。在文档字符串中提及这些可以吗？最佳做法是什么？
如果异常与使用应该记录的函数的人相关（并且它们是间接的）
这对于评论来说太长了，但这也不是答案，因为它的某些部分相互矛盾。
不关心因使用不当或计算机问题导致磁盘已满等阻止正常程序运行的异常。
如果在正确使用函数时会发生一些异常（应该记录这意味着什么），它们是接口的一部分，应该记录下来。
网络充满了超时、中断、连接失败，所以它们可能被认为是正常的。
例如
requests.get本身并没有提到它可能引发的异常 (link: https://docs.python-requests.org/en/latest/_modules/requests/api/#get)。它说你会得到回应。但是如果没有有效的回应，你能得到什么？一个例外，没有别的。所以是“暗示”。