
Exception Handling
******************

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 result of ``sys.exc_info()``.  API functions exist to interact
with the error indicator in various ways.  There is a separate error
indicator for each thread.

void PyErr_PrintEx(int set_sys_last_vars)

   Print a standard traceback to ``sys.stderr`` and clear the error
   indicator. Call this function only when the error indicator is set.
   (Otherwise it will cause a fatal error!)

   If *set_sys_last_vars* is nonzero, the variables ``sys.last_type``,
   ``sys.last_value`` and ``sys.last_traceback`` will be set to the
   type, value and traceback of the printed exception, respectively.

void PyErr_Print()

   Alias for ``PyErr_PrintEx(1)``.

PyObject* PyErr_Occurred()
    Return value: Borrowed reference.

   Test whether the error indicator is set.  If set, return the
   exception *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.  (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.)

int PyErr_ExceptionMatches(PyObject *exc)

   Equivalent to ``PyErr_GivenExceptionMatches(PyErr_Occurred(),
   exc)``.  This should only be called when an exception is actually
   set; a memory access violation will occur if no exception has been
   raised.

int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc)

   Return true if the *given* exception matches the exception in
   *exc*.  If *exc* is a class object, this also returns true when
   *given* is an instance of a subclass.  If *exc* is a tuple, all
   exceptions in the tuple (and recursively in subtuples) are searched
   for a match.

void PyErr_NormalizeException(PyObject**exc, PyObject**val, PyObject**tb)

   Under certain circumstances, the values returned by ``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. The delayed
   normalization is implemented to improve performance.

void PyErr_Clear()

   Clear the error indicator.  If the error indicator is not set,
   there is no effect.

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.

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 ``PyErr_Fetch``
     to save the current exception state.

void PyErr_SetString(PyObject *type, const 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. ``PyExc_RuntimeError``.  You need not
   increment its reference count. The second argument is an error
   message; it is converted to a string object.

void PyErr_SetObject(PyObject *type, PyObject *value)

   This function is similar to ``PyErr_SetString`` but lets you
   specify an arbitrary Python object for the "value" of the
   exception.

PyObject* PyErr_Format(PyObject *exception, const char *format, ...)
    Return value: Always NULL.

   This function sets the error indicator and returns *NULL*.
   *exception* should be a Python exception (class, not an instance).
   *format* should be a string, containing format codes, similar to
   ``printf``. The ``width.precision`` before a format code is parsed,
   but the width part is ignored.

   +---------------------+-----------------+----------------------------------+
   | Format Characters   | Type            | Comment                          |
   +=====================+=================+==================================+
   | ``%%``              | *n/a*           | The literal % character.         |
   +---------------------+-----------------+----------------------------------+
   | ``%c``              | int             | A single character, represented  |
   |                     |                 | as an C int.                     |
   +---------------------+-----------------+----------------------------------+
   | ``%d``              | int             | Exactly equivalent to            |
   |                     |                 | ``printf("%d")``.                |
   +---------------------+-----------------+----------------------------------+
   | ``%u``              | unsigned int    | Exactly equivalent to            |
   |                     |                 | ``printf("%u")``.                |
   +---------------------+-----------------+----------------------------------+
   | ``%ld``             | long            | Exactly equivalent to            |
   |                     |                 | ``printf("%ld")``.               |
   +---------------------+-----------------+----------------------------------+
   | ``%lu``             | unsigned long   | Exactly equivalent to            |
   |                     |                 | ``printf("%lu")``.               |
   +---------------------+-----------------+----------------------------------+
   | ``%zd``             | Py_ssize_t      | Exactly equivalent to            |
   |                     |                 | ``printf("%zd")``.               |
   +---------------------+-----------------+----------------------------------+
   | ``%zu``             | size_t          | Exactly equivalent to            |
   |                     |                 | ``printf("%zu")``.               |
   +---------------------+-----------------+----------------------------------+
   | ``%i``              | int             | Exactly equivalent to            |
   |                     |                 | ``printf("%i")``.                |
   +---------------------+-----------------+----------------------------------+
   | ``%x``              | int             | Exactly equivalent to            |
   |                     |                 | ``printf("%x")``.                |
   +---------------------+-----------------+----------------------------------+
   | ``%s``              | char*           | A null-terminated C character    |
   |                     |                 | array.                           |
   +---------------------+-----------------+----------------------------------+
   | ``%p``              | void*           | The hex representation of a C    |
   |                     |                 | pointer. Mostly equivalent to    |
   |                     |                 | ``printf("%p")`` except that it  |
   |                     |                 | is guaranteed to start with the  |
   |                     |                 | literal ``0x`` regardless of     |
   |                     |                 | what the platform's ``printf``   |
   |                     |                 | yields.                          |
   +---------------------+-----------------+----------------------------------+

   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.

void PyErr_SetNone(PyObject *type)

   This is a shorthand for ``PyErr_SetObject(type, Py_None)``.

int PyErr_BadArgument()

   This is a shorthand for ``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.

PyObject* PyErr_NoMemory()
    Return value: Always NULL.

   This is a shorthand for ``PyErr_SetNone(PyExc_MemoryError)``; it
   returns *NULL* so an object allocation function can write ``return
   PyErr_NoMemory();`` when it runs out of memory.

PyObject* PyErr_SetFromErrno(PyObject *type)
    Return value: Always NULL.

   This is a convenience function to raise an exception when a C
   library function has returned an error and set the C variable
   ``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_SetFromErrno(type);`` when the system call returns an error.

PyObject* PyErr_SetFromErrnoWithFilename(PyObject *type, const char *filename)
    Return value: Always NULL.

   Similar to ``PyErr_SetFromErrno``, with the additional behavior
   that if *filename* is not *NULL*, it is passed to the constructor
   of *type* as a third parameter.  In the case of exceptions such as
   ``IOError`` and ``OSError``, this is used to define the
   ``filename`` attribute of the exception instance.

PyObject* PyErr_SetFromWindowsErr(int ierr)
    Return value: Always NULL.

   This is a convenience function to raise ``WindowsError``. If called
   with *ierr* of ``0``, the error code returned by a call to
   ``GetLastError`` is used instead.  It calls the Win32 function
   ``FormatMessage`` to retrieve the Windows description of error code
   given by *ierr* or ``GetLastError``, then it constructs a tuple
   object whose first item is the *ierr* value and whose second item
   is the corresponding error message (gotten from ``FormatMessage``),
   and then calls ``PyErr_SetObject(PyExc_WindowsError, object)``.
   This function always returns *NULL*. Availability: Windows.

PyObject* PyErr_SetExcFromWindowsErr(PyObject *type, int ierr)
    Return value: Always NULL.

   Similar to ``PyErr_SetFromWindowsErr``, with an additional
   parameter specifying the exception type to be raised. Availability:
   Windows.

PyObject* PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename)
    Return value: Always NULL.

   Similar to ``PyErr_SetFromWindowsErr``, with the additional
   behavior that if *filename* is not *NULL*, it is passed to the
   constructor of ``WindowsError`` as a third parameter. Availability:
   Windows.

PyObject* PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, char *filename)
    Return value: Always NULL.

   Similar to ``PyErr_SetFromWindowsErrWithFilename``, with an
   additional parameter specifying the exception type to be raised.
   Availability: Windows.

void PyErr_BadInternalCall()

   This is a shorthand for ``PyErr_SetString(PyExc_SystemError,
   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.

int PyErr_WarnEx(PyObject *category, char *message, int stacklevel)

   Issue a warning message.  The *category* argument is a warning
   category (see below) or *NULL*; the *message* argument is a message
   string.  *stacklevel* is a positive number giving a number of stack
   frames; the warning will be issued from the  currently executing
   line of code in that stack frame.  A *stacklevel* of 1 is the
   function calling ``PyErr_WarnEx``, 2 is  the function above that,
   and so forth.

   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_UnicodeWarning``,
   ``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.

int PyErr_WarnExplicit(PyObject *category, const char *message, const char *filename, int lineno, const char *module, PyObject *registry)

   Issue a warning message with explicit control over all warning
   attributes.  This is a straightforward wrapper around the Python
   function ``warnings.warn_explicit()``, see there for more
   information.  The *module* and *registry* arguments may be set to
   *NULL* to get the default effect described there.

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 ``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
   ``KeyboardInterrupt`` 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.

void PyErr_SetInterrupt()

   This function simulates the effect of a ``SIGINT`` signal arriving
   --- the next time ``PyErr_CheckSignals`` is called,
   ``KeyboardInterrupt`` will be raised.  It may be called without
   holding the interpreter lock.

int PySignal_SetWakeupFd(int fd)

   This utility function specifies a file descriptor to which a
   ``'\0'`` byte will be written whenever a signal is received.  It
   returns the previous such file descriptor.  The value ``-1``
   disables the feature; this is the initial state. This is equivalent
   to ``signal.set_wakeup_fd()`` in Python, but without any error
   checking.  *fd* should be a valid file descriptor.  The function
   should only be called from the main thread.

PyObject* PyErr_NewException(char *name, PyObject *base, PyObject *dict)
    Return value: New reference.

   This utility function creates and returns a new exception object.
   The *name* argument must be the name of the new exception, a C
   string of the form ``module.class``.  The *base* and *dict*
   arguments are normally *NULL*.  This creates a class object derived
   from ``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 alternate base classes; it can
   either be only one class or a tuple of classes. The *dict* argument
   can be used to specify a dictionary of class variables and methods.

void PyErr_WriteUnraisable(PyObject *obj)

   This utility function prints a warning message to ``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.


Exception Objects
=================

PyObject* PyException_GetTraceback(PyObject *ex)

   Return the traceback associated with the exception as a new
   reference, as accessible from Python through ``__traceback__``.  If
   there is no traceback associated, this returns *NULL*.

int PyException_SetTraceback(PyObject *ex, PyObject *tb)

   Set the traceback associated with the exception to *tb*.  Use
   ``Py_None`` to clear it.

PyObject* PyException_GetContext(PyObject *ex)

   Return the context (another exception instance during whose
   handling *ex* was raised) associated with the exception as a new
   reference, as accessible from Python through ``__context__``.  If
   there is no context associated, this returns *NULL*.

void PyException_SetContext(PyObject *ex, PyObject *ctx)

   Set the context associated with the exception to *ctx*.  Use *NULL*
   to clear it.  There is no type check to make sure that *ctx* is an
   exception instance. This steals a reference to *ctx*.

PyObject* PyException_GetCause(PyObject *ex)

   Return the cause (another exception instance set by ``raise ...
   from ...``) associated with the exception as a new reference, as
   accessible from Python through ``__cause__``.  If there is no cause
   associated, this returns *NULL*.

void PyException_SetCause(PyObject *ex, PyObject *ctx)

   Set the cause associated with the exception to *ctx*.  Use *NULL*
   to clear it.  There is no type check to make sure that *ctx* is an
   exception instance. This steals a reference to *ctx*.


Standard Exceptions
===================

All standard Python exceptions 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.  For
completeness, here are all the variables:

+--------------------------------------+------------------------------+------------+
| C Name                               | Python Name                  | Notes      |
+======================================+==============================+============+
| ``PyExc_BaseException``              | ``BaseException``            | (1)        |
+--------------------------------------+------------------------------+------------+
| ``PyExc_Exception``                  | ``Exception``                | (1)        |
+--------------------------------------+------------------------------+------------+
| ``PyExc_ArithmeticError``            | ``ArithmeticError``          | (1)        |
+--------------------------------------+------------------------------+------------+
| ``PyExc_LookupError``                | ``LookupError``              | (1)        |
+--------------------------------------+------------------------------+------------+
| ``PyExc_AssertionError``             | ``AssertionError``           |            |
+--------------------------------------+------------------------------+------------+
| ``PyExc_AttributeError``             | ``AttributeError``           |            |
+--------------------------------------+------------------------------+------------+
| ``PyExc_EOFError``                   | ``EOFError``                 |            |
+--------------------------------------+------------------------------+------------+
| ``PyExc_EnvironmentError``           | ``EnvironmentError``         | (1)        |
+--------------------------------------+------------------------------+------------+
| ``PyExc_FloatingPointError``         | ``FloatingPointError``       |            |
+--------------------------------------+------------------------------+------------+
| ``PyExc_IOError``                    | ``IOError``                  |            |
+--------------------------------------+------------------------------+------------+
| ``PyExc_ImportError``                | ``ImportError``              |            |
+--------------------------------------+------------------------------+------------+
| ``PyExc_IndexError``                 | ``IndexError``               |            |
+--------------------------------------+------------------------------+------------+
| ``PyExc_KeyError``                   | ``KeyError``                 |            |
+--------------------------------------+------------------------------+------------+
| ``PyExc_KeyboardInterrupt``          | ``KeyboardInterrupt``        |            |
+--------------------------------------+------------------------------+------------+
| ``PyExc_MemoryError``                | ``MemoryError``              |            |
+--------------------------------------+------------------------------+------------+
| ``PyExc_NameError``                  | ``NameError``                |            |
+--------------------------------------+------------------------------+------------+
| ``PyExc_NotImplementedError``        | ``NotImplementedError``      |            |
+--------------------------------------+------------------------------+------------+
| ``PyExc_OSError``                    | ``OSError``                  |            |
+--------------------------------------+------------------------------+------------+
| ``PyExc_OverflowError``              | ``OverflowError``            |            |
+--------------------------------------+------------------------------+------------+
| ``PyExc_ReferenceError``             | ``ReferenceError``           | (2)        |
+--------------------------------------+------------------------------+------------+
| ``PyExc_RuntimeError``               | ``RuntimeError``             |            |
+--------------------------------------+------------------------------+------------+
| ``PyExc_SyntaxError``                | ``SyntaxError``              |            |
+--------------------------------------+------------------------------+------------+
| ``PyExc_SystemError``                | ``SystemError``              |            |
+--------------------------------------+------------------------------+------------+
| ``PyExc_SystemExit``                 | ``SystemExit``               |            |
+--------------------------------------+------------------------------+------------+
| ``PyExc_TypeError``                  | ``TypeError``                |            |
+--------------------------------------+------------------------------+------------+
| ``PyExc_ValueError``                 | ``ValueError``               |            |
+--------------------------------------+------------------------------+------------+
| ``PyExc_WindowsError``               | ``WindowsError``             | (3)        |
+--------------------------------------+------------------------------+------------+
| ``PyExc_ZeroDivisionError``          | ``ZeroDivisionError``        |            |
+--------------------------------------+------------------------------+------------+

Notes:

1. This is a base class for other standard exceptions.

2. This is the same as ``weakref.ReferenceError``.

3. Only defined on Windows; protect code that uses this by testing
   that the preprocessor macro ``MS_WINDOWS`` is defined.
