The raise Statement

To raise an exception, you use the raise statement with an argument that is either a class (which should subclass Exception) or an instance. When using a class, an instance is created automatically Here is an example, using the built-in exception class Exception:

>>> raise Exception
Traceback (most recent call last):
   File "<stdin>", line 1, in ?
Exception
>>> raise Exception('hyperdrive overload')
Traceback (most recent call last):
   File "<stdin>", line 1, in ?
Exception: hyperdrive overload

The first example, raise Exception, raises a generic exception with no information about what went wrong. In the previous example, I added the error message hyperdrive overload.

Many built-in classes are available. Table 8-1 describes some of the most important ones. You can find a description of all of them in the Python Library Reference, in the section “Built-in Exceptions.” All of these exception classes can be used in your raise statements.

>>> raise ArithmeticError
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
ArithmeticError

Custom Exception Classes

Although the built-in exceptions cover a lot of ground and are sufficient for many purposes, there are times when you might want to create your own. For example, in the hyperdrive overload example, wouldn’t it be more natural to have a specific HyperdriveError class representing error conditions in the hyperdrive? It might seem that the error message is sufficient, but as you will see in the next section (“Catching Exceptions”), you can selectively handle certain types of exceptions based on their class. Thus, if you wanted to handle hyperdrive errors with special error-handling code, you would need a separate class for the exceptions.

So, how do you create exception classes? Just like any other class—but be sure to subclass Exception (either directly or indirectly, which means that subclassing any other built-in exception is okay). Thus, writing a custom exception basically amounts to something like this:

class SomeCustomException(Exception): pass

It’s really not much work, is it? (If you want, you can certainly add methods to your exception class as well.)

Look, Ma, No Arguments!

If you have caught an exception but you want to raise it again (pass it on, so to speak), you can call raise without any arguments . (You can also supply the exception explicitly if you catch it, as explained in the section “Catching the Object” later in this chapter.)

As an example of how this might be useful, consider a calculator class that has the capability to “muffle” ZeroDivisionErrorexceptions. If this behavior is turned on, the calculator prints out an error message instead of letting the exception propagate. This is useful if the calculator is used in an interactive session with a user, but if it is used internally in a program, raising an exception would be better. Therefore, the muffling can be turned off. Here is the code for such a class:

class MuffledCalculator:
    muffled = False
    def calc(self, expr):
        try:
            return eval(expr)
        except ZeroDivisionError:
            if self.muffled:
                print('Division by zero is illegal')
            else:
                raise

The following is an example of how this class may be used, both with and without muffling:

>>> calculator = MuffledCalculator()
>>> calculator.calc('10 / 2')
5.0
>>> calculator.calc('10 / 0') # No muffling
Traceback (most recent call last): File "<stdin>", line 1, in ?
  File "MuffledCalculator.py", line 6, in calc
     return eval(expr)
  File "<string>", line 0, in ?
ZeroDivisionError: integer division or modulo by zero
>>> calculator.muffled = True
>>> calculator.calc('10 / 0')
Division by zero is illegal

As you can see, when the calculator is not muffled, the ZeroDivisionError is caught but passed on.

Using raise with no arguments is often a good choice in an except clause, if you’re unable to handle the exception. Sometimes you may want to raise a different exception, though. In that case, the exception that took you into the except cause will be stored as the context for your exception and will be part of the final error message, for example:

>>> try:
...     1/0
... except ZeroDivisionError:
...     raise ValueError
...
Traceback (most recent call last):
  File "<stdin>", line 2, in <module>
ZeroDivisionError: division by zero

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "<stdin>", line 4, in <module>
ValueError

You can supply your own context exception by using the raise ... from ... version of the statement or use None to suppress the context.

>>> try:
...     1/0
... except ZeroDivisionError:
...     raise ValueError from None
...
Traceback (most recent call last):
  File "<stdin>", line 4, in <module>
ValueError

More Than One except Clause

If you run the program from the previous section again and enter a nonnumeric value at the prompt, another exception occurs.

Enter the first number: 10
Enter the second number: "Hello, world!"
Traceback (most recent call last):
  File "exceptions.py", line 4, in ?
     print(x / y)
TypeError: unsupported operand type(s) for /: 'int' and 'str'

Because the except clause looked for only ZeroDivisionErrorexceptions, this one slipped through and halted the program. To catch this exception as well, you can simply add another except clause to the same try/except statement.

try:
   x = int(input('Enter the first number: '))
   y = int(input('Enter the second number: '))
   print(x / y)
except ZeroDivisionError:
   print("The second number can't be zero!")
except TypeError:
   print("That wasn't a number, was it?")

This time using an if statement would be more difficult. How do you check whether a value can be used in division? There are a number of ways, but by far the best way is, in fact, to simply divide the values to see if it works.

Also notice how the exception handling doesn’t clutter the original code. Adding a lot of if statements to check for possible error conditions could easily have made the code quite unreadable.

Catching Two Exceptions with One Block

If you want to catch more than one exception type with one block, you can specify them all in a tuple, as follows:

try:
   x = int(input('Enter the first number: '))
   y = int(input('Enter the second number: '))
   print(x / y)
except (ZeroDivisionError, TypeError, NameError):
   print('Your numbers were bogus ...')

In the preceding code, if the user enters either a string or something other than a number or if the second number is zero, the same error message is printed. Simply printing an error message isn’t very helpful, of course. An alternative could be to keep asking for numbers until the division works. I show you how to do that in the section “When All Is Well” later in this chapter.

Note that the parentheses around the exceptions in the except clause are important. A common error is to omit these parentheses, in which case you may end up with something other than what you want. For an explanation, see the next section, “Catching the Object.”

Catching the Object

If you want access to the exception object itself in an except clause , you can use two arguments instead of one. (Note that even when you are catching multiple exceptions, you are supplying except with only one argument—a tuple.) This can be useful (for example) if you want your program to keep running but you want to log the error somehow (perhaps just printing it out to the user). The following is a sample program that prints out the exception (if it occurs) but keeps running:

try:
    x = int(input('Enter the first number: '))
    y = int(input('Enter the second number: '))
    print(x / y)
except (ZeroDivisionError, TypeError) as e:
    print(e)

The except clause in this little program again catches two types of exceptions, but because you also explicitly catch the object itself, you can print it out so the user can see what happened. (You see a more useful application of this later in this chapter, in the section “When All Is Well.”)

A Real Catchall

Even if the program handles several types of exceptions, some may still slip through. For example, using the same division program, simply try to press Enter at the prompt, without writing anything. You should get an error message and some information about what went wrong (a stack trace), somewhat like this:

Traceback (most recent call last):
  ...
ValueError: invalid literal for int() with base 10: ''

This exception got through the try/except statement —and rightly so. You hadn’t foreseen that this could happen and weren’t prepared for it. In these cases, it is better that the program crash immediately (so you can see what’s wrong) than that it simply hide the exception with a try/except statement that isn’t meant to catch it.

However, if you do want to catch all exceptions in a piece of code, you can simply omit the exception class from the except clause.

try:
    x = int(input('Enter the first number: '))
    y = int(input('Enter the second number: '))
    print(x / y)
except:
    print('Something wrong happened ...')

Now you can do practically whatever you want.

Enter the first number: "This" is *completely* illegal 123
Something wrong happened ...

Catching all exceptions like this is risky business because it will hide errors you haven’t thought of as well as those you’re prepared for. It will also trap attempts by the user to terminate execution by Ctrl-C, attempts by functions you call to terminate by sys.exit, and so on. In most cases, it would be better to use except Exception as e and perhaps do some checking on the exception object, e. This will then permit those very few exceptions that don’t subclass Exception to slip through. This includes SystemExit and KeyboardInterrupt, which subclass BaseException, the superclass of Exception itself.

When All Is Well

In some cases, it can be useful to have a block of code that is executed unless something bad happens; as with conditionals and loops, you can add an else clause to the try/except statement.

try:
   print('A simple task')
except:
   print('What? Something went wrong?')
else:
   print('Ah ... It went as planned.')

If you run this, you get the following output:

A simple task
Ah ... It went as planned.

With this else clause, you can implement the loop hinted at in the section “Catching Two Exceptions with One Block” earlier in this chapter.

while True:
    try:
        x = int(input('Enter the first number: '))
        y = int(input('Enter the second number: '))
        value = x / y
        print('x / y is', value)
    except:
        print('Invalid input. Please try again.')
    else:
        break

Here, the loop is broken (by the break statement in the else clause) only when no exception is raised. In other words, as long as something wrong happens, the program keeps asking for new input. The following is an example run:

Enter the first number: 1
Enter the second number: 0
Invalid input. Please try again.
Enter the first number: 'foo'
Enter the second number: 'bar'
Invalid input. Please try again.
Enter the first number: baz
Invalid input. Please try again.
Enter the first number: 10
Enter the second number: 2
x / y is 5

As mentioned previously, a preferable alternative to using an empty except clause is to catch all exceptions of the Exception class (which will catch all exceptions of any subclass as well). You cannot be 100 percent certain that you’ll catch everything then, because the code in your try/except statement may be naughty and use the old-fashioned string exceptions or perhaps create a custom exception that doesn’t subclass Exception. However, if you go with the except Exception version, you can use the technique from the section “Catching the Object” earlier in this chapter to print out a more instructive error message in your little division program.

while True:
    try:
        x = int(input('Enter the first number: '))
        y = int(input('Enter the second number: '))
        value = x / y
        print('x / y is', value)
    except Exception as e:
        print('Invalid input:', e)
        print('Please try again')
    else:
        break

The following is a sample run:

Enter the first number: 1
Enter the second number: 0
Invalid input: integer division or modulo by zero
Please try again
Enter the first number: 'x' Enter the second number: 'y'
Invalid input: unsupported operand type(s) for /: 'str' and 'str'
Please try again
Enter the first number: quuux
Invalid input: name 'quuux' is not defined
Please try again
Enter the first number: 10
Enter the second number: 2
x / y is 5

And Finally . . .

Finally, there is the finally clause . You use it to do housekeeping after a possible exception. It is combined with a try clause.

x = None
try:
    x = 1 / 0
finally:
    print('Cleaning up ...')
    del x

In the preceding example, you are guaranteed that the finally clause will be executed, no matter what exceptions occur in the try clause. The reason for initializing x before the try clause is that otherwise it would never be assigned a value because of the ZeroDivisionError. This would lead to an exception when using del on it within the finally clause, which you wouldn’t catch.

If you run this, the cleanup comes before the program crashes and burns.

Cleaning up ...
Traceback (most recent call last):
  File "C:pythondiv.py", line 4, in ?
     x = 1 / 0
ZeroDivisionError: integer division or modulo by zero

While using del to remove a variable is a rather silly kind of cleanup, the finally clause may be quite useful for closing files or network sockets and the like. (You learn more about those in Chapter 14.)

You can also combine try, except, finally, and else (or just three of them) in a single statement.

try:
    1 / 0
except NameError:
    print("Unknown variable")
else:
    print("That went well!")
finally:
    print("Cleaning up.")

New Functions in This Chapter

What Now?

While you might think that the material in this chapter was exceptional (pardon the pun), the next chapter is truly magical. Well, almost magical.