Section 10.6. Raising Exceptions

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.

If the additional parameter to the raise statement used with an exception class is not an instanceinstead, it is a singleton or tuplethen the class is instantiated and args is used as the argument list to the exception. If the second parameter is not present or None, then the argument list is empty.

If SomeException is an instance, then we do not need to instantiate anything. In this case, additional parameters must not be given or must be None. The exception type is the class that instancebelongs to; in other words, this is equivalent to raising the class with this instance, i.e., raise instance.__class__, instance.

Use of string exceptions is deprecated in favor of exception classes, but if SomeException is a string, then it raises the exception identified by string, with any optional parameters (args) as arguments.

Finally, the raise statement by itself without any parameters is a new construct, introduced in Python 1.5, and causes the last exception raised in the current code block to be reraised. If no exception was previously raised, a TypeError exception will occur, because there was no previous exception to reraise.

Due to the many different valid syntax formats for raise (i.e., SomeException can be either a class, instance, or a string), we provide Table 10.1 to illuminate all the different ways which raise can be used.

Table 10.1. Using the raise Statement

raise syntax	Description
raise exclass	Raise an exception, creating an instance of exclass (without any exception arguments)
raise exclass()	Same as above since classes are now exceptions; invoking the class name with the function call operator instantiates an instance of exclass, also with no arguments
raise exclass	Same as above, but also providing exception arguments args, which can be a single argument or a tuple
raiseexclass(args)	Same as above
raise exclass,args, tb	Same as above, but provides traceback object tbto use
raise exclass, instance	Raise exception using instance (normally an instance of exclass); if instance is an instance of a subclass of exclass, then the new exception will be of the subclass type (not of exclass); if instance is not an instance of exclass or an instance of a subclass of exclass, then a new instance of exclass will be created with exception arguments copied from instance
raiseinstance	Raise exception using instance: the exception type is the class that instantiated instance; equivalent to raise instance.__ class__, instance (same as above)
raise string	(Archaic) Raises string exception
raise string, args	Same as above, but raises exception with args
raise string, args, tb	Same as above, but provides traceback object tb to use
raise	(New in 1.5) Reraises previously raised exception; if no exception was previously raised, a TypeErroris raised