Raising Your Own

Your own functions have rules too. A tip percentage cannot be negative. An amount cannot be empty. When a function receives something that breaks its rules, the worst response is to carry on and produce a wrong answer three steps later. raise lets a function refuse the input immediately, with a message that says what was wrong.

Think of a pharmacist handed a prescription with a dose that makes no sense. A clear "no, and here is why" at the counter is far better than the wrong medicine and a puzzled doctor next week.

raise

raise creates an exception and sends it on its way, exactly as Python does when one of its own instructions fails. You choose the type, usually ValueError for a bad value, and write the message in brackets. The function below refuses a percentage outside zero to a hundred.

def calculate_tip(bill, percent):
    """Return the tip for a bill at the given percentage."""
    if not 0 <= percent <= 100:
        raise ValueError(f"percent must be between 0 and 100, got {percent}")
    return bill * percent / 100


print(calculate_tip(40, 15))
print(calculate_tip(40, -5))

6.0
Traceback (most recent call last):
  File "/Users/you/python-course/tip_check.py", line 9, in <module>
    print(calculate_tip(40, -5))
          ~~~~~~~~~~~~~^^^^^^^^
  File "/Users/you/python-course/tip_check.py", line 4, in calculate_tip
    raise ValueError(f"percent must be between 0 and 100, got {percent}")
ValueError: percent must be between 0 and 100, got -5

A Good Message

The last line of that traceback is your own sentence, and it is worth writing well, because whoever reads it has only that sentence to go on. A good message says what was wrong and what was expected, and it includes the bad value: "percent must be between 0 and 100, got -5". Compare "invalid input", which tells the reader nothing they can act on.

Check at the Edge

You do not need checks in every function. The useful place is the edge: where data enters the program from outside, such as a person typing, a file being read, or a request arriving. Check it there, once, and the inside of the program can trust what it receives. Functions deep inside can then stay short and simple.

Raising and Catching Together

A function that raises and a caller that catches work as a pair. The function states its rule; the caller decides what to do when the rule is broken. Below, main tries each percentage, and when calculate_tip refuses one, main catches the ValueError and prints the function's own message.

def calculate_tip(bill, percent):
    """Return the tip for a bill at the given percentage."""
    if not 0 <= percent <= 100:
        raise ValueError(f"percent must be between 0 and 100, got {percent}")
    return bill * percent / 100


def main():
    for percent in [15, 250]:
        try:
            print(f"Tip: {calculate_tip(40, percent)}")
        except ValueError as error:
            print(f"Could not work out the tip: {error}")


main()

Tip: 6.0
Could not work out the tip: percent must be between 0 and 100, got 250

The words as error give the caught exception a name, and printing it prints its message. That is how the sentence written in calculate_tip reaches the person running main.