402 lines
20 KiB
TeX
402 lines
20 KiB
TeX
\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
|
|
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 (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 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.
|
|
% XXX This was described as obsolete, but is used in
|
|
% thread.interrupt_main() (used from IDLE), so it's still needed.
|
|
\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 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\ttindex{PyExc_Exception}}{\exception{Exception}}{(1)}
|
|
\lineiii{PyExc_StandardError\ttindex{PyExc_StandardError}}{\exception{StandardError}}{(1)}
|
|
\lineiii{PyExc_ArithmeticError\ttindex{PyExc_ArithmeticError}}{\exception{ArithmeticError}}{(1)}
|
|
\lineiii{PyExc_LookupError\ttindex{PyExc_LookupError}}{\exception{LookupError}}{(1)}
|
|
\lineiii{PyExc_AssertionError\ttindex{PyExc_AssertionError}}{\exception{AssertionError}}{}
|
|
\lineiii{PyExc_AttributeError\ttindex{PyExc_AttributeError}}{\exception{AttributeError}}{}
|
|
\lineiii{PyExc_EOFError\ttindex{PyExc_EOFError}}{\exception{EOFError}}{}
|
|
\lineiii{PyExc_EnvironmentError\ttindex{PyExc_EnvironmentError}}{\exception{EnvironmentError}}{(1)}
|
|
\lineiii{PyExc_FloatingPointError\ttindex{PyExc_FloatingPointError}}{\exception{FloatingPointError}}{}
|
|
\lineiii{PyExc_IOError\ttindex{PyExc_IOError}}{\exception{IOError}}{}
|
|
\lineiii{PyExc_ImportError\ttindex{PyExc_ImportError}}{\exception{ImportError}}{}
|
|
\lineiii{PyExc_IndexError\ttindex{PyExc_IndexError}}{\exception{IndexError}}{}
|
|
\lineiii{PyExc_KeyError\ttindex{PyExc_KeyError}}{\exception{KeyError}}{}
|
|
\lineiii{PyExc_KeyboardInterrupt\ttindex{PyExc_KeyboardInterrupt}}{\exception{KeyboardInterrupt}}{}
|
|
\lineiii{PyExc_MemoryError\ttindex{PyExc_MemoryError}}{\exception{MemoryError}}{}
|
|
\lineiii{PyExc_NameError\ttindex{PyExc_NameError}}{\exception{NameError}}{}
|
|
\lineiii{PyExc_NotImplementedError\ttindex{PyExc_NotImplementedError}}{\exception{NotImplementedError}}{}
|
|
\lineiii{PyExc_OSError\ttindex{PyExc_OSError}}{\exception{OSError}}{}
|
|
\lineiii{PyExc_OverflowError\ttindex{PyExc_OverflowError}}{\exception{OverflowError}}{}
|
|
\lineiii{PyExc_ReferenceError\ttindex{PyExc_ReferenceError}}{\exception{ReferenceError}}{(2)}
|
|
\lineiii{PyExc_RuntimeError\ttindex{PyExc_RuntimeError}}{\exception{RuntimeError}}{}
|
|
\lineiii{PyExc_SyntaxError\ttindex{PyExc_SyntaxError}}{\exception{SyntaxError}}{}
|
|
\lineiii{PyExc_SystemError\ttindex{PyExc_SystemError}}{\exception{SystemError}}{}
|
|
\lineiii{PyExc_SystemExit\ttindex{PyExc_SystemExit}}{\exception{SystemExit}}{}
|
|
\lineiii{PyExc_TypeError\ttindex{PyExc_TypeError}}{\exception{TypeError}}{}
|
|
\lineiii{PyExc_ValueError\ttindex{PyExc_ValueError}}{\exception{ValueError}}{}
|
|
\lineiii{PyExc_WindowsError\ttindex{PyExc_WindowsError}}{\exception{WindowsError}}{(3)}
|
|
\lineiii{PyExc_ZeroDivisionError\ttindex{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.
|