Should the docstring only contain the exceptions that are explicitly raised by a function?

Question

When writing doc strings in python, I am wondering if the docstring should contain the exceptions that are implicitly raised or if it should also contain the exceptions I explicitly raise.

Consider the function

def inv(a):
    if a == 0:
        raise ZeroDivisionError
    else:
        return 1/a

So in a docstring under the "Raises" keyword I would definetly put ZeroDivisionError. However, depending on the input I would also expect a TypeError. So would you put that also in the docstring?

Due to the EAFP principle (if i understand it correctly) I don't want to check for types here, correct? Any hint (also on the code sample) is welcome.

Swarthy

Answer 1

It 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.

Vetchling

Thanks for both the answers. I also see that your variant follows more closely the EAFP principle than mine does. Furthermore, the function name suggests that a matrix might be inserted. Hence, unless specifying that the function takes integer arguments (as amath suggests), the presence of the TypeError with its description highlights the purpose of the function better (in my opinion) – Swarthy

Answer 2

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.

Arguello