As mentioned earlier, string-based exceptions still work, but they generate warnings as of Python 2.5, and are scheduled to go away completely in Python 3.0, if not earlier. In fact, here is the real output of the preceding code when run in IDLE under Python 2.5:

>>> myexc = 'My exception string'
>>> try:
        raise myexc
    except myexc:
        print 'caught'

Warning (from warnings module):
  File "_  _main_  _", line 2
DeprecationWarning: raising a string exception is deprecated
caught

You can disable such warnings, but they are generated to let you know that string exceptions will become errors in the future, and thus will be completely disallowed. This book’s coverage of string exceptions is retained just to help you understand code written in the past; today, all built-in exceptions are class instances, and all user-defined exceptions you create should be class-based as well. The next section explains why.

Let’s look at an example to see how class exceptions work in code. In the following file, classexc.py, we define a superclass called General and two subclasses called Specific1 and Specific2. This example illustrates the notion of exception categories—General is a category name, and its two subclasses are specific types of exceptions within the category. Handlers that catch General will also catch any subclasses of it, including Specific1 and Specific2:

class General:            pass
class Specific1(General): pass
class Specific2(General): pass

def raiser0(  ):
    X = General(  )          # Raise superclass instance
    raise X

def raiser1(  ):
    X = Specific1(  )        # Raise subclass instance
    raise X

def raiser2(  ):
    X = Specific2(  )        # Raise different subclass instance
    raise X

for func in (raiser0, raiser1, raiser2):
    try:
        func(  )
    except General:        # Match General or any subclass of it
        import sys
        print 'caught:', sys.exc_info(  )[0]

C:python> python classexc.py
caught: _  _main_  _.General
caught: _  _main_  _.Specific1
caught: _  _main_  _.Specific2

We’ll revisit the sys.exc_info call used here in the next chapter—it’s how we can grab hold of the most recently raised exception in a generic fashion. Briefly, for class-based exceptions, the first item in its result is the class of the exception raised, and the second is the actual instance raised. Apart from this method, there is no other way to determine exactly what happened in an empty except clause like this one that catches everything.

Notice that we call classes to make instances in the raise statements here; as we’ll see when we formalize raise statement forms later in this section, an instance is always present when raising a class-based exception. This code also includes functions that raise instances of all three of our classes as exceptions, as well as a top-level try that calls the functions, and catches General exceptions (the same try also catches the two specific exceptions, because they are subclasses of General).

One more note: the current Python documentation states that it is preferred (though not required) that user-defined exception classes inherit from the built-in exception named Exception. To do this, we would rewrite the first line of our classexc.py file as follows:

class General(Exception): pass
class Specific1(General): pass
class Specific2(General): pass

Although this isn’t required, and standalone exception classes work fine today, preferred things have a way of becoming requirements in Python over time. If you want to future-proof your code, inherit from Exception in your root superclass, as shown here. Doing so also provides your class with some useful interfaces and tools for free, by inheritance—for example, the Exception class comes with _ _init_ _ constructor logic, which automatically attaches constructor arguments to class instances.

Because there are only three possible exceptions in the prior section’s example, it doesn’t really do justice to the utility of class exceptions. In fact, we could achieve the same effects by coding a list of string exception names in parentheses within the except clause. The file stringexc.py shows how:

General   = 'general'
Specific1 = 'specific1'
Specific2 = 'specific2'

def raiser0(  ): raise General
def raiser1(  ): raise Specific1
def raiser2(  ): raise Specific2

for func in (raiser0, raiser1, raiser2):
    try:
        func(  )
    except (General, Specific1, Specific2):     # Catch any of these
        import sys
        print 'caught:', sys.exc_info(  )[0]

C:python> python stringexc.py
caught: general
caught: specific1
caught: specific2

For large or high exception hierarchies, however, it may be easier to catch categories using classes than to list every member of a category in a single except clause. Moreover, you can extend exception hierarchies by adding new subclasses without breaking existing code.

Suppose you code a numeric programming library in Python, to be used by a large number of people. While you are writing your library, you identify two things that can go wrong with numbers in your code—division by zero, and numeric overflow. You document these as the two exceptions that your library may raise, and define them as simple strings in your code:

# mathlib.py

divzero = 'Division by zero error in library'
oflow   = 'Numeric overflow error in library'
...
def func(  ):
    ...
    raise divzero

Now, when people use your library, they will typically wrap calls to your functions or classes in try statements that catch your two exceptions (if they do not catch your exceptions, exceptions from the library kill their code):

# client.py

import mathlib
...
try:
    mathlib.func(...)
except (mathlib.divzero, mathlib.oflow):
    ...report and recover...

This works fine, and lots of people start using your library. Six months down the road, though, you revise it. Along the way, you identify a new thing that can go wrong—underflow—and add that as a new string exception:

# mathlib.py

divzero = 'Division by zero error in library'
oflow   = 'Numeric overflow error in library'
uflow   = 'Numeric underflow error in library'

Unfortunately, when you rerelease your code, you create a maintenance problem for your users. If they’ve listed your exceptions explicitly, they now have to go back and change every place they call your library to include the newly added exception name:

# client.py

try:
    mathlib.func(...)
except (mathlib.divzero, mathlib.oflow, mathlib.uflow):
    ...report and recover...

This may not be the end of the world. If your library is used only in-house, you can make the changes yourself. You might also ship a Python script that tries to fix such code automatically (it would probably be only a few dozen lines, and it would guess right at least some of the time). If many people have to change their code each time you alter your exception set, though, this is not exactly the most polite of upgrade policies.

Your users might try to avoid this pitfall by coding empty except clauses to catch all possible exceptions:

# client.py

try:
    mathlib.func(...)
except:                           # Catch everything here...report and recover...

But this workaround might catch more than they bargained for—even things like variable name typos, memory errors, and system exits trigger exceptions, and you want such things to pass, not be caught and erroneously classified as library errors. As a rule of thumb, it’s usually better to be specific than general in exception handlers (an idea we’ll revisit in the gotchas section in the next chapter).^[78]

So what to do, then? Class exceptions fix this dilemma completely. Rather than defining your library’s exceptions as a simple set of strings, arrange them into a class tree with a common superclass to encompass the entire category:

# mathlib.py

class NumErr(Exception): pass
class Divzero(NumErr): pass
class Oflow(NumErr): pass
...
def func(  ):
    ...
    raise DivZero(  )

This way, users of your library simply need to list the common superclass (i.e., category) to catch all of your library’s exceptions, both now and in the future:

# client.py

import mathlib
...
try:
    mathlib.func(...)
except mathlib.NumErr:
    ...report and recover...

When you go back and hack your code again, new exceptions are added as new subclasses of the common superclass:

# mathlib.py

...
class Uflow(NumErr): pass

The end result is that user code that catches your library’s exceptions will keep working, unchanged. In fact, you are free to add, delete, and change exceptions arbitrarily in the future—as long as clients name the superclass, they are insulated from changes in your exceptions set. In other words, class exceptions provide a better answer to maintenance issues than strings do. Moreover, class-based exceptions can support state retention and inheritance in ways that strings cannot—concepts we’ll explore by example later in this chapter.

I didn’t really pull the prior section’s examples out of thin air. Although user-defined exceptions may be identified by string or class objects, all built-in exceptions that Python itself may raise are predefined class objects instead of strings. Moreover, they are organized into a shallow hierarchy with general superclass categories and specific subclass types, much like the exceptions class tree we developed earlier.

All the familiar exceptions you’ve seen (e.g., SyntaxError) are really just predefined classes, available both as built-in names (in the module _ _builtin_ _), and as attributes of the standard library module exceptions. In addition, Python organizes the built-in exceptions into a hierarchy, to support a variety of catching modes. For example:

And so on—you can read further about this structure in either the Python library manual, or the help text of the exceptions module (see Chapter 4 and Chapter 14 for help on help):

>>> import exceptions
>>> help(exceptions)...lots of text omitted...

The built-in class tree allows you to choose how specific or general your handlers will be. For example, the built-in exception ArithmeticError is a superclass for more specific exceptions such as OverflowError and ZeroDivisionError. By listing ArithmeticError in a try, you will catch any kind of numeric error raised; by listing just OverflowError, you will intercept just that specific type of error, and no others.

Similarly, because StandardError is the superclass of all built-in error exceptions, you can generally use it to select between built-in errors and user-defined exceptions in a try:

try:
    action(  )
except StandardError:
    ...handle Python errors...
except:
    ...handle user exceptions...
else:
    ...handle no-exception case...

You can also almost simulate an empty except clause (that catches everything) by catching the root class Exception. This doesn’t quite work, however, because it won’t catch string exceptions, and standalone user-defined exceptions are not currently required to be subclasses of the Exception root class.

Whether or not you will use categories in the built-in class tree, it serves as a good example; by using similar techniques for class exceptions in your own code, you can provide exception sets that are flexible and easily modified.

Other than in the respects that we have covered here, built-in exceptions are largely indistinguishable from the original string-based model. In fact, you normally don’t need to care that they are classes unless you assume built-in exceptions are strings and try to concatenate without converting (e.g., KeyError + "spam" fails, but str(KeyError) + "spam" works).

When we met string-based exceptions at the start of this chapter, we saw that the text of the string shows up in the standard error message when the exception is not caught (i.e., when it’s propagated up to the top-level default exception handler). But what does this message contain for an uncaught class exception? By default, you get the class’ name, and a not very pretty display of the instance object that was raised:

>>> class MyBad: pass
>>> raise MyBad(  )

Traceback (most recent call last):
  File "<pyshell#13>", line 1, in <module>
    raise MyBad(  )
MyBad: <_  _main_  _.MyBad instance at 0x00BB5468>

To improve this display, define either the _ _repr_ _ or _ _str_ _ string-representation overloading method in your class to return the string you want to display for your exception if it reaches the default handler:

>>> class MyBad:
...     def _ _repr_ _(self):
...         return "Sorry--my mistake!"
...
>>> raise MyBad(  )

Traceback (most recent call last):
  File "<pyshell#28>", line 1, in <module>
    raise MyBad(  )
MyBad: Sorry--my mistake!

As we learned earlier, the _ _repr_ _ operator overloading method used here is called for printing and for string conversion requests made to your class’ instances; _ _str_ _ defines the user-friendly display preferred by print statements. (See "Operator Overloading" in Chapter 24 for more on display-string methods.)

Note that if we inherit from built-in exception classes, as recommended earlier, the error test is modified slightly—constructor arguments are automatically saved and displayed in the message:

>>> class MyBad(Exception): pass
>>> raise MyBad(  )

Traceback (most recent call last):
  File "<pyshell#18>", line 1, in <module>
    raise MyBad(  )
MyBad

>>> class MyBad(Exception): pass
>>> raise MyBad('the', 'bright', 'side', 'of', 'life')

Traceback (most recent call last):
  File "<pyshell#22>", line 1, in <module>
    raise MyBad('the', 'bright', 'side', 'of', 'life')
MyBad: ('the', 'bright', 'side', 'of', 'life')

If your end users might see exception error messages, you will probably want to define your own custom display format methods with operator overloading, as shown here. Being able to automatically attach state information to instances like this, though, is a generally useful feature, as the next section explores.

Besides supporting flexible hierarchies, class exceptions also provide storage for extra state information as instance attributes. When a class-based exception is raised, Python automatically passes the class instance object along with the exception as the extra data item. As for string exceptions, you can access the raised instance by listing an extra variable back in the try statement. This provides a natural hook for supplying data and behavior to the handler.

>>> class FormatError:
...     def _ _init_ _(self, line, file):
...         self.line = line
...         self.file = file
...
>>> def parser(  ):
...     # when error found
...     raise FormatError(42, file='spam.txt')
...
>>> try:
...     parser(  )
... except FormatError, X:
...     print 'Error at', X.file, X.line
...
Error at spam.txt 42

>>> formatError = 'formatError'

>>> def parser(  ):
...     # when error found
...     raise formatError, {'line':42, 'file':'spam.txt'}
...
>>> try:
...     parser(  )
... except formatError, X:
...     print 'Error at', X['file'], X['line']
...
Error at spam.txt 42

class FormatError:
    def _ _init_ _(self, line, file):
        self.line = line
        self.file = file
    def logerror(self):
        log = open('formaterror.txt', 'a')
        print >> log, 'Error at', self.file, self.line

def parser(  ):
    raise FormatError(40, 'spam.txt')

try:
    parser(  )
except FormatError, exc:
    exc.logerror(  )

formatError = "formatError"

def logerror(line, file):
    log = open('formaterror.txt', 'a')
    print >> log, 'Error at', file, line

def parser(  ):
    raise formatError, (41, 'spam.txt', logerror)

try:
    parser(  )
except formatError, data:
    data[2](data[0], data[1])        # Or simply: logerror(  )