Defining docstring raises for functions not explicitly raising exception

Question

import requests

def example():
    """An example function

    :raises KeyError: ?
    :raises HttpError: ?
    """
    result: Dict = do_something()
    log(result["key"])
    response = requests.get(url)
    return response

The above function is not explicitly raising any exception, but as can be seen, its execution can potentially raise KeyError and HTTPError. Is it fine to mention these in docstring? What does the best practice say?

Asked By: Gaurav Pathak

||

Source

Answer 1

If the exceptions are relavant for somebody using the functions the should be documented (and also that they are indirect)

Answered By: user18074821

Answer 2

This is too long for a comment, but it is not a full answer either, because it is based on what I have noticed and because there are no strict rules, e.g. the item 3 below is an exception from item 2.

Don’t care about exceptions resulting from incorrect usage or problems with a computer that prevent normal program operation like disk full.
If some exceptions can happen when the functions is used correctly (it should be documented what that means), they are part of the interface and should be documented.
Networking is full of timeouts, outages, refused connections etc. Such error is always a possible outcome when network I/O is involved. This is probably considered a well known fact and it is usually not mentioned in docstrings.
For example the requests.get` appearing in the OP’s code does not mention exceptions it may raise (link:
https://requests.readthedocs.io/en/latest/api/#requests.get
). It says you’ll get a response. But what you get if there is no valid response? An exception, of course.

Answered By: VPfB

Defining docstring raises for functions not explicitly raising exception

Question:

Answers: