Python Docstring: raise vs. raises
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:
- Simple NumPy
- Simple Google
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.
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.