The exceptions module
This module provides the standard exception hierarchy. It’s automatically imported when Python starts, and the exceptions are added to the __builtin__ module. In other words, you usually don’t need to import this module.
This is a Python module in 1.5.2, and a built-in module in 2.0 and later.
The following standard exceptions are defined by this module:
Exception is used as a base class for all exceptions. It’s strongly recommended (but not yet required) that user exceptions are derived from this class too.
SystemExit(Exception) is raised by the sys.exit function. If it propagates to the top level without being caught by a try-except clause, the interpreter is terminated without a traceback message.
StandardError(Exception) is used as a base class for all standard exceptions (except SystemExit, that is).
KeyboardInterrupt(StandardError) is raised when the user presses Control-C (or any other interrupt key). Note that this may cause strange errors if you use “catch all” try-except statements.
ImportError(StandardError) is raised when Python fails to import a module.
EnvironmentError is used as a base class for exceptions that can be caused by the interpreter’s environment (that is, they’re usually not caused by bugs in the program).
IOError(EnvironmentError) is used to flag I/O-related errors.
OSError(EnvironmentError) is used to flag errors by the os module.
WindowsError(OSError) is used to flag Windows-specific errors from the os module.
NameError(StandardError) is raised when Python fails to find a global or local name.
UnboundLocalError(NameError) is raised if your program attempts to access a local variable before it has been assigned a value. This exception is only used in 2.0 and later; earlier versions raise a plain NameError exception instead.
AttributeError(StandardError) is raised when Python fails to find (or assign to) an instance attribute, a method, a module function, or any other qualified name.
SyntaxError(StandardError) is raised when the compiler stumbles upon a syntax error.
(2.0 and later) IndentationError(SyntaxError) is raised for syntax errors caused by bad indentation. This exception is only used in 2.0 and later; earlier versions raise a plain SyntaxError exception instead.
(2.0 and later) TabError(IndentationError) is raised by the interpreter when the -tt option is used to check for inconsistent indentation. This exception is only used in 2.0 and later; earlier versions raise a plain SyntaxError exception instead.
TypeError(StandardError) is raised when an operation cannot be applied to an object of the given type.
AssertionError(StandardError) is raised when an assert statement fails (if the expression is false, that is).
LookupError(StandardError) is used as a base class for exceptions raised when a sequence or dictionary type doesn’t contain a given index or key.
IndexError(LookupError) is raised by sequence objects when the given index doesn’t exist.
KeyError(LookupError) is raised by dictionary objects when the given key doesn’t exist.
ArithmeticError(StandardError) is used as a base class for math-related exceptions.
OverflowError(ArithmeticError) is raised when an operations overflows (for example, when an integer is too large to fit in the given type).
ZeroDivisionError(ArithmeticError) is raised when you try to divide a number by zero.
FloatingPointError(ArithmeticError) is raised when a floating point operation fails.
ValueError(StandardError) is raised if an argument has the right type, but an invalid value.
(2.0 and later) UnicodeError(ValueError) is raised for type problems related to the Unicode string type. This is only used in 2.0 and later.
RuntimeError(StandardError) is used for various run-time problems, including attempts to get outside the box when running in restricted mode, unexpected hardware problems, etc.
NotImplementedError(RuntimeError) can be used to flag functions that hasn’t been implemented yet, or methods that should be overridden.
SystemError(StandardError) is raised if the interpreter messes up, and knows about it. The exception value contains a more detailed description (usually something cryptic, like “eval_code2: NULL globals” or so). I cannot recall ever seeing this exception in over five years of full-time Python programming, but maybe that’s just me.
MemoryError(StandardError) is raised when the interpreter runs out of memory. Note that this only happens when the underlying memory allocation routines complain; you can often send your poor computer into a mindless swapping frenzy before that happens.
You can create your own exception classes. Just inherit from the built-in Exception class (or a proper standard exception), and override the constructor and/or __str__ method as necessary.
# File: exceptions-example-1.py # python imports this module by itself, so the following # line isn't really needed # import exceptions class HTTPError(Exception): # indicates an HTTP protocol error def __init__(self, url, errcode, errmsg): self.url = url self.errcode = errcode self.errmsg = errmsg def __str__(self): return ( "<HTTPError for %s: %s %s>" % (self.url, self.errcode, self.errmsg) ) try: raise HTTPError("http://www.python.org/foo", 200, "Not Found") except HTTPError, error: print "url", "=>", error.url print "errcode", "=>", error.errcode print "errmsg", "=>", error.errmsg raise # reraise exception
$ python exceptions-example-1.py url => http://www.python.org/foo errcode => 200 errmsg => Not Found Traceback (innermost last): File "exceptions-example-1", line 16, in ? HTTPError: <HTTPError for http://www.python.org/foo: 200 Not Found>