Python Docstring: raise vs. raises
Question:
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 to raises in my docstring? Specifically, if a class required an argument that was not provided and raises a TypeError, which should be used to document that?
Answers:
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.
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.
This works for me in latest version of PyCharm for anyone interested.
"""
Some explanations.
:raises WhatEverError: if there is any error
"""
Here’s an addition to the previous answers.
If you want to specify multiple raises in one docstring, you have to rewrite the raises keywork, as specified in the Sphinx documentation:
"""
Explanation.
:param str par1: The first param
:param par2: The second param
:type par2: integer or None
:return: The returned value
:rtype: int
:raises ValueError: If ...
:raises TypeError: If ...
"""
Tested on PyCharm v2022.3.2
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 to raises in my docstring? Specifically, if a class required an argument that was not provided and raises a TypeError, which should be used to document that?
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.
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.
This works for me in latest version of PyCharm for anyone interested.
"""
Some explanations.
:raises WhatEverError: if there is any error
"""
Here’s an addition to the previous answers.
If you want to specify multiple raises in one docstring, you have to rewrite the raises keywork, as specified in the Sphinx documentation:
"""
Explanation.
:param str par1: The first param
:param par2: The second param
:type par2: integer or None
:return: The returned value
:rtype: int
:raises ValueError: If ...
:raises TypeError: If ...
"""
Tested on PyCharm v2022.3.2