Python Docstring: повышение по сравнению с рейзами

Я использую среду PyCharm, которая помогает с созданием согласованных с PEP0257 докстеров. Он предоставляет два атрибута, которые я не совсем понимаю различие/использование между:

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

Когда я буду использовать raise как противопоставляющий raises в моей docstring? В частности, если классу требуется аргумент, который не был предоставлен, и возникает сообщение TypeError, которое должно использоваться для документирования этого?

Ответ 1

TL; DR

raises используется для описания возможных исключений. raise распознается Sphinx при запуске autodoc и совпадает с raises.

Полное объяснение

PyCharm помогает использовать несколько разных стилей комментариев docstring.

Три, которые я часто использую:

Формат NumPy
Формат Google
Sphinx (гораздо больше, чем формат)

Во всех этих случаях существует специальный раздел для raises, который вы можете увидеть в старой версии тестов кода PyCharm:

Реализация для SphinxDocString мы можем видеть здесь, есть многочисленные ключевые слова, которые можно распознать. Затем те теги ссылаются на список RAISES_TAGS, который можно найти здесь.

Я надеюсь, что эта информация полезна.

Ответ 2

Вы должны использовать raises для описания исключений, вызванных вашим методом/классом.

:raises:
    Exception: Explanation here.

Например, для исключения ValueError:

:raises:
    ValueError: if fft_data is empty.