The functions 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
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 -1 if they return an integer
(exception: the PyArg_Parse*()
functions return 1 for success and
0 for failure). When a function must fail because of some function it
called failed, it generally doesn't set the error indicator; the
function it called already set it.
The error indicator consists of three Python objects corresponding to
the Python variables sys.exc_type
, sys.exc_value
and
sys.exc_traceback
. API functions exist to interact with the
error indicator in various ways. There is a separate error indicator
for each thread.
sys.stderr
and clear the error
indicator. Call this function only when the error indicator is set.
(Otherwise it will cause a fatal error!)
type
(the first argument to the last call to one of the
PyErr_Set*()
functions or to PyErr_Restore()
). If not
set, return NULL. You do not own a reference to the return value,
so you do not need to Py_DECREF()
it. Note: do not compare the
return value to a specific exception; use
PyErr_ExceptionMatches
instead, shown below.
PyErr_GivenExceptionMatches(PyErr_Occurred(), exc)
.
This should only be called when an exception is actually set.
PyErr_Fetch()
below can be ``unnormalized'', meaning that
*exc is a class object but *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.
PyExc_RuntimeError
. You need not
increment its reference count. The second argument is an error
message; it is converted to a string object.
PyErr_SetString()
but lets you
specify an arbitrary Python object for the ``value'' of the exception.
You need not increment its reference count.
PyErr_SetString(type, Py_None
.
PyErr_SetString(PyExc_TypeError,
message)
, where message indicates that a built-in operation
was invoked with an illegal argument. It is mostly for internal use.
PyErr_SetNone(PyExc_MemoryError)
; it
returns NULL so an object allocation function can write
return PyErr_NoMemory();
when it runs out of memory.
errno
.
It constructs a tuple object whose first item is the integer
errno
value and whose second item is the corresponding error
message (gotten from strerror()
), and then calls
PyErr_SetObject(type, object)
. On Unix, when
the errno
value is EINTR
, indicating an interrupted
system call, this calls 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
return PyErr_NoMemory();
when the system call returns an error.
PyErr_SetString(PyExc_TypeError,
message)
, where 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.
signal
module is
supported, this can invoke a signal handler written in Python. In all
cases, the default effect for SIGINT
is to raise the
KeyboadInterrupt
exception. If an exception is raised the
error indicator is set and the function returns 1; otherwise the
function returns 0. The error indicator may or may not be cleared if
it was previously set.
SIGINT
signal arriving - the next time
PyErr_CheckSignals()
is called, KeyboadInterrupt
will be
raised.
module.class
. The base and dict
arguments are normally NULL. Normally, this creates a class
object derived from the root for all exceptions, the built-in name
Exception
(accessible in C as PyExc_Exception
). In this
case the __module__
attribute of the new class is set to the
first part (up to the last dot) of the name argument, and the
class name is set to the last part (after the last dot). When the
user has specified the -X
command line option to use string
exceptions, for backward compatibility, or when the base
argument is not a class object (and not NULL), a string object
created from the entire name argument is returned. The
base argument can be used to specify an alternate base class.
The dict argument can be used to specify a dictionary of class
variables and methods.
guido@CNRI.Reston.Va.US