| \chapter{Exception Handling \label{exceptionHandling}} |
| |
| The functions described in this chapter will let you handle and raise Python |
| exceptions. It is important to understand some of the basics of |
| Python exception handling. It works somewhat like the |
| \UNIX{} \cdata{errno} variable: there is a global indicator (per |
| thread) of the last error that occurred. Most functions don't clear |
| this on success, but will set it to indicate the cause of the error on |
| failure. Most functions also return an error indicator, usually |
| \NULL{} if they are supposed to return a pointer, or \code{-1} if they |
| return an integer (exception: the \cfunction{PyArg_*()} functions |
| return \code{1} for success and \code{0} for failure). |
| |
| When a function must fail because some function it called failed, it |
| generally doesn't set the error indicator; the function it called |
| already set it. It is responsible for either handling the error and |
| clearing the exception or returning after cleaning up any resources it |
| holds (such as object references or memory allocations); it should |
| \emph{not} continue normally if it is not prepared to handle the |
| error. If returning due to an error, it is important to indicate to |
| the caller that an error has been set. If the error is not handled or |
| carefully propagated, additional calls into the Python/C API may not |
| behave as intended and may fail in mysterious ways. |
| |
| The error indicator consists of three Python objects corresponding to |
| \withsubitem{(in module sys)}{ |
| \ttindex{exc_type}\ttindex{exc_value}\ttindex{exc_traceback}} |
| the Python variables \code{sys.exc_type}, \code{sys.exc_value} and |
| \code{sys.exc_traceback}. API functions exist to interact with the |
| error indicator in various ways. There is a separate error indicator |
| for each thread. |
| |
| % XXX Order of these should be more thoughtful. |
| % Either alphabetical or some kind of structure. |
| |
| \begin{cfuncdesc}{void}{PyErr_Print}{} |
| Print a standard traceback to \code{sys.stderr} and clear the error |
| indicator. Call this function only when the error indicator is |
| set. (Otherwise it will cause a fatal error!) |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyErr_Occurred}{} |
| Test whether the error indicator is set. If set, return the |
| exception \emph{type} (the first argument to the last call to one of |
| the \cfunction{PyErr_Set*()} functions or to |
| \cfunction{PyErr_Restore()}). If not set, return \NULL. You do |
| not own a reference to the return value, so you do not need to |
| \cfunction{Py_DECREF()} it. \note{Do not compare the return value |
| to a specific exception; use \cfunction{PyErr_ExceptionMatches()} |
| instead, shown below. (The comparison could easily fail since the |
| exception may be an instance instead of a class, in the case of a |
| class exception, or it may the a subclass of the expected |
| exception.)} |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyErr_ExceptionMatches}{PyObject *exc} |
| Equivalent to \samp{PyErr_GivenExceptionMatches(PyErr_Occurred(), |
| \var{exc})}. This should only be called when an exception is |
| actually set; a memory access violation will occur if no exception |
| has been raised. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyErr_GivenExceptionMatches}{PyObject *given, PyObject *exc} |
| Return true if the \var{given} exception matches the exception in |
| \var{exc}. If \var{exc} is a class object, this also returns true |
| when \var{given} is an instance of a subclass. If \var{exc} is a |
| tuple, all exceptions in the tuple (and recursively in subtuples) |
| are searched for a match. If \var{given} is \NULL, a memory access |
| violation will occur. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{PyErr_NormalizeException}{PyObject**exc, PyObject**val, PyObject**tb} |
| Under certain circumstances, the values returned by |
| \cfunction{PyErr_Fetch()} below can be ``unnormalized'', meaning |
| that \code{*\var{exc}} is a class object but \code{*\var{val}} is |
| not an instance of the same class. This function can be used to |
| instantiate the class in that case. If the values are already |
| normalized, nothing happens. The delayed normalization is |
| implemented to improve performance. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{PyErr_Clear}{} |
| Clear the error indicator. If the error indicator is not set, there |
| is no effect. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{PyErr_Fetch}{PyObject **ptype, PyObject **pvalue, |
| PyObject **ptraceback} |
| Retrieve the error indicator into three variables whose addresses |
| are passed. If the error indicator is not set, set all three |
| variables to \NULL. If it is set, it will be cleared and you own a |
| reference to each object retrieved. The value and traceback object |
| may be \NULL{} even when the type object is not. \note{This |
| function is normally only used by code that needs to handle |
| exceptions or by code that needs to save and restore the error |
| indicator temporarily.} |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{PyErr_Restore}{PyObject *type, PyObject *value, |
| PyObject *traceback} |
| Set the error indicator from the three objects. If the error |
| indicator is already set, it is cleared first. If the objects are |
| \NULL, the error indicator is cleared. Do not pass a \NULL{} type |
| and non-\NULL{} value or traceback. The exception type should be a |
| string or class. Do not pass an invalid exception type or value. |
| (Violating these rules will cause subtle problems later.) This call |
| takes away a reference to each object: you must own a reference to |
| each object before the call and after the call you no longer own |
| these references. (If you don't understand this, don't use this |
| function. I warned you.) \note{This function is normally only used |
| by code that needs to save and restore the error indicator |
| temporarily; use \cfunction{PyErr_Fetch()} to save the current |
| exception state.} |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{PyErr_SetString}{PyObject *type, char *message} |
| This is the most common way to set the error indicator. The first |
| argument specifies the exception type; it is normally one of the |
| standard exceptions, e.g. \cdata{PyExc_RuntimeError}. You need not |
| increment its reference count. The second argument is an error |
| message; it is converted to a string object. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{PyErr_SetObject}{PyObject *type, PyObject *value} |
| This function is similar to \cfunction{PyErr_SetString()} but lets |
| you specify an arbitrary Python object for the ``value'' of the |
| exception. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyErr_Format}{PyObject *exception, |
| const char *format, \moreargs} |
| This function sets the error indicator and returns \NULL.. |
| \var{exception} should be a Python exception (string or class, not |
| an instance). \var{format} should be a string, containing format |
| codes, similar to \cfunction{printf()}. The \code{width.precision} |
| before a format code is parsed, but the width part is ignored. |
| |
| \begin{tableii}{c|l}{character}{Character}{Meaning} |
| \lineii{c}{Character, as an \ctype{int} parameter} |
| \lineii{d}{Number in decimal, as an \ctype{int} parameter} |
| \lineii{x}{Number in hexadecimal, as an \ctype{int} parameter} |
| \lineii{s}{A string, as a \ctype{char *} parameter} |
| \lineii{p}{A hex pointer, as a \ctype{void *} parameter} |
| \end{tableii} |
| |
| An unrecognized format character causes all the rest of the format |
| string to be copied as-is to the result string, and any extra |
| arguments discarded. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{PyErr_SetNone}{PyObject *type} |
| This is a shorthand for \samp{PyErr_SetObject(\var{type}, |
| Py_None)}. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyErr_BadArgument}{} |
| This is a shorthand for \samp{PyErr_SetString(PyExc_TypeError, |
| \var{message})}, where \var{message} indicates that a built-in |
| operation was invoked with an illegal argument. It is mostly for |
| internal use. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyErr_NoMemory}{} |
| This is a shorthand for \samp{PyErr_SetNone(PyExc_MemoryError)}; it |
| returns \NULL{} so an object allocation function can write |
| \samp{return PyErr_NoMemory();} when it runs out of memory. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyErr_SetFromErrno}{PyObject *type} |
| This is a convenience function to raise an exception when a C |
| library function has returned an error and set the C variable |
| \cdata{errno}. It constructs a tuple object whose first item is the |
| integer \cdata{errno} value and whose second item is the |
| corresponding error message (gotten from |
| \cfunction{strerror()}\ttindex{strerror()}), and then calls |
| \samp{PyErr_SetObject(\var{type}, \var{object})}. On \UNIX, when |
| the \cdata{errno} value is \constant{EINTR}, indicating an |
| interrupted system call, this calls |
| \cfunction{PyErr_CheckSignals()}, and if that set the error |
| indicator, leaves it set to that. The function always returns |
| \NULL, so a wrapper function around a system call can write |
| \samp{return PyErr_SetFromErrno(\var{type});} when the system call |
| returns an error. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyErr_SetFromErrnoWithFilename}{PyObject *type, |
| char *filename} |
| Similar to \cfunction{PyErr_SetFromErrno()}, with the additional |
| behavior that if \var{filename} is not \NULL, it is passed to the |
| constructor of \var{type} as a third parameter. In the case of |
| exceptions such as \exception{IOError} and \exception{OSError}, this |
| is used to define the \member{filename} attribute of the exception |
| instance. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyErr_SetFromWindowsErr}{int ierr} |
| This is a convenience function to raise \exception{WindowsError}. |
| If called with \var{ierr} of \cdata{0}, the error code returned by a |
| call to \cfunction{GetLastError()} is used instead. It calls the |
| Win32 function \cfunction{FormatMessage()} to retrieve the Windows |
| description of error code given by \var{ierr} or |
| \cfunction{GetLastError()}, then it constructs a tuple object whose |
| first item is the \var{ierr} value and whose second item is the |
| corresponding error message (gotten from |
| \cfunction{FormatMessage()}), and then calls |
| \samp{PyErr_SetObject(\var{PyExc_WindowsError}, \var{object})}. |
| This function always returns \NULL. |
| Availability: Windows. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyErr_SetExcFromWindowsErr}{PyObject *type, |
| int ierr} |
| Similar to \cfunction{PyErr_SetFromWindowsErr()}, with an additional |
| parameter specifying the exception type to be raised. |
| Availability: Windows. |
| \versionadded{2.3} |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyErr_SetFromWindowsErrWithFilename}{int ierr, |
| char *filename} |
| Similar to \cfunction{PyErr_SetFromWindowsErr()}, with the |
| additional behavior that if \var{filename} is not \NULL, it is |
| passed to the constructor of \exception{WindowsError} as a third |
| parameter. |
| Availability: Windows. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyErr_SetExcFromWindowsErrWithFilename} |
| {PyObject *type, int ierr, char *filename} |
| Similar to \cfunction{PyErr_SetFromWindowsErrWithFilename()}, with |
| an additional parameter specifying the exception type to be raised. |
| Availability: Windows. |
| \versionadded{2.3} |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{PyErr_BadInternalCall}{} |
| This is a shorthand for \samp{PyErr_SetString(PyExc_TypeError, |
| \var{message})}, where \var{message} indicates that an internal |
| operation (e.g. a Python/C API function) was invoked with an illegal |
| argument. It is mostly for internal use. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyErr_Warn}{PyObject *category, char *message} |
| Issue a warning message. The \var{category} argument is a warning |
| category (see below) or \NULL; the \var{message} argument is a |
| message string. |
| |
| This function normally prints a warning message to \var{sys.stderr}; |
| however, it is also possible that the user has specified that |
| warnings are to be turned into errors, and in that case this will |
| raise an exception. It is also possible that the function raises an |
| exception because of a problem with the warning machinery (the |
| implementation imports the \module{warnings} module to do the heavy |
| lifting). The return value is \code{0} if no exception is raised, |
| or \code{-1} if an exception is raised. (It is not possible to |
| determine whether a warning message is actually printed, nor what |
| the reason is for the exception; this is intentional.) If an |
| exception is raised, the caller should do its normal exception |
| handling (for example, \cfunction{Py_DECREF()} owned references and |
| return an error value). |
| |
| Warning categories must be subclasses of \cdata{Warning}; the |
| default warning category is \cdata{RuntimeWarning}. The standard |
| Python warning categories are available as global variables whose |
| names are \samp{PyExc_} followed by the Python exception name. |
| These have the type \ctype{PyObject*}; they are all class objects. |
| Their names are \cdata{PyExc_Warning}, \cdata{PyExc_UserWarning}, |
| \cdata{PyExc_DeprecationWarning}, \cdata{PyExc_SyntaxWarning}, |
| \cdata{PyExc_RuntimeWarning}, and \cdata{PyExc_FutureWarning}. |
| \cdata{PyExc_Warning} is a subclass of \cdata{PyExc_Exception}; the |
| other warning categories are subclasses of \cdata{PyExc_Warning}. |
| |
| For information about warning control, see the documentation for the |
| \module{warnings} module and the \programopt{-W} option in the |
| command line documentation. There is no C API for warning control. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyErr_WarnExplicit}{PyObject *category, char *message, |
| char *filename, int lineno, char *module, PyObject *registry} |
| Issue a warning message with explicit control over all warning |
| attributes. This is a straightforward wrapper around the Python |
| function \function{warnings.warn_explicit()}, see there for more |
| information. The \var{module} and \var{registry} arguments may be |
| set to \NULL{} to get the default effect described there. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{int}{PyErr_CheckSignals}{} |
| This function interacts with Python's signal handling. It checks |
| whether a signal has been sent to the processes and if so, invokes |
| the corresponding signal handler. If the |
| \module{signal}\refbimodindex{signal} module is supported, this can |
| invoke a signal handler written in Python. In all cases, the |
| default effect for \constant{SIGINT}\ttindex{SIGINT} is to raise the |
| \withsubitem{(built-in exception)}{\ttindex{KeyboardInterrupt}} |
| \exception{KeyboardInterrupt} exception. If an exception is raised |
| the error indicator is set and the function returns \code{1}; |
| otherwise the function returns \code{0}. The error indicator may or |
| may not be cleared if it was previously set. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{PyErr_SetInterrupt}{} |
| This function is obsolete. It simulates the effect of a |
| \constant{SIGINT}\ttindex{SIGINT} signal arriving --- the next time |
| \cfunction{PyErr_CheckSignals()} is called, |
| \withsubitem{(built-in exception)}{\ttindex{KeyboardInterrupt}} |
| \exception{KeyboardInterrupt} will be raised. It may be called |
| without holding the interpreter lock. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{PyObject*}{PyErr_NewException}{char *name, |
| PyObject *base, |
| PyObject *dict} |
| This utility function creates and returns a new exception object. |
| The \var{name} argument must be the name of the new exception, a C |
| string of the form \code{module.class}. The \var{base} and |
| \var{dict} arguments are normally \NULL. This creates a class |
| object derived from the root for all exceptions, the built-in name |
| \exception{Exception} (accessible in C as \cdata{PyExc_Exception}). |
| The \member{__module__} attribute of the new class is set to the |
| first part (up to the last dot) of the \var{name} argument, and the |
| class name is set to the last part (after the last dot). The |
| \var{base} argument can be used to specify an alternate base class. |
| The \var{dict} argument can be used to specify a dictionary of class |
| variables and methods. |
| \end{cfuncdesc} |
| |
| \begin{cfuncdesc}{void}{PyErr_WriteUnraisable}{PyObject *obj} |
| This utility function prints a warning message to \code{sys.stderr} |
| when an exception has been set but it is impossible for the |
| interpreter to actually raise the exception. It is used, for |
| example, when an exception occurs in an \method{__del__()} method. |
| |
| The function is called with a single argument \var{obj} that |
| identifies where the context in which the unraisable exception |
| occurred. The repr of \var{obj} will be printed in the warning |
| message. |
| \end{cfuncdesc} |
| |
| \section{Standard Exceptions \label{standardExceptions}} |
| |
| All standard Python exceptions are available as global variables whose |
| names are \samp{PyExc_} followed by the Python exception name. These |
| have the type \ctype{PyObject*}; they are all class objects. For |
| completeness, here are all the variables: |
| |
| \begin{tableiii}{l|l|c}{cdata}{C Name}{Python Name}{Notes} |
| \lineiii{PyExc_Exception}{\exception{Exception}}{(1)} |
| \lineiii{PyExc_StandardError}{\exception{StandardError}}{(1)} |
| \lineiii{PyExc_ArithmeticError}{\exception{ArithmeticError}}{(1)} |
| \lineiii{PyExc_LookupError}{\exception{LookupError}}{(1)} |
| \lineiii{PyExc_AssertionError}{\exception{AssertionError}}{} |
| \lineiii{PyExc_AttributeError}{\exception{AttributeError}}{} |
| \lineiii{PyExc_EOFError}{\exception{EOFError}}{} |
| \lineiii{PyExc_EnvironmentError}{\exception{EnvironmentError}}{(1)} |
| \lineiii{PyExc_FloatingPointError}{\exception{FloatingPointError}}{} |
| \lineiii{PyExc_IOError}{\exception{IOError}}{} |
| \lineiii{PyExc_ImportError}{\exception{ImportError}}{} |
| \lineiii{PyExc_IndexError}{\exception{IndexError}}{} |
| \lineiii{PyExc_KeyError}{\exception{KeyError}}{} |
| \lineiii{PyExc_KeyboardInterrupt}{\exception{KeyboardInterrupt}}{} |
| \lineiii{PyExc_MemoryError}{\exception{MemoryError}}{} |
| \lineiii{PyExc_NameError}{\exception{NameError}}{} |
| \lineiii{PyExc_NotImplementedError}{\exception{NotImplementedError}}{} |
| \lineiii{PyExc_OSError}{\exception{OSError}}{} |
| \lineiii{PyExc_OverflowError}{\exception{OverflowError}}{} |
| \lineiii{PyExc_ReferenceError}{\exception{ReferenceError}}{(2)} |
| \lineiii{PyExc_RuntimeError}{\exception{RuntimeError}}{} |
| \lineiii{PyExc_SyntaxError}{\exception{SyntaxError}}{} |
| \lineiii{PyExc_SystemError}{\exception{SystemError}}{} |
| \lineiii{PyExc_SystemExit}{\exception{SystemExit}}{} |
| \lineiii{PyExc_TypeError}{\exception{TypeError}}{} |
| \lineiii{PyExc_ValueError}{\exception{ValueError}}{} |
| \lineiii{PyExc_WindowsError}{\exception{WindowsError}}{(3)} |
| \lineiii{PyExc_ZeroDivisionError}{\exception{ZeroDivisionError}}{} |
| \end{tableiii} |
| |
| \noindent |
| Notes: |
| \begin{description} |
| \item[(1)] |
| This is a base class for other standard exceptions. |
| |
| \item[(2)] |
| This is the same as \exception{weakref.ReferenceError}. |
| |
| \item[(3)] |
| Only defined on Windows; protect code that uses this by testing that |
| the preprocessor macro \code{MS_WINDOWS} is defined. |
| \end{description} |
| |
| |
| \section{Deprecation of String Exceptions} |
| |
| All exceptions built into Python or provided in the standard library |
| are derived from \exception{Exception}. |
| \withsubitem{(built-in exception)}{\ttindex{Exception}} |
| |
| String exceptions are still supported in the interpreter to allow |
| existing code to run unmodified, but this will also change in a future |
| release. |