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?

score 119 · Accepted Answer · edited Nov 18 '22 at 10:44

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.

Since the SphinxDocString also recognizes `raises`, that is what I am going to use. — Noumenon, Nov 09 '19 at 20:06

score 18 · Answer 2 · answered Sep 17 '19 at 15:11

18

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.

answered Sep 17 '19 at 15:11

eduardosufan

1,441
2
23
51

2

erik-e's answer is also good. I like this one because it provides an example. – MikeyE Feb 08 '20 at 05:40
1

Note that the second colon needs to be after the exception name – Dean Gurvitz Dec 20 '20 at 07:43

score 17 · Answer 3 · answered Apr 27 '20 at 19:57

17

This works for me in latest version of PyCharm for anyone interested.

"""
Some explanations.

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

answered Apr 27 '20 at 19:57

Erfan Akhavan

316
2
7

2

also working in latest intellij too, as of 11/2021 – aqm Nov 18 '21 at 14:12

score 0 · Answer 4 · answered Feb 03 '23 at 07:39

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

Python Docstring: raise vs. raises

4 Answers4