rest25/c-api/exceptions.rst => rest262/c-api/exceptions.rst
32   single: exc_value (in module sys)
33   single: exc_traceback (in module sys)
34
35The error indicator consists of three Python objects corresponding to   the
36Python variables ``sys.exc_type``, ``sys.exc_value`` and ``sys.exc_traceback``.
37API functions exist to interact with the error indicator in various ways.  There
38is a separate error indicator for each thread.
39
n40-.. % XXX Order of these should be more thoughtful.
n40+.. XXX Order of these should be more thoughtful.
41-.. % Either alphabetical or some kind of structure.
41+   Either alphabetical or some kind of structure.
42
43
n44-.. cfunction:: void PyErr_Print()
n44+.. cfunction:: void PyErr_PrintEx(int set_sys_last_vars)
45
46   Print a standard traceback to ``sys.stderr`` and clear the error indicator.
47   Call this function only when the error indicator is set.  (Otherwise it will
48   cause a fatal error!)
n49+ 
50+   If *set_sys_last_vars* is nonzero, the variables :data:`sys.last_type`,
51+   :data:`sys.last_value` and :data:`sys.last_traceback` will be set to the
52+   type, value and traceback of the printed exception, respectively.
53+ 
54+ 
55+.. cfunction:: void PyErr_Print()
56+ 
57+   Alias for ``PyErr_PrintEx(1)``.
49
50
51.. cfunction:: PyObject* PyErr_Occurred()
52
53   Test whether the error indicator is set.  If set, return the exception *type*
54   (the first argument to the last call to one of the :cfunc:`PyErr_Set\*`
55   functions or to :cfunc:`PyErr_Restore`).  If not set, return *NULL*.  You do not
56   own a reference to the return value, so you do not need to :cfunc:`Py_DECREF`
68
69   Equivalent to ``PyErr_GivenExceptionMatches(PyErr_Occurred(), exc)``.  This
70   should only be called when an exception is actually set; a memory access
71   violation will occur if no exception has been raised.
72
73
74.. cfunction:: int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc)
75
n76-   Return true if the *given* exception matches the exception in *exc*.  If *exc*
n85+   Return true if the *given* exception matches the exception in *exc*.  If
77-   is a class object, this also returns true when *given* is an instance of a
86+   *exc* is a class object, this also returns true when *given* is an instance
78-   subclass.  If *exc* is a tuple, all exceptions in the tuple (and recursively in
87+   of a subclass.  If *exc* is a tuple, all exceptions in the tuple (and
79-   subtuples) are searched for a match.  If *given* is *NULL*, a memory access
88+   recursively in subtuples) are searched for a match.
80-   violation will occur.
81
82
83.. cfunction:: void PyErr_NormalizeException(PyObject**exc, PyObject**val, PyObject**tb)
84
85   Under certain circumstances, the values returned by :cfunc:`PyErr_Fetch` below
86   can be "unnormalized", meaning that ``*exc`` is a class object but ``*val`` is
87   not an instance of the  same class.  This function can be used to instantiate
88   the class in that case.  If the values are already normalized, nothing happens.
339
340   Issue a warning message with explicit control over all warning attributes.  This
341   is a straightforward wrapper around the Python function
342   :func:`warnings.warn_explicit`, see there for more information.  The *module*
343   and *registry* arguments may be set to *NULL* to get the default effect
344   described there.
345
346
n355+.. cfunction:: int PyErr_WarnPy3k(char *message, int stacklevel)
356+ 
357+   Issue a :exc:`DeprecationWarning` with the given *message* and *stacklevel*
358+   if the :cdata:`Py_Py3kWarningFlag` flag is enabled.
359+ 
360+   .. versionadded:: 2.6
361+ 
362+ 
347.. cfunction:: int PyErr_CheckSignals()
348
349   .. index::
350      module: signal
351      single: SIGINT
352      single: KeyboardInterrupt (built-in exception)
353
354   This function interacts with Python's signal handling.  It checks whether a
355   signal has been sent to the processes and if so, invokes the corresponding
356   signal handler.  If the :mod:`signal` module is supported, this can invoke a
357   signal handler written in Python.  In all cases, the default effect for
358   :const:`SIGINT` is to raise the  :exc:`KeyboardInterrupt` exception.  If an
n359-   exception is raised the error indicator is set and the function returns ``1``;
n375+   exception is raised the error indicator is set and the function returns ``-1``;
360   otherwise the function returns ``0``.  The error indicator may or may not be
361   cleared if it was previously set.
362
363
364.. cfunction:: void PyErr_SetInterrupt()
365
366   .. index::
367      single: SIGINT
368      single: KeyboardInterrupt (built-in exception)
369
370   This function simulates the effect of a :const:`SIGINT` signal arriving --- the
371   next time :cfunc:`PyErr_CheckSignals` is called,  :exc:`KeyboardInterrupt` will
372   be raised.  It may be called without holding the interpreter lock.
373
374   .. % XXX This was described as obsolete, but is used in
375   .. % thread.interrupt_main() (used from IDLE), so it's still needed.
t392+ 
393+ 
394+.. cfunction:: int PySignal_SetWakeupFd(int fd)
395+ 
396+   This utility function specifies a file descriptor to which a ``'\0'`` byte will
397+   be written whenever a signal is received.  It returns the previous such file
398+   descriptor.  The value ``-1`` disables the feature; this is the initial state.
399+   This is equivalent to :func:`signal.set_wakeup_fd` in Python, but without any
400+   error checking.  *fd* should be a valid file descriptor.  The function should
401+   only be called from the main thread.
376
377
378.. cfunction:: PyObject* PyErr_NewException(char *name, PyObject *base, PyObject *dict)
379
380   This utility function creates and returns a new exception object. The *name*
381   argument must be the name of the new exception, a C string of the form
382   ``module.class``.  The *base* and *dict* arguments are normally *NULL*.  This
383   creates a class object derived from :exc:`Exception` (accessible in C as
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op