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 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_*() functions
return 1 for success and 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 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
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!)
| ) | 
| PyObject *exc) | 
| PyObject *given, PyObject *exc) | 
| PyObject**exc, PyObject**val, PyObject**tb) | 
*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.  The delayed normalization is
  implemented to improve performance.
| ) | 
| PyObject **ptype, PyObject **pvalue, PyObject **ptraceback) | 
| PyObject *type, PyObject *value, PyObject *traceback) | 
| PyObject *type, char *message) | 
| PyObject *type, PyObject *value) | 
| PyObject *exception, const char *format, ...) | 
width.precision
  before a format code is parsed, but the width part is ignored.
| Character | Meaning | 
|---|---|
| c | Character, as an int parameter | 
| d | Number in decimal, as an int parameter | 
| x | Number in hexadecimal, as an int parameter | 
| s | A string, as a char * parameter | 
| p | A hex pointer, as a void * parameter | 
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.
| PyObject *type) | 
| ) | 
| ) | 
| PyObject *type) | 
| PyObject *type, char *filename) | 
| int ierr) | 
| PyObject *type, int ierr) | 
| int ierr, char *filename) | 
| PyObject *type, int ierr, char *filename) | 
| ) | 
| PyObject *category, char *message) | 
This function normally prints a warning message to 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 warnings module to do the heavy
  lifting).  The return value is 0 if no exception is raised,
  or -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, Py_DECREF() owned references and
  return an error value).
Warning categories must be subclasses of Warning; the default warning category is RuntimeWarning. The standard Python warning categories are available as global variables whose names are "PyExc_" followed by the Python exception name. These have the type PyObject*; they are all class objects. Their names are PyExc_Warning, PyExc_UserWarning, PyExc_DeprecationWarning, PyExc_SyntaxWarning, PyExc_RuntimeWarning, and PyExc_FutureWarning. PyExc_Warning is a subclass of PyExc_Exception; the other warning categories are subclasses of PyExc_Warning.
For information about warning control, see the documentation for the warnings module and the -W option in the command line documentation. There is no C API for warning control.
| PyObject *category, char *message, char *filename, int lineno, char *module, PyObject *registry) | 
| ) | 
1;
  otherwise the function returns 0.  The error indicator may or
  may not be cleared if it was previously set.
| ) | 
| char *name, PyObject *base, PyObject *dict) | 
module.class.  The base and
  dict arguments are normally NULL.  This creates a class
  object derived from the root for all exceptions, the built-in name
  Exception (accessible in C as PyExc_Exception).
  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).  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.
| PyObject *obj) | 
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 __del__() method.
The function is called with a single argument obj that identifies the context in which the unraisable exception occurred. The repr of obj will be printed in the warning message.