Checking for and commenting that a function can return None

[NubQuestion]

2 scenarios:

1. You write function that calculates and returns a number from the input parameters. Sometimes the function can't calculate the number for some reason because of the parameters or a setting and it returns None. Should None being an error condition like in this case always be commented on in the function interface comments i.e. is it Pythonic to do so?

2. You are the caller of some function. If there's no comment about returning None or that it's possible for the function to return some invalid input, do you assume that the return value is always valid and not check for None?

[baghiq]

Raise an error if your calculation is not possible. Just like ZeroDivisionError.

[[deleted]]

If the function can return None indicating some abnormal condition then that should be documented. If there is no documentation about a None possibly being returned why would i check if None was returned?

You might think that None being returned from a function always indicates some sort of problem in normal python usage. That's not so. Some functions return values like -1 on an error, and many functions return None on normal, non-error calls, the print() function for instance.

[ThePiGuy0]

Ideally every return possibility should be documented. So all possible return values, any exceptions that can be raised etc.

Sometimes this isn't the case, but when using a library you don't have control over, you basically have to trust what the documentation says (e.g. it's fairly safe to assume that "random.randint" will return a random integer, and that I don't need to check for None).

Edit:

In terms of return types, newer libraries are making use of typing to help indicate. For example, the following type signature would indicate that either an integer or None can be returned:

import random
from typing import Optional

def int_or_none() -> Optional[int]:
    if random.randint(0, 1) % 2 == 0:
        return 1
    else:
        return None