1. Larry Hastings
  2. python-clinic


python-clinic / Doc / library / exceptions.rst

Built-in Exceptions

In Python, all exceptions must be instances of a class that derives from :class:`BaseException`. In a :keyword:`try` statement with an :keyword:`except` clause that mentions a particular class, that clause also handles any exception classes derived from that class (but not exception classes from which it is derived). Two exception classes that are not related via subclassing are never equivalent, even if they have the same name.

The built-in exceptions listed below can be generated by the interpreter or built-in functions. Except where mentioned, they have an "associated value" indicating the detailed cause of the error. This may be a string or a tuple of several items of information (e.g., an error code and a string explaining the code). The associated value is usually passed as arguments to the exception class's constructor.

User code can raise built-in exceptions. This can be used to test an exception handler or to report an error condition "just like" the situation in which the interpreter raises the same exception; but beware that there is nothing to prevent user code from raising an inappropriate error.

The built-in exception classes can be sub-classed to define new exceptions; programmers are encouraged to at least derive new exceptions from the :exc:`Exception` class and not :exc:`BaseException`. More information on defining exceptions is available in the Python Tutorial under :ref:`tut-userexceptions`.

When raising (or re-raising) an exception in an :keyword:`except` clause :attr:`__context__` is automatically set to the last exception caught; if the new exception is not handled the traceback that is eventually displayed will include the originating exception(s) and the final exception.

When raising a new exception (rather than using a bare raise to re-raise the exception currently being handled), the implicit exception context can be supplemented with an explicit cause by using :keyword:`from` with :keyword:`raise`:

raise new_exc from original_exc

The expression following :keyword:`from` must be an exception or None. It will be set as :attr:`__cause__` on the raised exception. Setting :attr:`__cause__` also implicitly sets the :attr:`__suppress_context__` attribute to True, so that using raise new_exc from None effectively replaces the old exception with the new one for display purposes (e.g. converting :exc:`KeyError` to :exc:`AttributeError`, while leaving the old exception available in :attr:`__context__` for introspection when debugging.

The default traceback display code shows these chained exceptions in addition to the traceback for the exception itself. An explicitly chained exception in :attr:`__cause__` is always shown when present. An implicitly chained exception in :attr:`__context__` is shown only if :attr:`__cause__` is :const:`None` and :attr:`__suppress_context__` is false.

In either case, the exception itself is always shown after any chained exceptions so that the final line of the traceback always shows the last exception that was raised.

Base classes

The following exceptions are used mostly as base classes for other exceptions.

Concrete exceptions

The following exceptions are the exceptions that are usually raised.

The following exceptions are kept for compatibility with previous versions; starting from Python 3.3, they are aliases of :exc:`OSError`.

OS exceptions

The following exceptions are subclasses of :exc:`OSError`, they get raised depending on the system error code.


The following exceptions are used as warning categories; see the :mod:`warnings` module for more information.

Exception hierarchy

The class hierarchy for built-in exceptions is: