We're back after a server migration that caused effbot.org to fall over a bit harder than expected. Expect some glitches.

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.

Example: Using the exceptions module
# 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>