| single: exc_value (in module sys) |
| single: exc_traceback (in module sys) |
| |
| 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. |
| |
n | .. % XXX Order of these should be more thoughtful. |
n | .. XXX Order of these should be more thoughtful. |
| .. % Either alphabetical or some kind of structure. |
| Either alphabetical or some kind of structure. |
| |
| |
n | .. cfunction:: void PyErr_Print() |
n | .. cfunction:: 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!) |
n | |
| If *set_sys_last_vars* is nonzero, the variables :data:`sys.last_type`, |
| :data:`sys.last_value` and :data:`sys.last_traceback` will be set to the |
| type, value and traceback of the printed exception, respectively. |
| |
| |
| .. cfunction:: void PyErr_Print() |
| |
| Alias for ``PyErr_PrintEx(1)``. |
| |
| |
| .. cfunction:: PyObject* PyErr_Occurred() |
| |
| Test whether the error indicator is set. If set, return the exception *type* |
| (the first argument to the last call to one of the :cfunc:`PyErr_Set\*` |
| functions or to :cfunc:`PyErr_Restore`). If not set, return *NULL*. You do not |
| own a reference to the return value, so you do not need to :cfunc:`Py_DECREF` |
| |
| 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. |
| |
| |
| .. cfunction:: int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc) |
| |
n | Return true if the *given* exception matches the exception in *exc*. If *exc* |
n | Return true if the *given* exception matches the exception in *exc*. If |
| is a class object, this also returns true when *given* is an instance of a |
| *exc* is a class object, this also returns true when *given* is an instance |
| subclass. If *exc* is a tuple, all exceptions in the tuple (and recursively in |
| of a subclass. If *exc* is a tuple, all exceptions in the tuple (and |
| subtuples) are searched for a match. If *given* is *NULL*, a memory access |
| recursively in subtuples) are searched for a match. |
| violation will occur. |
| |
| |
| .. cfunction:: void PyErr_NormalizeException(PyObject**exc, PyObject**val, PyObject**tb) |
| |
| Under certain circumstances, the values returned by :cfunc:`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. |
| |
| Issue a warning message with explicit control over all warning attributes. This |
| is a straightforward wrapper around the Python function |
| :func:`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. |
| |
| |
n | .. cfunction:: int PyErr_WarnPy3k(char *message, int stacklevel) |
| |
| Issue a :exc:`DeprecationWarning` with the given *message* and *stacklevel* |
| if the :cdata:`Py_Py3kWarningFlag` flag is enabled. |
| |
| .. versionadded:: 2.6 |
| |
| |
| .. cfunction:: int PyErr_CheckSignals() |
| |
| .. index:: |
| module: signal |
| single: SIGINT |
| single: KeyboardInterrupt (built-in exception) |
| |
| 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 :mod:`signal` module is supported, this can invoke a |
| signal handler written in Python. In all cases, the default effect for |
| :const:`SIGINT` is to raise the :exc:`KeyboardInterrupt` exception. If an |
n | exception is raised the error indicator is set and the function returns ``1``; |
n | 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. |
| |
| |
| .. cfunction:: void PyErr_SetInterrupt() |
| |
| .. index:: |
| single: SIGINT |
| single: KeyboardInterrupt (built-in exception) |
| |
| This function simulates the effect of a :const:`SIGINT` signal arriving --- the |
| next time :cfunc:`PyErr_CheckSignals` is called, :exc:`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. |
t | |
| |
| .. cfunction:: 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 :func:`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. |
| |
| |
| .. cfunction:: PyObject* PyErr_NewException(char *name, PyObject *base, PyObject *dict) |
| |
| 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 :exc:`Exception` (accessible in C as |