Python Docstring:提高与提高

Question

我使用PyCharm IDE来协助制作符合PEP0257标准的文档字符串.它提供了两个属性,我不完全理解它们之间的区别/用法:

• :raise Exception: exception explanation here
• :raises Exception: exception explanation here

我什么时候会在我的文档中使用raise反对raises？具体来说,如果一个类需要一个未提供的参数并引发一个TypeError,那应该用来记录它？

Answer 1

TL; DR

raises用于描述可能引发的异常.在运行autodoc时raise,Sphinx会识别它,并且与之相同raises.

完整解释

PyCharm有助于使用几种不同风格的文档字符串注释.

我经常使用的三个是:

1. NumPy格式
2. 谷歌格式
3. 狮身人面像(远远超过一种格式)

在所有这些中,有一个特殊的部分Raises,您可以在较旧版本的PyCharm代码测试中看到:

1. 简单的NumPy
2. 简单的谷歌

SphinxDocString我们可以看到这里的实现有很多可以识别的关键字.然后将这些标签链接到RAISES_TAGS可在此处找到的列表.

我希望这些信息有用.

Answer 2

您必须使用raises来描述您的方法/类引发的异常。

:raises:
    Exception: Explanation here.

例如，对于 ValueError 异常：

:raises:
    ValueError: if fft_data is empty.

Answer 3

对于任何感兴趣的人，这对我来说适用于最新版本的 PyCharm。

"""
Some explanations.

:raises WhatEverError: if there is any error
"""