Core Python Programming (2nd Edition)

10.6. Raising Exceptions
The interpreter was responsible for raising all of the exceptions we have seen so far. These exist as a
result of encountering an error during execution. A programmer writing an API may also wish to throw
an exception on erroneous input, for example, so Python provides a mechanism for the programmer to
explicitly generate an exception: the raise statement.
10.6.1. raise Statement
Syntax and Common Usage
The raise statement is quite flexible with the arguments it supports, translating to a large number of
different formats supported syntactically. The general syntax for raise is:
raise [SomeException [, args [, traceback]]]
The first argument, SomeException, is the name of the exception to raise. If present, it must either be a
string, class, or instance (more below). SomeException must be given if any of the other arguments (args
or traceback) are present. A list of all Python standard exceptions is given in Table 10.2.
The second expression contains optional args (aka parameters, values) for the exception. This value is
either a single object or a tuple of objects. When exceptions are detected, the exception arguments are
always returned as a tuple. If args is a tuple, then that tuple represents the same set of exception
arguments that are given to the handler. If args is a single object, then the tuple will consist solely of
this one object (i.e., a tuple with one element). In most cases, the single argument consists of a string
indicating the cause of the error. When a tuple is given, it usually equates to an error string, an error
number, and perhaps an error location, such as a file, etc.
The final argument, TRaceback, is also optional (and rarely used in practice), and, if present, is the
traceback object used for the exceptionnormally a traceback object is newly created when an exception
is raised. This third argument is useful if you want to reraise an exception (perhaps to point to the
previous location from the current). Arguments that are absent are represented by the value None.
The most common syntax used is when SomeException is a class. No additional parameters are ever
required, but in this case, if they are given, they can be a single object argument, a tuple of arguments,
or an exception class instance. If the argument is an instance, then it can be an instance of the given
class or a derived class (subclassed from a pre-existing exception class). No additional arguments (i.e.,
exception arguments) are permitted if the argument is an instance.
More Exotic/Less Common Usage
What happens if the argument is an instance? No problems arise if instance is an instance of the given
exception class. However, if instance is not an instance of the class or an instance of a subclass of the
class, then a new instance of the exception class will be created with exception arguments copied from
the given instance. If instanceis an instance of a subclass of the exception class, then the new exception
will be instantiated from the subclass, not the original exception class.