Python Docstring: raise vs. raises

PythonDocumentationDocstring

Python Problem Overview

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?

Python Solutions

Solution 1 - Python

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:

  1. NumPy Format
  2. Google Format
  3. 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:

  1. Simple NumPy
  2. 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.

Solution 2 - Python

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 - Python

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

"""
Some explanations.

:raises WhatEverError: if there is any error
"""
Categories
Recommended Python Solutions
Recommended Documentation Solutions
Recommended Docstring Solutions

Previous Solution:

How to force handler to run before executing a task in Ansible?

AnsibleAnsible Handlers

Next Solution:

Differencies between git add and git stage command

Git

Attributions

All content for this solution is sourced from the original question on Stackoverflow.

The content on this page is licensed under the Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) license.

Content TypeOriginal AuthorOriginal Content on Stackoverflow
QuestionBob DylanView Question on Stackoverflow
Solution 1 - Pythonerik-eView Answer on Stackoverflow
Solution 2 - PythoneduardosufanView Answer on Stackoverflow
Solution 3 - PythonErfan AkhavanView Answer on Stackoverflow