Raising your own errors

A quiet wrong answer

Here's grade_for from lesson 5.8. A score must be 0 to 100. Predict what it does with 150:

def grade_for(score):
    if score >= 85:
        return "A"
    elif score >= 70:
        return "B"
    elif score >= 50:
        return "C"
    else:
        return "F"

print(grade_for(150))

A

Python only knows what you tell it; it has no idea a score stops at 100. A typo like 150 for 50 gets an A, the A goes on a report, and nobody notices. A wrong answer that looks right is worse than an error, because an error at least stops the program where the problem is.

raise

To raiseraiseSignal an error yourself: raise ValueError('message') stops the function and sends the error to its caller. an error, write raise, then the error type with a message in parentheses. It stops the function on the spot, like return, but sends an error to the caller instead of a value. This shorter grade function uses pass and fail:

def grade_for(score):
    if score < 0 or score > 100:
        raise ValueError("score must be 0-100")
    if score >= 50:
        return "pass"
    return "fail"

print(grade_for(150))

The traceback ends with ValueError: score must be 0-100, and the line above it is the raise line. ValueError is the usual type for "right type, wrong value". In lesson 5.8, grade_for only calculated and main() decided what to print; errors split the work the same way. The function raises; the caller decides what to do about it. except ValueError as e gives the error a name, e, and printing e shows its message:

def grade_for(score):
    if score < 0 or score > 100:
        raise ValueError("score must be 0-100")
    if score >= 50:
        return "pass"
    return "fail"

for score in [72, 150]:
    try:
        print(score, grade_for(score))
    except ValueError as e:
        print("Can't grade", score, "-", e)

Add -5 to the list and run it: it's caught the same way.

The message must be inside the error, not the error itself:

finally (lesson 7.2) runs even when the function is leaving with return. Predict:

def check():
    try:
        return "try"
    finally:
        print("finally runs")

print(check())

finally runs
try

If you picked try alone, you pictured return skipping finally. It never does.

Your own kind of error

A payment app needs an error that means exactly "not enough money". You can make one with two short lines:

class NotEnoughBalance(Exception):
    pass

def pay(balance, amount):
    if amount > balance:
        raise NotEnoughBalance(f"balance is {balance} birr")
    return balance - amount

try:
    balance = pay(50, 120)
except NotEnoughBalance as e:
    print("Payment failed:", e)

Read the first two lines as a recipe: "a new kind of error, called NotEnoughBalance, based on Exception". That's a custom exceptioncustom exceptionAn error type you make yourself, with class Name(Exception): pass, so callers can catch exactly that problem.. class makes a new type; pass (lesson 2.6) says it needs nothing added. How classes work is a whole module later (Module 10), so for now this is a recipe to copy: change the name, keep the rest. It behaves like any error: you raise it with a message, and except NotEnoughBalance catches this problem and no other.

Error types come in families. ZeroDivisionError is a kind of ArithmeticError, which is a kind of Exception, and except catches the type it names and every kind of it:

try:
    print(10 / 0)
except ArithmeticError:
    print("A maths problem")

NotEnoughBalance is a kind of Exception too; that's what the (Exception) says.

When should a function raise, and when should it return None, like to_int in lesson 7.2? Raise when the call is wrong: a correct program never asks for it, like a score of 150. Return None when "no answer" is a normal result the caller expects, like text that isn't a number or a name that isn't in the list.