Python Docstring: raise vs. raises
Solution 1
TL;DR
raises
is used to describe the possible exceptions being raised. raise
is recognized by Sphinx when running autodoc and is the same as raises
.
Full Explanation
PyCharm helps in using a few different styles of docstring comments.
Three which I often use are:
- NumPy Format
- Google Format
- Sphinx (much more than a format)
In all of these there is a special section for Raises
which you can see in an older version of the PyCharm code tests:
The implementation for SphinxDocString
we can see here there there are numerous keywords which can be recognized. Those tags then link to the list of RAISES_TAGS
which can be found here.
I hope this information is useful.
Solution 2
You must use raises
to describe exceptions raised by your method/class.
:raises:
Exception: Explanation here.
For example, for a ValueError exception:
:raises:
ValueError: if fft_data is empty.
Solution 3
This works for me in latest version of PyCharm for anyone interested.
"""
Some explanations.
:raises WhatEverError: if there is any error
"""
![Bob Dylan](https://i.stack.imgur.com/uAPUq.jpg?s=256&g=1)
Bob Dylan
Updated on July 05, 2022Comments
-
Bob Dylan almost 2 years
I use the PyCharm IDE which assists with crafting PEP0257-compliant docstrings. It provides two attributes I don't entirely understand the distinction/use between:
:raise Exception: exception explanation here
:raises Exception: exception explanation here
When would I use
raise
as opposes toraises
in my docstring? Specifically, if a class required an argument that was not provided and raises aTypeError
, which should be used to document that? -
Noumenon over 4 yearsSince the SphinxDocString also recognizes
raises
, that is what I am going to use. -
MikeyE over 4 yearserik-e's answer is also good. I like this one because it provides an example.
-
Dean Gurvitz over 3 yearsNote that the second colon needs to be after the exception name
-
aqm over 2 yearsalso working in latest intellij too, as of 11/2021