6.4 Exception Objects

Exceptions are instances of subclasses of the built-in Exception class. For backward compatibility, Python also lets you use strings, or instances of any class, as exception objects, but such usage risks future incompatibility and gives no benefits. An instance of any subclass of Exception has an attribute args, the tuple of arguments used to create the instance. args holds error-specific information, usable for diagnostic or recovery purposes.

6.4.1 The Hierarchy of Standard Exceptions

All exceptions that Python itself raises are instances of subclasses of Exception. The inheritance structure of exception classes is important, as it determines which except clauses handle which exceptions.

The SystemExit class inherits directly from Exception. Instances of SystemExit are normally raised by the exit function in module sys (covered in Chapter 8).

Other standard exceptions derive from StandardError, a direct subclass of Exception. Three subclasses of StandardError, like StandardError itself and Exception, are never instantiated directly. Their purpose is to make it easier for you to specify except clauses that handle a broad range of related errors. These subclasses are:

ArithmeticError

The base class for exceptions due to arithmetic errors (i.e., OverflowError, ZeroDivisionError, FloatingPointError)

LookupError

The base class for exceptions that a container raises when it receives an invalid key or index (i.e., IndexError, KeyError)

EnvironmentError

The base class for exceptions due to external causes (i.e., IOError, OSError, WindowsError)

6.4.2 Standard Exception Classes

Common runtime errors raise exceptions of the following classes:

AssertionError

An assert statement failed.

AttributeError

An attribute reference or assignment failed.

FloatingPointError

A floating-point operation failed. Derived from ArithmeticError.

IOError

An I/O operation failed (e.g., the disk is full, a file was not found, or needed permissions were missing). Derived from EnvironmentError.

ImportError

An import statement (covered in Chapter 7) cannot find the module to import or cannot find a name specifically requested from the module.

IndentationError

The parser encountered a syntax error due to incorrect indentation. Derived from SyntaxError.

IndexError

An integer used to index a sequence is out of range (using a non-integer as a sequence index raises TypeError). Derived from LookupError.

KeyError

A key used to index a mapping is not in the mapping. Derived from LookupError.

KeyboardInterrupt

The user pressed the interrupt key (Ctrl-C, Ctrl-Break, or Delete, depending on the platform).

MemoryError

An operation ran out of memory.

NameError

A variable was referenced, but its name is not bound.

NotImplementedError

Raised by abstract base classes to indicate that a concrete subclass must override a method.

OSError

Raised by functions in module os (covered in Chapter 10 and Chapter 14) to indicate platform-dependent errors. Derived from EnvironmentError.

OverflowError

The result of an operation on an integer is too large to fit into an integer (operator << does not raise this exception: rather, it drops excess bits). Derived from ArithmeticError. Python 2.1 only; in 2.2 and 2.3, too-large integer results implicitly become long integers, without raising exceptions.

SyntaxError

The parser encountered a syntax error.

SystemError

An internal error within Python itself or some extension module. You should report this to the authors and maintainers of Python, or of the extension in question, with all possible details to allow reproducing it.

TypeError

An operation or function was applied to an object of an inappropriate type.

UnboundLocalError

A reference was made to a local variable, but no value is currently bound to that local variable. Derived from NameError.

UnicodeError

An error occurred while converting Unicode to a string or vice versa.

ValueError

An operation or function was applied to an object that has a correct type but an inappropriate value, and nothing more specific (e.g., KeyError) applies.

WindowsError

Raised by functions in module os (covered in Chapter 10 and Chapter 14) to indicate Windows-specific errors. Derived from OsError.

ZeroDivisionError

A divisor (the right-hand operand of a /, //, or % operator or the second argument to built-in function divmod) is 0. Derived from ArithmeticError.



    Part III: Python Library and Extension Modules