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.
Answer from erik-e on Stack OverflowTL;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.
This works for me in latest version of PyCharm for anyone interested.
"""
Some explanations.
:raises WhatEverError: if there is any error
"""
python 3.x - Exception in docstring python3 - Stack Overflow
Documenting exceptions that can happen in other functions in python docstrings - Stack Overflow
How to document error cases?
Custom exceptions defined in same python script cause "reference target not found" warnings
Hello everyone, I'm new to Python, and it seems like there's no proper way of annotating which kinds of exceptions a function raises. Raising an error without making it part of the method signature might be fine for actually unexpected errors that should make the whole program terminate.
But what about kind of expected error? Like a file being unreadable or unable to parse. You can't just expect a programmer to know that code like this
def load_file(filename:string) -> MyFile:
file = open(filename)
return parse(file)might throw an IOException, a ParseException, or a SpecialParseException. How should they know? Should they read all the source code from all the functions called, and all the sources codes from all the functions they called to know which exceptions they might have to handle?
So I tried returning errors instead. So instead, parse() is now going to return an error, and therefore, the signature needs to look like this:
def load_file(filename:string) -> Union[MyFile, ParseError, SpecialParseError, IOError]:
try:
file = open(filename)
except IOError as e:
return e
return parse(file)I think that's much better, but on the Internet people say you should raise an exception wherever possible in Python. Also, this can get quite tedious, if you want to work with the result before returning, and just want to bubble errors up to the calling function:
def load_file(filename:string) -> Union[MyFile, ParseError, SpecialParseError, IOError]:
try:
file = open(filename)
except IOError as e:
return e
parsed = parse(file)
if isinstance(parsed, Exception):
return parsed
specialtreatment(parsed)
return parsedIs there a better way to do this? I thought about, maybe an annotation, like this:
@raises ParseError, SpecialParseError, IOError
def load_file(filename:string) -> MyFile:
file = open(filename)
parsed = parse(file)
specialtreatment(parsed)
return parsedIt depends what (or whom) you're writing the docstring for. For automatic conversion to API documentation, I like Google-style docstrings, which would look like:
def inv(a):
"""Return the inverse of the argument.
Arguments:
a (int): The number to invert.
Returns:
float: The inverse of the argument.
Raises:
TypeError: If 1 cannot be divided by the argument.
ZeroDivisionError: If the argument is zero.
"""
return 1 / a
Here I've included all of the exceptions that the function is likely to raise. Note that there's no need to explicitly raise ZeroDivisionError - that will happen automatically if you try to divide by zero.
However, if you aren't creating documentation from the docstring, I would probably just include the description line for such a simple function:
def inv(a):
"""Return the inverse of the argument."""
return 1 / a
Anyone using it is likely to know that you can't invert e.g. strings.
I don't want to check for types here, correct?
I wouldn't - if the user, after reading your documentation, decides to pass e.g. a string into the function they should expect to get the TypeError, and there's no point testing the argument type to then raise the same exception yourself that the code would have raised anyway (again, see also the ZeroDivisionError!) That is, unless e.g. float or complex numbers should be invalid input, in which case you will need to handle them manually.
No. The docstring should describe the input expected. If this were my function, I would include something like this in the docstring:
"""Return the inverse of an integer. ZeroDivisionError is raised if zero is
passed to this function."""
Therefore it is specified that the input should be an integer. Specifying that the function can raise a TypeError just overly complicates the docstring.