10
The functions described in this chapter will let you handle and raise Python
11
exceptions. It is important to understand some of the basics of Python
12
exception handling. It works somewhat like the Unix :cdata:`errno` variable:
13
there is a global indicator (per thread) of the last error that occurred. Most
14
functions don't clear this on success, but will set it to indicate the cause of
15
the error on failure. Most functions also return an error indicator, usually
16
*NULL* if they are supposed to return a pointer, or ``-1`` if they return an
17
integer (exception: the :cfunc:`PyArg_\*` functions return ``1`` for success and
20
When a function must fail because some function it called failed, it generally
21
doesn't set the error indicator; the function it called already set it. It is
22
responsible for either handling the error and clearing the exception or
23
returning after cleaning up any resources it holds (such as object references or
24
memory allocations); it should *not* continue normally if it is not prepared to
25
handle the error. If returning due to an error, it is important to indicate to
26
the caller that an error has been set. If the error is not handled or carefully
27
propagated, additional calls into the Python/C API may not behave as intended
28
and may fail in mysterious ways.
30
The error indicator consists of three Python objects corresponding to the result
31
of ``sys.exc_info()``. API functions exist to interact with the error indicator
32
in various ways. There is a separate error indicator for each thread.
34
.. XXX Order of these should be more thoughtful.
35
Either alphabetical or some kind of structure.
38
.. cfunction:: void PyErr_PrintEx(int set_sys_last_vars)
40
Print a standard traceback to ``sys.stderr`` and clear the error indicator.
41
Call this function only when the error indicator is set. (Otherwise it will
44
If *set_sys_last_vars* is nonzero, the variables :data:`sys.last_type`,
45
:data:`sys.last_value` and :data:`sys.last_traceback` will be set to the
46
type, value and traceback of the printed exception, respectively.
49
.. cfunction:: void PyErr_Print()
51
Alias for ``PyErr_PrintEx(1)``.
54
.. cfunction:: PyObject* PyErr_Occurred()
56
Test whether the error indicator is set. If set, return the exception *type*
57
(the first argument to the last call to one of the :cfunc:`PyErr_Set\*`
58
functions or to :cfunc:`PyErr_Restore`). If not set, return *NULL*. You do not
59
own a reference to the return value, so you do not need to :cfunc:`Py_DECREF`
64
Do not compare the return value to a specific exception; use
65
:cfunc:`PyErr_ExceptionMatches` instead, shown below. (The comparison could
66
easily fail since the exception may be an instance instead of a class, in the
67
case of a class exception, or it may the a subclass of the expected exception.)
70
.. cfunction:: int PyErr_ExceptionMatches(PyObject *exc)
72
Equivalent to ``PyErr_GivenExceptionMatches(PyErr_Occurred(), exc)``. This
73
should only be called when an exception is actually set; a memory access
74
violation will occur if no exception has been raised.
77
.. cfunction:: int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc)
79
Return true if the *given* exception matches the exception in *exc*. If
80
*exc* is a class object, this also returns true when *given* is an instance
81
of a subclass. If *exc* is a tuple, all exceptions in the tuple (and
82
recursively in subtuples) are searched for a match.
85
.. cfunction:: void PyErr_NormalizeException(PyObject**exc, PyObject**val, PyObject**tb)
87
Under certain circumstances, the values returned by :cfunc:`PyErr_Fetch` below
88
can be "unnormalized", meaning that ``*exc`` is a class object but ``*val`` is
89
not an instance of the same class. This function can be used to instantiate
90
the class in that case. If the values are already normalized, nothing happens.
91
The delayed normalization is implemented to improve performance.
94
.. cfunction:: void PyErr_Clear()
96
Clear the error indicator. If the error indicator is not set, there is no
100
.. cfunction:: void PyErr_Fetch(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)
102
Retrieve the error indicator into three variables whose addresses are passed.
103
If the error indicator is not set, set all three variables to *NULL*. If it is
104
set, it will be cleared and you own a reference to each object retrieved. The
105
value and traceback object may be *NULL* even when the type object is not.
109
This function is normally only used by code that needs to handle exceptions or
110
by code that needs to save and restore the error indicator temporarily.
113
.. cfunction:: void PyErr_Restore(PyObject *type, PyObject *value, PyObject *traceback)
115
Set the error indicator from the three objects. If the error indicator is
116
already set, it is cleared first. If the objects are *NULL*, the error
117
indicator is cleared. Do not pass a *NULL* type and non-*NULL* value or
118
traceback. The exception type should be a class. Do not pass an invalid
119
exception type or value. (Violating these rules will cause subtle problems
120
later.) This call takes away a reference to each object: you must own a
121
reference to each object before the call and after the call you no longer own
122
these references. (If you don't understand this, don't use this function. I
127
This function is normally only used by code that needs to save and restore the
128
error indicator temporarily; use :cfunc:`PyErr_Fetch` to save the current
132
.. cfunction:: void PyErr_SetString(PyObject *type, const char *message)
134
This is the most common way to set the error indicator. The first argument
135
specifies the exception type; it is normally one of the standard exceptions,
136
e.g. :cdata:`PyExc_RuntimeError`. You need not increment its reference count.
137
The second argument is an error message; it is converted to a string object.
140
.. cfunction:: void PyErr_SetObject(PyObject *type, PyObject *value)
142
This function is similar to :cfunc:`PyErr_SetString` but lets you specify an
143
arbitrary Python object for the "value" of the exception.
146
.. cfunction:: PyObject* PyErr_Format(PyObject *exception, const char *format, ...)
148
This function sets the error indicator and returns *NULL*. *exception* should be
149
a Python exception (class, not an instance). *format* should be a string,
150
containing format codes, similar to :cfunc:`printf`. The ``width.precision``
151
before a format code is parsed, but the width part is ignored.
153
.. % This should be exactly the same as the table in PyString_FromFormat.
154
.. % One should just refer to the other.
155
.. % The descriptions for %zd and %zu are wrong, but the truth is complicated
156
.. % because not all compilers support the %z width modifier -- we fake it
157
.. % when necessary via interpolating PY_FORMAT_SIZE_T.
159
+-------------------+---------------+--------------------------------+
160
| Format Characters | Type | Comment |
161
+===================+===============+================================+
162
| :attr:`%%` | *n/a* | The literal % character. |
163
+-------------------+---------------+--------------------------------+
164
| :attr:`%c` | int | A single character, |
165
| | | represented as an C int. |
166
+-------------------+---------------+--------------------------------+
167
| :attr:`%d` | int | Exactly equivalent to |
168
| | | ``printf("%d")``. |
169
+-------------------+---------------+--------------------------------+
170
| :attr:`%u` | unsigned int | Exactly equivalent to |
171
| | | ``printf("%u")``. |
172
+-------------------+---------------+--------------------------------+
173
| :attr:`%ld` | long | Exactly equivalent to |
174
| | | ``printf("%ld")``. |
175
+-------------------+---------------+--------------------------------+
176
| :attr:`%lu` | unsigned long | Exactly equivalent to |
177
| | | ``printf("%lu")``. |
178
+-------------------+---------------+--------------------------------+
179
| :attr:`%zd` | Py_ssize_t | Exactly equivalent to |
180
| | | ``printf("%zd")``. |
181
+-------------------+---------------+--------------------------------+
182
| :attr:`%zu` | size_t | Exactly equivalent to |
183
| | | ``printf("%zu")``. |
184
+-------------------+---------------+--------------------------------+
185
| :attr:`%i` | int | Exactly equivalent to |
186
| | | ``printf("%i")``. |
187
+-------------------+---------------+--------------------------------+
188
| :attr:`%x` | int | Exactly equivalent to |
189
| | | ``printf("%x")``. |
190
+-------------------+---------------+--------------------------------+
191
| :attr:`%s` | char\* | A null-terminated C character |
193
+-------------------+---------------+--------------------------------+
194
| :attr:`%p` | void\* | The hex representation of a C |
195
| | | pointer. Mostly equivalent to |
196
| | | ``printf("%p")`` except that |
197
| | | it is guaranteed to start with |
198
| | | the literal ``0x`` regardless |
199
| | | of what the platform's |
200
| | | ``printf`` yields. |
201
+-------------------+---------------+--------------------------------+
203
An unrecognized format character causes all the rest of the format string to be
204
copied as-is to the result string, and any extra arguments discarded.
207
.. cfunction:: void PyErr_SetNone(PyObject *type)
209
This is a shorthand for ``PyErr_SetObject(type, Py_None)``.
212
.. cfunction:: int PyErr_BadArgument()
214
This is a shorthand for ``PyErr_SetString(PyExc_TypeError, message)``, where
215
*message* indicates that a built-in operation was invoked with an illegal
216
argument. It is mostly for internal use.
219
.. cfunction:: PyObject* PyErr_NoMemory()
221
This is a shorthand for ``PyErr_SetNone(PyExc_MemoryError)``; it returns *NULL*
222
so an object allocation function can write ``return PyErr_NoMemory();`` when it
226
.. cfunction:: PyObject* PyErr_SetFromErrno(PyObject *type)
228
.. index:: single: strerror()
230
This is a convenience function to raise an exception when a C library function
231
has returned an error and set the C variable :cdata:`errno`. It constructs a
232
tuple object whose first item is the integer :cdata:`errno` value and whose
233
second item is the corresponding error message (gotten from :cfunc:`strerror`),
234
and then calls ``PyErr_SetObject(type, object)``. On Unix, when the
235
:cdata:`errno` value is :const:`EINTR`, indicating an interrupted system call,
236
this calls :cfunc:`PyErr_CheckSignals`, and if that set the error indicator,
237
leaves it set to that. The function always returns *NULL*, so a wrapper
238
function around a system call can write ``return PyErr_SetFromErrno(type);``
239
when the system call returns an error.
242
.. cfunction:: PyObject* PyErr_SetFromErrnoWithFilename(PyObject *type, const char *filename)
244
Similar to :cfunc:`PyErr_SetFromErrno`, with the additional behavior that if
245
*filename* is not *NULL*, it is passed to the constructor of *type* as a third
246
parameter. In the case of exceptions such as :exc:`IOError` and :exc:`OSError`,
247
this is used to define the :attr:`filename` attribute of the exception instance.
250
.. cfunction:: PyObject* PyErr_SetFromWindowsErr(int ierr)
252
This is a convenience function to raise :exc:`WindowsError`. If called with
253
*ierr* of :cdata:`0`, the error code returned by a call to :cfunc:`GetLastError`
254
is used instead. It calls the Win32 function :cfunc:`FormatMessage` to retrieve
255
the Windows description of error code given by *ierr* or :cfunc:`GetLastError`,
256
then it constructs a tuple object whose first item is the *ierr* value and whose
257
second item is the corresponding error message (gotten from
258
:cfunc:`FormatMessage`), and then calls ``PyErr_SetObject(PyExc_WindowsError,
259
object)``. This function always returns *NULL*. Availability: Windows.
262
.. cfunction:: PyObject* PyErr_SetExcFromWindowsErr(PyObject *type, int ierr)
264
Similar to :cfunc:`PyErr_SetFromWindowsErr`, with an additional parameter
265
specifying the exception type to be raised. Availability: Windows.
268
.. cfunction:: PyObject* PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename)
270
Similar to :cfunc:`PyErr_SetFromWindowsErr`, with the additional behavior that
271
if *filename* is not *NULL*, it is passed to the constructor of
272
:exc:`WindowsError` as a third parameter. Availability: Windows.
275
.. cfunction:: PyObject* PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, char *filename)
277
Similar to :cfunc:`PyErr_SetFromWindowsErrWithFilename`, with an additional
278
parameter specifying the exception type to be raised. Availability: Windows.
281
.. cfunction:: void PyErr_BadInternalCall()
283
This is a shorthand for ``PyErr_SetString(PyExc_SystemError, message)``,
284
where *message* indicates that an internal operation (e.g. a Python/C API
285
function) was invoked with an illegal argument. It is mostly for internal
289
.. cfunction:: int PyErr_WarnEx(PyObject *category, char *message, int stacklevel)
291
Issue a warning message. The *category* argument is a warning category (see
292
below) or *NULL*; the *message* argument is a message string. *stacklevel* is a
293
positive number giving a number of stack frames; the warning will be issued from
294
the currently executing line of code in that stack frame. A *stacklevel* of 1
295
is the function calling :cfunc:`PyErr_WarnEx`, 2 is the function above that,
298
This function normally prints a warning message to *sys.stderr*; however, it is
299
also possible that the user has specified that warnings are to be turned into
300
errors, and in that case this will raise an exception. It is also possible that
301
the function raises an exception because of a problem with the warning machinery
302
(the implementation imports the :mod:`warnings` module to do the heavy lifting).
303
The return value is ``0`` if no exception is raised, or ``-1`` if an exception
304
is raised. (It is not possible to determine whether a warning message is
305
actually printed, nor what the reason is for the exception; this is
306
intentional.) If an exception is raised, the caller should do its normal
307
exception handling (for example, :cfunc:`Py_DECREF` owned references and return
310
Warning categories must be subclasses of :cdata:`Warning`; the default warning
311
category is :cdata:`RuntimeWarning`. The standard Python warning categories are
312
available as global variables whose names are ``PyExc_`` followed by the Python
313
exception name. These have the type :ctype:`PyObject\*`; they are all class
314
objects. Their names are :cdata:`PyExc_Warning`, :cdata:`PyExc_UserWarning`,
315
:cdata:`PyExc_UnicodeWarning`, :cdata:`PyExc_DeprecationWarning`,
316
:cdata:`PyExc_SyntaxWarning`, :cdata:`PyExc_RuntimeWarning`, and
317
:cdata:`PyExc_FutureWarning`. :cdata:`PyExc_Warning` is a subclass of
318
:cdata:`PyExc_Exception`; the other warning categories are subclasses of
319
:cdata:`PyExc_Warning`.
321
For information about warning control, see the documentation for the
322
:mod:`warnings` module and the :option:`-W` option in the command line
323
documentation. There is no C API for warning control.
326
.. cfunction:: int PyErr_WarnExplicit(PyObject *category, const char *message, const char *filename, int lineno, const char *module, PyObject *registry)
328
Issue a warning message with explicit control over all warning attributes. This
329
is a straightforward wrapper around the Python function
330
:func:`warnings.warn_explicit`, see there for more information. The *module*
331
and *registry* arguments may be set to *NULL* to get the default effect
335
.. cfunction:: int PyErr_CheckSignals()
340
single: KeyboardInterrupt (built-in exception)
342
This function interacts with Python's signal handling. It checks whether a
343
signal has been sent to the processes and if so, invokes the corresponding
344
signal handler. If the :mod:`signal` module is supported, this can invoke a
345
signal handler written in Python. In all cases, the default effect for
346
:const:`SIGINT` is to raise the :exc:`KeyboardInterrupt` exception. If an
347
exception is raised the error indicator is set and the function returns ``-1``;
348
otherwise the function returns ``0``. The error indicator may or may not be
349
cleared if it was previously set.
352
.. cfunction:: void PyErr_SetInterrupt()
356
single: KeyboardInterrupt (built-in exception)
358
This function simulates the effect of a :const:`SIGINT` signal arriving --- the
359
next time :cfunc:`PyErr_CheckSignals` is called, :exc:`KeyboardInterrupt` will
360
be raised. It may be called without holding the interpreter lock.
362
.. % XXX This was described as obsolete, but is used in
363
.. % _thread.interrupt_main() (used from IDLE), so it's still needed.
366
.. cfunction:: int PySignal_SetWakeupFd(int fd)
368
This utility function specifies a file descriptor to which a ``'\0'`` byte will
369
be written whenever a signal is received. It returns the previous such file
370
descriptor. The value ``-1`` disables the feature; this is the initial state.
371
This is equivalent to :func:`signal.set_wakeup_fd` in Python, but without any
372
error checking. *fd* should be a valid file descriptor. The function should
373
only be called from the main thread.
376
.. cfunction:: PyObject* PyErr_NewException(char *name, PyObject *base, PyObject *dict)
378
This utility function creates and returns a new exception object. The *name*
379
argument must be the name of the new exception, a C string of the form
380
``module.class``. The *base* and *dict* arguments are normally *NULL*. This
381
creates a class object derived from :exc:`Exception` (accessible in C as
382
:cdata:`PyExc_Exception`).
384
The :attr:`__module__` attribute of the new class is set to the first part (up
385
to the last dot) of the *name* argument, and the class name is set to the last
386
part (after the last dot). The *base* argument can be used to specify alternate
387
base classes; it can either be only one class or a tuple of classes. The *dict*
388
argument can be used to specify a dictionary of class variables and methods.
391
.. cfunction:: void PyErr_WriteUnraisable(PyObject *obj)
393
This utility function prints a warning message to ``sys.stderr`` when an
394
exception has been set but it is impossible for the interpreter to actually
395
raise the exception. It is used, for example, when an exception occurs in an
396
:meth:`__del__` method.
398
The function is called with a single argument *obj* that identifies the context
399
in which the unraisable exception occurred. The repr of *obj* will be printed in
403
.. _standardexceptions:
408
All standard Python exceptions are available as global variables whose names are
409
``PyExc_`` followed by the Python exception name. These have the type
410
:ctype:`PyObject\*`; they are all class objects. For completeness, here are all
413
+------------------------------------+----------------------------+----------+
414
| C Name | Python Name | Notes |
415
+====================================+============================+==========+
416
| :cdata:`PyExc_BaseException` | :exc:`BaseException` | \(1) |
417
+------------------------------------+----------------------------+----------+
418
| :cdata:`PyExc_Exception` | :exc:`Exception` | \(1) |
419
+------------------------------------+----------------------------+----------+
420
| :cdata:`PyExc_ArithmeticError` | :exc:`ArithmeticError` | \(1) |
421
+------------------------------------+----------------------------+----------+
422
| :cdata:`PyExc_LookupError` | :exc:`LookupError` | \(1) |
423
+------------------------------------+----------------------------+----------+
424
| :cdata:`PyExc_AssertionError` | :exc:`AssertionError` | |
425
+------------------------------------+----------------------------+----------+
426
| :cdata:`PyExc_AttributeError` | :exc:`AttributeError` | |
427
+------------------------------------+----------------------------+----------+
428
| :cdata:`PyExc_EOFError` | :exc:`EOFError` | |
429
+------------------------------------+----------------------------+----------+
430
| :cdata:`PyExc_EnvironmentError` | :exc:`EnvironmentError` | \(1) |
431
+------------------------------------+----------------------------+----------+
432
| :cdata:`PyExc_FloatingPointError` | :exc:`FloatingPointError` | |
433
+------------------------------------+----------------------------+----------+
434
| :cdata:`PyExc_IOError` | :exc:`IOError` | |
435
+------------------------------------+----------------------------+----------+
436
| :cdata:`PyExc_ImportError` | :exc:`ImportError` | |
437
+------------------------------------+----------------------------+----------+
438
| :cdata:`PyExc_IndexError` | :exc:`IndexError` | |
439
+------------------------------------+----------------------------+----------+
440
| :cdata:`PyExc_KeyError` | :exc:`KeyError` | |
441
+------------------------------------+----------------------------+----------+
442
| :cdata:`PyExc_KeyboardInterrupt` | :exc:`KeyboardInterrupt` | |
443
+------------------------------------+----------------------------+----------+
444
| :cdata:`PyExc_MemoryError` | :exc:`MemoryError` | |
445
+------------------------------------+----------------------------+----------+
446
| :cdata:`PyExc_NameError` | :exc:`NameError` | |
447
+------------------------------------+----------------------------+----------+
448
| :cdata:`PyExc_NotImplementedError` | :exc:`NotImplementedError` | |
449
+------------------------------------+----------------------------+----------+
450
| :cdata:`PyExc_OSError` | :exc:`OSError` | |
451
+------------------------------------+----------------------------+----------+
452
| :cdata:`PyExc_OverflowError` | :exc:`OverflowError` | |
453
+------------------------------------+----------------------------+----------+
454
| :cdata:`PyExc_ReferenceError` | :exc:`ReferenceError` | \(2) |
455
+------------------------------------+----------------------------+----------+
456
| :cdata:`PyExc_RuntimeError` | :exc:`RuntimeError` | |
457
+------------------------------------+----------------------------+----------+
458
| :cdata:`PyExc_SyntaxError` | :exc:`SyntaxError` | |
459
+------------------------------------+----------------------------+----------+
460
| :cdata:`PyExc_SystemError` | :exc:`SystemError` | |
461
+------------------------------------+----------------------------+----------+
462
| :cdata:`PyExc_SystemExit` | :exc:`SystemExit` | |
463
+------------------------------------+----------------------------+----------+
464
| :cdata:`PyExc_TypeError` | :exc:`TypeError` | |
465
+------------------------------------+----------------------------+----------+
466
| :cdata:`PyExc_ValueError` | :exc:`ValueError` | |
467
+------------------------------------+----------------------------+----------+
468
| :cdata:`PyExc_WindowsError` | :exc:`WindowsError` | \(3) |
469
+------------------------------------+----------------------------+----------+
470
| :cdata:`PyExc_ZeroDivisionError` | :exc:`ZeroDivisionError` | |
471
+------------------------------------+----------------------------+----------+
474
single: PyExc_BaseException
475
single: PyExc_Exception
476
single: PyExc_ArithmeticError
477
single: PyExc_LookupError
478
single: PyExc_AssertionError
479
single: PyExc_AttributeError
480
single: PyExc_EOFError
481
single: PyExc_EnvironmentError
482
single: PyExc_FloatingPointError
483
single: PyExc_IOError
484
single: PyExc_ImportError
485
single: PyExc_IndexError
486
single: PyExc_KeyError
487
single: PyExc_KeyboardInterrupt
488
single: PyExc_MemoryError
489
single: PyExc_NameError
490
single: PyExc_NotImplementedError
491
single: PyExc_OSError
492
single: PyExc_OverflowError
493
single: PyExc_ReferenceError
494
single: PyExc_RuntimeError
495
single: PyExc_SyntaxError
496
single: PyExc_SystemError
497
single: PyExc_SystemExit
498
single: PyExc_TypeError
499
single: PyExc_ValueError
500
single: PyExc_WindowsError
501
single: PyExc_ZeroDivisionError
506
This is a base class for other standard exceptions.
509
This is the same as :exc:`weakref.ReferenceError`.
512
Only defined on Windows; protect code that uses this by testing that the
513
preprocessor macro ``MS_WINDOWS`` is defined.
added
removed
Doc/c-api/exceptions.rst
