• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1.. highlight:: c
2
3
4.. _exceptionhandling:
5
6******************
7Exception Handling
8******************
9
10The functions described in this chapter will let you handle and raise Python
11exceptions.  It is important to understand some of the basics of Python
12exception handling.  It works somewhat like the POSIX :c:data:`errno` variable:
13there is a global indicator (per thread) of the last error that occurred.  Most
14C API functions don't clear this on success, but will set it to indicate the
15cause of the error on failure.  Most C API functions also return an error
16indicator, usually ``NULL`` if they are supposed to return a pointer, or ``-1``
17if they return an integer (exception: the :c:func:`PyArg_\*` functions
18return ``1`` for success and ``0`` for failure).
19
20Concretely, the error indicator consists of three object pointers: the
21exception's type, the exception's value, and the traceback object.  Any
22of those pointers can be ``NULL`` if non-set (although some combinations are
23forbidden, for example you can't have a non-``NULL`` traceback if the exception
24type is ``NULL``).
25
26When a function must fail because some function it called failed, it generally
27doesn't set the error indicator; the function it called already set it.  It is
28responsible for either handling the error and clearing the exception or
29returning after cleaning up any resources it holds (such as object references or
30memory allocations); it should *not* continue normally if it is not prepared to
31handle the error.  If returning due to an error, it is important to indicate to
32the caller that an error has been set.  If the error is not handled or carefully
33propagated, additional calls into the Python/C API may not behave as intended
34and may fail in mysterious ways.
35
36.. note::
37   The error indicator is **not** the result of :func:`sys.exc_info()`.
38   The former corresponds to an exception that is not yet caught (and is
39   therefore still propagating), while the latter returns an exception after
40   it is caught (and has therefore stopped propagating).
41
42
43Printing and clearing
44=====================
45
46
47.. c:function:: void PyErr_Clear()
48
49   Clear the error indicator.  If the error indicator is not set, there is no
50   effect.
51
52
53.. c:function:: void PyErr_PrintEx(int set_sys_last_vars)
54
55   Print a standard traceback to ``sys.stderr`` and clear the error indicator.
56   **Unless** the error is a ``SystemExit``, in that case no traceback is
57   printed and the Python process will exit with the error code specified by
58   the ``SystemExit`` instance.
59
60   Call this function **only** when the error indicator is set.  Otherwise it
61   will cause a fatal error!
62
63   If *set_sys_last_vars* is nonzero, the variables :data:`sys.last_type`,
64   :data:`sys.last_value` and :data:`sys.last_traceback` will be set to the
65   type, value and traceback of the printed exception, respectively.
66
67
68.. c:function:: void PyErr_Print()
69
70   Alias for ``PyErr_PrintEx(1)``.
71
72
73.. c:function:: void PyErr_WriteUnraisable(PyObject *obj)
74
75   Call :func:`sys.unraisablehook` using the current exception and *obj*
76   argument.
77
78   This utility function prints a warning message to ``sys.stderr`` when an
79   exception has been set but it is impossible for the interpreter to actually
80   raise the exception.  It is used, for example, when an exception occurs in an
81   :meth:`__del__` method.
82
83   The function is called with a single argument *obj* that identifies the context
84   in which the unraisable exception occurred. If possible,
85   the repr of *obj* will be printed in the warning message.
86
87   An exception must be set when calling this function.
88
89
90Raising exceptions
91==================
92
93These functions help you set the current thread's error indicator.
94For convenience, some of these functions will always return a
95``NULL`` pointer for use in a ``return`` statement.
96
97
98.. c:function:: void PyErr_SetString(PyObject *type, const char *message)
99
100   This is the most common way to set the error indicator.  The first argument
101   specifies the exception type; it is normally one of the standard exceptions,
102   e.g. :c:data:`PyExc_RuntimeError`.  You need not increment its reference count.
103   The second argument is an error message; it is decoded from ``'utf-8'``.
104
105
106.. c:function:: void PyErr_SetObject(PyObject *type, PyObject *value)
107
108   This function is similar to :c:func:`PyErr_SetString` but lets you specify an
109   arbitrary Python object for the "value" of the exception.
110
111
112.. c:function:: PyObject* PyErr_Format(PyObject *exception, const char *format, ...)
113
114   This function sets the error indicator and returns ``NULL``.  *exception*
115   should be a Python exception class.  The *format* and subsequent
116   parameters help format the error message; they have the same meaning and
117   values as in :c:func:`PyUnicode_FromFormat`. *format* is an ASCII-encoded
118   string.
119
120
121.. c:function:: PyObject* PyErr_FormatV(PyObject *exception, const char *format, va_list vargs)
122
123   Same as :c:func:`PyErr_Format`, but taking a :c:type:`va_list` argument rather
124   than a variable number of arguments.
125
126   .. versionadded:: 3.5
127
128
129.. c:function:: void PyErr_SetNone(PyObject *type)
130
131   This is a shorthand for ``PyErr_SetObject(type, Py_None)``.
132
133
134.. c:function:: int PyErr_BadArgument()
135
136   This is a shorthand for ``PyErr_SetString(PyExc_TypeError, message)``, where
137   *message* indicates that a built-in operation was invoked with an illegal
138   argument.  It is mostly for internal use.
139
140
141.. c:function:: PyObject* PyErr_NoMemory()
142
143   This is a shorthand for ``PyErr_SetNone(PyExc_MemoryError)``; it returns ``NULL``
144   so an object allocation function can write ``return PyErr_NoMemory();`` when it
145   runs out of memory.
146
147
148.. c:function:: PyObject* PyErr_SetFromErrno(PyObject *type)
149
150   .. index:: single: strerror()
151
152   This is a convenience function to raise an exception when a C library function
153   has returned an error and set the C variable :c:data:`errno`.  It constructs a
154   tuple object whose first item is the integer :c:data:`errno` value and whose
155   second item is the corresponding error message (gotten from :c:func:`strerror`),
156   and then calls ``PyErr_SetObject(type, object)``.  On Unix, when the
157   :c:data:`errno` value is :const:`EINTR`, indicating an interrupted system call,
158   this calls :c:func:`PyErr_CheckSignals`, and if that set the error indicator,
159   leaves it set to that.  The function always returns ``NULL``, so a wrapper
160   function around a system call can write ``return PyErr_SetFromErrno(type);``
161   when the system call returns an error.
162
163
164.. c:function:: PyObject* PyErr_SetFromErrnoWithFilenameObject(PyObject *type, PyObject *filenameObject)
165
166   Similar to :c:func:`PyErr_SetFromErrno`, with the additional behavior that if
167   *filenameObject* is not ``NULL``, it is passed to the constructor of *type* as
168   a third parameter.  In the case of :exc:`OSError` exception,
169   this is used to define the :attr:`filename` attribute of the
170   exception instance.
171
172
173.. c:function:: PyObject* PyErr_SetFromErrnoWithFilenameObjects(PyObject *type, PyObject *filenameObject, PyObject *filenameObject2)
174
175   Similar to :c:func:`PyErr_SetFromErrnoWithFilenameObject`, but takes a second
176   filename object, for raising errors when a function that takes two filenames
177   fails.
178
179   .. versionadded:: 3.4
180
181
182.. c:function:: PyObject* PyErr_SetFromErrnoWithFilename(PyObject *type, const char *filename)
183
184   Similar to :c:func:`PyErr_SetFromErrnoWithFilenameObject`, but the filename
185   is given as a C string.  *filename* is decoded from the :term:`filesystem
186   encoding and error handler`.
187
188
189.. c:function:: PyObject* PyErr_SetFromWindowsErr(int ierr)
190
191   This is a convenience function to raise :exc:`WindowsError`. If called with
192   *ierr* of :c:data:`0`, the error code returned by a call to :c:func:`GetLastError`
193   is used instead.  It calls the Win32 function :c:func:`FormatMessage` to retrieve
194   the Windows description of error code given by *ierr* or :c:func:`GetLastError`,
195   then it constructs a tuple object whose first item is the *ierr* value and whose
196   second item is the corresponding error message (gotten from
197   :c:func:`FormatMessage`), and then calls ``PyErr_SetObject(PyExc_WindowsError,
198   object)``. This function always returns ``NULL``.
199
200   .. availability:: Windows.
201
202
203.. c:function:: PyObject* PyErr_SetExcFromWindowsErr(PyObject *type, int ierr)
204
205   Similar to :c:func:`PyErr_SetFromWindowsErr`, with an additional parameter
206   specifying the exception type to be raised.
207
208   .. availability:: Windows.
209
210
211.. c:function:: PyObject* PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename)
212
213   Similar to :c:func:`PyErr_SetFromWindowsErrWithFilenameObject`, but the
214   filename is given as a C string.  *filename* is decoded from the filesystem
215   encoding (:func:`os.fsdecode`).
216
217   .. availability:: Windows.
218
219
220.. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilenameObject(PyObject *type, int ierr, PyObject *filename)
221
222   Similar to :c:func:`PyErr_SetFromWindowsErrWithFilenameObject`, with an
223   additional parameter specifying the exception type to be raised.
224
225   .. availability:: Windows.
226
227
228.. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilenameObjects(PyObject *type, int ierr, PyObject *filename, PyObject *filename2)
229
230   Similar to :c:func:`PyErr_SetExcFromWindowsErrWithFilenameObject`,
231   but accepts a second filename object.
232
233   .. availability:: Windows.
234
235   .. versionadded:: 3.4
236
237
238.. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, const char *filename)
239
240   Similar to :c:func:`PyErr_SetFromWindowsErrWithFilename`, with an additional
241   parameter specifying the exception type to be raised.
242
243   .. availability:: Windows.
244
245
246.. c:function:: PyObject* PyErr_SetImportError(PyObject *msg, PyObject *name, PyObject *path)
247
248   This is a convenience function to raise :exc:`ImportError`. *msg* will be
249   set as the exception's message string. *name* and *path*, both of which can
250   be ``NULL``, will be set as the :exc:`ImportError`'s respective ``name``
251   and ``path`` attributes.
252
253   .. versionadded:: 3.3
254
255
256.. c:function:: void PyErr_SyntaxLocationObject(PyObject *filename, int lineno, int col_offset)
257
258   Set file, line, and offset information for the current exception.  If the
259   current exception is not a :exc:`SyntaxError`, then it sets additional
260   attributes, which make the exception printing subsystem think the exception
261   is a :exc:`SyntaxError`.
262
263   .. versionadded:: 3.4
264
265
266.. c:function:: void PyErr_SyntaxLocationEx(const char *filename, int lineno, int col_offset)
267
268   Like :c:func:`PyErr_SyntaxLocationObject`, but *filename* is a byte string
269   decoded from the :term:`filesystem encoding and error handler`.
270
271   .. versionadded:: 3.2
272
273
274.. c:function:: void PyErr_SyntaxLocation(const char *filename, int lineno)
275
276   Like :c:func:`PyErr_SyntaxLocationEx`, but the col_offset parameter is
277   omitted.
278
279
280.. c:function:: void PyErr_BadInternalCall()
281
282   This is a shorthand for ``PyErr_SetString(PyExc_SystemError, message)``,
283   where *message* indicates that an internal operation (e.g. a Python/C API
284   function) was invoked with an illegal argument.  It is mostly for internal
285   use.
286
287
288Issuing warnings
289================
290
291Use these functions to issue warnings from C code.  They mirror similar
292functions exported by the Python :mod:`warnings` module.  They normally
293print a warning message to *sys.stderr*; however, it is
294also possible that the user has specified that warnings are to be turned into
295errors, and in that case they will raise an exception.  It is also possible that
296the functions raise an exception because of a problem with the warning machinery.
297The return value is ``0`` if no exception is raised, or ``-1`` if an exception
298is raised.  (It is not possible to determine whether a warning message is
299actually printed, nor what the reason is for the exception; this is
300intentional.)  If an exception is raised, the caller should do its normal
301exception handling (for example, :c:func:`Py_DECREF` owned references and return
302an error value).
303
304.. c:function:: int PyErr_WarnEx(PyObject *category, const char *message, Py_ssize_t stack_level)
305
306   Issue a warning message.  The *category* argument is a warning category (see
307   below) or ``NULL``; the *message* argument is a UTF-8 encoded string.  *stack_level* is a
308   positive number giving a number of stack frames; the warning will be issued from
309   the  currently executing line of code in that stack frame.  A *stack_level* of 1
310   is the function calling :c:func:`PyErr_WarnEx`, 2 is  the function above that,
311   and so forth.
312
313   Warning categories must be subclasses of :c:data:`PyExc_Warning`;
314   :c:data:`PyExc_Warning` is a subclass of :c:data:`PyExc_Exception`;
315   the default warning category is :c:data:`PyExc_RuntimeWarning`. The standard
316   Python warning categories are available as global variables whose names are
317   enumerated at :ref:`standardwarningcategories`.
318
319   For information about warning control, see the documentation for the
320   :mod:`warnings` module and the :option:`-W` option in the command line
321   documentation.  There is no C API for warning control.
322
323.. c:function:: PyObject* PyErr_SetImportErrorSubclass(PyObject *exception, PyObject *msg, PyObject *name, PyObject *path)
324
325   Much like :c:func:`PyErr_SetImportError` but this function allows for
326   specifying a subclass of :exc:`ImportError` to raise.
327
328   .. versionadded:: 3.6
329
330
331.. c:function:: int PyErr_WarnExplicitObject(PyObject *category, PyObject *message, PyObject *filename, int lineno, PyObject *module, PyObject *registry)
332
333   Issue a warning message with explicit control over all warning attributes.  This
334   is a straightforward wrapper around the Python function
335   :func:`warnings.warn_explicit`, see there for more information.  The *module*
336   and *registry* arguments may be set to ``NULL`` to get the default effect
337   described there.
338
339   .. versionadded:: 3.4
340
341
342.. c:function:: int PyErr_WarnExplicit(PyObject *category, const char *message, const char *filename, int lineno, const char *module, PyObject *registry)
343
344   Similar to :c:func:`PyErr_WarnExplicitObject` except that *message* and
345   *module* are UTF-8 encoded strings, and *filename* is decoded from the
346   :term:`filesystem encoding and error handler`.
347
348
349.. c:function:: int PyErr_WarnFormat(PyObject *category, Py_ssize_t stack_level, const char *format, ...)
350
351   Function similar to :c:func:`PyErr_WarnEx`, but use
352   :c:func:`PyUnicode_FromFormat` to format the warning message.  *format* is
353   an ASCII-encoded string.
354
355   .. versionadded:: 3.2
356
357
358.. c:function:: int PyErr_ResourceWarning(PyObject *source, Py_ssize_t stack_level, const char *format, ...)
359
360   Function similar to :c:func:`PyErr_WarnFormat`, but *category* is
361   :exc:`ResourceWarning` and it passes *source* to :func:`warnings.WarningMessage`.
362
363   .. versionadded:: 3.6
364
365
366Querying the error indicator
367============================
368
369.. c:function:: PyObject* PyErr_Occurred()
370
371   Test whether the error indicator is set.  If set, return the exception *type*
372   (the first argument to the last call to one of the :c:func:`PyErr_Set\*`
373   functions or to :c:func:`PyErr_Restore`).  If not set, return ``NULL``.  You do not
374   own a reference to the return value, so you do not need to :c:func:`Py_DECREF`
375   it.
376
377   The caller must hold the GIL.
378
379   .. note::
380
381      Do not compare the return value to a specific exception; use
382      :c:func:`PyErr_ExceptionMatches` instead, shown below.  (The comparison could
383      easily fail since the exception may be an instance instead of a class, in the
384      case of a class exception, or it may be a subclass of the expected exception.)
385
386
387.. c:function:: int PyErr_ExceptionMatches(PyObject *exc)
388
389   Equivalent to ``PyErr_GivenExceptionMatches(PyErr_Occurred(), exc)``.  This
390   should only be called when an exception is actually set; a memory access
391   violation will occur if no exception has been raised.
392
393
394.. c:function:: int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc)
395
396   Return true if the *given* exception matches the exception type in *exc*.  If
397   *exc* is a class object, this also returns true when *given* is an instance
398   of a subclass.  If *exc* is a tuple, all exception types in the tuple (and
399   recursively in subtuples) are searched for a match.
400
401
402.. c:function:: void PyErr_Fetch(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)
403
404   Retrieve the error indicator into three variables whose addresses are passed.
405   If the error indicator is not set, set all three variables to ``NULL``.  If it is
406   set, it will be cleared and you own a reference to each object retrieved.  The
407   value and traceback object may be ``NULL`` even when the type object is not.
408
409   .. note::
410
411      This function is normally only used by code that needs to catch exceptions or
412      by code that needs to save and restore the error indicator temporarily, e.g.::
413
414         {
415            PyObject *type, *value, *traceback;
416            PyErr_Fetch(&type, &value, &traceback);
417
418            /* ... code that might produce other errors ... */
419
420            PyErr_Restore(type, value, traceback);
421         }
422
423
424.. c:function:: void PyErr_Restore(PyObject *type, PyObject *value, PyObject *traceback)
425
426   Set  the error indicator from the three objects.  If the error indicator is
427   already set, it is cleared first.  If the objects are ``NULL``, the error
428   indicator is cleared.  Do not pass a ``NULL`` type and non-``NULL`` value or
429   traceback.  The exception type should be a class.  Do not pass an invalid
430   exception type or value. (Violating these rules will cause subtle problems
431   later.)  This call takes away a reference to each object: you must own a
432   reference to each object before the call and after the call you no longer own
433   these references.  (If you don't understand this, don't use this function.  I
434   warned you.)
435
436   .. note::
437
438      This function is normally only used by code that needs to save and restore the
439      error indicator temporarily.  Use :c:func:`PyErr_Fetch` to save the current
440      error indicator.
441
442
443.. c:function:: void PyErr_NormalizeException(PyObject**exc, PyObject**val, PyObject**tb)
444
445   Under certain circumstances, the values returned by :c:func:`PyErr_Fetch` below
446   can be "unnormalized", meaning that ``*exc`` is a class object but ``*val`` is
447   not an instance of the  same class.  This function can be used to instantiate
448   the class in that case.  If the values are already normalized, nothing happens.
449   The delayed normalization is implemented to improve performance.
450
451   .. note::
452
453      This function *does not* implicitly set the ``__traceback__``
454      attribute on the exception value. If setting the traceback
455      appropriately is desired, the following additional snippet is needed::
456
457         if (tb != NULL) {
458           PyException_SetTraceback(val, tb);
459         }
460
461
462.. c:function:: void PyErr_GetExcInfo(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)
463
464   Retrieve the exception info, as known from ``sys.exc_info()``.  This refers
465   to an exception that was *already caught*, not to an exception that was
466   freshly raised.  Returns new references for the three objects, any of which
467   may be ``NULL``.  Does not modify the exception info state.
468
469   .. note::
470
471      This function is not normally used by code that wants to handle exceptions.
472      Rather, it can be used when code needs to save and restore the exception
473      state temporarily.  Use :c:func:`PyErr_SetExcInfo` to restore or clear the
474      exception state.
475
476   .. versionadded:: 3.3
477
478
479.. c:function:: void PyErr_SetExcInfo(PyObject *type, PyObject *value, PyObject *traceback)
480
481   Set the exception info, as known from ``sys.exc_info()``.  This refers
482   to an exception that was *already caught*, not to an exception that was
483   freshly raised.  This function steals the references of the arguments.
484   To clear the exception state, pass ``NULL`` for all three arguments.
485   For general rules about the three arguments, see :c:func:`PyErr_Restore`.
486
487   .. note::
488
489      This function is not normally used by code that wants to handle exceptions.
490      Rather, it can be used when code needs to save and restore the exception
491      state temporarily.  Use :c:func:`PyErr_GetExcInfo` to read the exception
492      state.
493
494   .. versionadded:: 3.3
495
496
497Signal Handling
498===============
499
500
501.. c:function:: int PyErr_CheckSignals()
502
503   .. index::
504      module: signal
505      single: SIGINT
506      single: KeyboardInterrupt (built-in exception)
507
508   This function interacts with Python's signal handling.
509
510   If the function is called from the main thread and under the main Python
511   interpreter, it checks whether a signal has been sent to the processes
512   and if so, invokes the corresponding signal handler.  If the :mod:`signal`
513   module is supported, this can invoke a signal handler written in Python.
514
515   The function attempts to handle all pending signals, and then returns ``0``.
516   However, if a Python signal handler raises an exception, the error
517   indicator is set and the function returns ``-1`` immediately (such that
518   other pending signals may not have been handled yet: they will be on the
519   next :c:func:`PyErr_CheckSignals()` invocation).
520
521   If the function is called from a non-main thread, or under a non-main
522   Python interpreter, it does nothing and returns ``0``.
523
524   This function can be called by long-running C code that wants to
525   be interruptible by user requests (such as by pressing Ctrl-C).
526
527   .. note::
528      The default Python signal handler for :const:`SIGINT` raises the
529      :exc:`KeyboardInterrupt` exception.
530
531
532.. c:function:: void PyErr_SetInterrupt()
533
534   .. index::
535      module: signal
536      single: SIGINT
537      single: KeyboardInterrupt (built-in exception)
538
539   Simulate the effect of a :const:`SIGINT` signal arriving.
540   This is equivalent to ``PyErr_SetInterruptEx(SIGINT)``.
541
542   .. note::
543      This function is async-signal-safe.  It can be called without
544      the :term:`GIL` and from a C signal handler.
545
546
547.. c:function:: int PyErr_SetInterruptEx(int signum)
548
549   .. index::
550      module: signal
551      single: KeyboardInterrupt (built-in exception)
552
553   Simulate the effect of a signal arriving. The next time
554   :c:func:`PyErr_CheckSignals` is called,  the Python signal handler for
555   the given signal number will be called.
556
557   This function can be called by C code that sets up its own signal handling
558   and wants Python signal handlers to be invoked as expected when an
559   interruption is requested (for example when the user presses Ctrl-C
560   to interrupt an operation).
561
562   If the given signal isn't handled by Python (it was set to
563   :data:`signal.SIG_DFL` or :data:`signal.SIG_IGN`), it will be ignored.
564
565   If *signum* is outside of the allowed range of signal numbers, ``-1``
566   is returned.  Otherwise, ``0`` is returned.  The error indicator is
567   never changed by this function.
568
569   .. note::
570      This function is async-signal-safe.  It can be called without
571      the :term:`GIL` and from a C signal handler.
572
573   .. versionadded:: 3.10
574
575
576.. c:function:: int PySignal_SetWakeupFd(int fd)
577
578   This utility function specifies a file descriptor to which the signal number
579   is written as a single byte whenever a signal is received. *fd* must be
580   non-blocking. It returns the previous such file descriptor.
581
582   The value ``-1`` disables the feature; this is the initial state.
583   This is equivalent to :func:`signal.set_wakeup_fd` in Python, but without any
584   error checking.  *fd* should be a valid file descriptor.  The function should
585   only be called from the main thread.
586
587   .. versionchanged:: 3.5
588      On Windows, the function now also supports socket handles.
589
590
591Exception Classes
592=================
593
594.. c:function:: PyObject* PyErr_NewException(const char *name, PyObject *base, PyObject *dict)
595
596   This utility function creates and returns a new exception class. The *name*
597   argument must be the name of the new exception, a C string of the form
598   ``module.classname``.  The *base* and *dict* arguments are normally ``NULL``.
599   This creates a class object derived from :exc:`Exception` (accessible in C as
600   :c:data:`PyExc_Exception`).
601
602   The :attr:`__module__` attribute of the new class is set to the first part (up
603   to the last dot) of the *name* argument, and the class name is set to the last
604   part (after the last dot).  The *base* argument can be used to specify alternate
605   base classes; it can either be only one class or a tuple of classes. The *dict*
606   argument can be used to specify a dictionary of class variables and methods.
607
608
609.. c:function:: PyObject* PyErr_NewExceptionWithDoc(const char *name, const char *doc, PyObject *base, PyObject *dict)
610
611   Same as :c:func:`PyErr_NewException`, except that the new exception class can
612   easily be given a docstring: If *doc* is non-``NULL``, it will be used as the
613   docstring for the exception class.
614
615   .. versionadded:: 3.2
616
617
618Exception Objects
619=================
620
621.. c:function:: PyObject* PyException_GetTraceback(PyObject *ex)
622
623   Return the traceback associated with the exception as a new reference, as
624   accessible from Python through :attr:`__traceback__`.  If there is no
625   traceback associated, this returns ``NULL``.
626
627
628.. c:function:: int PyException_SetTraceback(PyObject *ex, PyObject *tb)
629
630   Set the traceback associated with the exception to *tb*.  Use ``Py_None`` to
631   clear it.
632
633
634.. c:function:: PyObject* PyException_GetContext(PyObject *ex)
635
636   Return the context (another exception instance during whose handling *ex* was
637   raised) associated with the exception as a new reference, as accessible from
638   Python through :attr:`__context__`.  If there is no context associated, this
639   returns ``NULL``.
640
641
642.. c:function:: void PyException_SetContext(PyObject *ex, PyObject *ctx)
643
644   Set the context associated with the exception to *ctx*.  Use ``NULL`` to clear
645   it.  There is no type check to make sure that *ctx* is an exception instance.
646   This steals a reference to *ctx*.
647
648
649.. c:function:: PyObject* PyException_GetCause(PyObject *ex)
650
651   Return the cause (either an exception instance, or :const:`None`,
652   set by ``raise ... from ...``) associated with the exception as a new
653   reference, as accessible from Python through :attr:`__cause__`.
654
655
656.. c:function:: void PyException_SetCause(PyObject *ex, PyObject *cause)
657
658   Set the cause associated with the exception to *cause*.  Use ``NULL`` to clear
659   it.  There is no type check to make sure that *cause* is either an exception
660   instance or :const:`None`.  This steals a reference to *cause*.
661
662   :attr:`__suppress_context__` is implicitly set to ``True`` by this function.
663
664
665.. _unicodeexceptions:
666
667Unicode Exception Objects
668=========================
669
670The following functions are used to create and modify Unicode exceptions from C.
671
672.. c:function:: PyObject* PyUnicodeDecodeError_Create(const char *encoding, const char *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
673
674   Create a :class:`UnicodeDecodeError` object with the attributes *encoding*,
675   *object*, *length*, *start*, *end* and *reason*. *encoding* and *reason* are
676   UTF-8 encoded strings.
677
678.. c:function:: PyObject* PyUnicodeEncodeError_Create(const char *encoding, const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
679
680   Create a :class:`UnicodeEncodeError` object with the attributes *encoding*,
681   *object*, *length*, *start*, *end* and *reason*. *encoding* and *reason* are
682   UTF-8 encoded strings.
683
684   .. deprecated:: 3.3 3.11
685
686      ``Py_UNICODE`` is deprecated since Python 3.3. Please migrate to
687      ``PyObject_CallFunction(PyExc_UnicodeEncodeError, "sOnns", ...)``.
688
689.. c:function:: PyObject* PyUnicodeTranslateError_Create(const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
690
691   Create a :class:`UnicodeTranslateError` object with the attributes *object*,
692   *length*, *start*, *end* and *reason*. *reason* is a UTF-8 encoded string.
693
694   .. deprecated:: 3.3 3.11
695
696      ``Py_UNICODE`` is deprecated since Python 3.3. Please migrate to
697      ``PyObject_CallFunction(PyExc_UnicodeTranslateError, "Onns", ...)``.
698
699.. c:function:: PyObject* PyUnicodeDecodeError_GetEncoding(PyObject *exc)
700                PyObject* PyUnicodeEncodeError_GetEncoding(PyObject *exc)
701
702   Return the *encoding* attribute of the given exception object.
703
704.. c:function:: PyObject* PyUnicodeDecodeError_GetObject(PyObject *exc)
705                PyObject* PyUnicodeEncodeError_GetObject(PyObject *exc)
706                PyObject* PyUnicodeTranslateError_GetObject(PyObject *exc)
707
708   Return the *object* attribute of the given exception object.
709
710.. c:function:: int PyUnicodeDecodeError_GetStart(PyObject *exc, Py_ssize_t *start)
711                int PyUnicodeEncodeError_GetStart(PyObject *exc, Py_ssize_t *start)
712                int PyUnicodeTranslateError_GetStart(PyObject *exc, Py_ssize_t *start)
713
714   Get the *start* attribute of the given exception object and place it into
715   *\*start*.  *start* must not be ``NULL``.  Return ``0`` on success, ``-1`` on
716   failure.
717
718.. c:function:: int PyUnicodeDecodeError_SetStart(PyObject *exc, Py_ssize_t start)
719                int PyUnicodeEncodeError_SetStart(PyObject *exc, Py_ssize_t start)
720                int PyUnicodeTranslateError_SetStart(PyObject *exc, Py_ssize_t start)
721
722   Set the *start* attribute of the given exception object to *start*.  Return
723   ``0`` on success, ``-1`` on failure.
724
725.. c:function:: int PyUnicodeDecodeError_GetEnd(PyObject *exc, Py_ssize_t *end)
726                int PyUnicodeEncodeError_GetEnd(PyObject *exc, Py_ssize_t *end)
727                int PyUnicodeTranslateError_GetEnd(PyObject *exc, Py_ssize_t *end)
728
729   Get the *end* attribute of the given exception object and place it into
730   *\*end*.  *end* must not be ``NULL``.  Return ``0`` on success, ``-1`` on
731   failure.
732
733.. c:function:: int PyUnicodeDecodeError_SetEnd(PyObject *exc, Py_ssize_t end)
734                int PyUnicodeEncodeError_SetEnd(PyObject *exc, Py_ssize_t end)
735                int PyUnicodeTranslateError_SetEnd(PyObject *exc, Py_ssize_t end)
736
737   Set the *end* attribute of the given exception object to *end*.  Return ``0``
738   on success, ``-1`` on failure.
739
740.. c:function:: PyObject* PyUnicodeDecodeError_GetReason(PyObject *exc)
741                PyObject* PyUnicodeEncodeError_GetReason(PyObject *exc)
742                PyObject* PyUnicodeTranslateError_GetReason(PyObject *exc)
743
744   Return the *reason* attribute of the given exception object.
745
746.. c:function:: int PyUnicodeDecodeError_SetReason(PyObject *exc, const char *reason)
747                int PyUnicodeEncodeError_SetReason(PyObject *exc, const char *reason)
748                int PyUnicodeTranslateError_SetReason(PyObject *exc, const char *reason)
749
750   Set the *reason* attribute of the given exception object to *reason*.  Return
751   ``0`` on success, ``-1`` on failure.
752
753
754.. _recursion:
755
756Recursion Control
757=================
758
759These two functions provide a way to perform safe recursive calls at the C
760level, both in the core and in extension modules.  They are needed if the
761recursive code does not necessarily invoke Python code (which tracks its
762recursion depth automatically).
763They are also not needed for *tp_call* implementations
764because the :ref:`call protocol <call>` takes care of recursion handling.
765
766.. c:function:: int Py_EnterRecursiveCall(const char *where)
767
768   Marks a point where a recursive C-level call is about to be performed.
769
770   If :const:`USE_STACKCHECK` is defined, this function checks if the OS
771   stack overflowed using :c:func:`PyOS_CheckStack`.  In this is the case, it
772   sets a :exc:`MemoryError` and returns a nonzero value.
773
774   The function then checks if the recursion limit is reached.  If this is the
775   case, a :exc:`RecursionError` is set and a nonzero value is returned.
776   Otherwise, zero is returned.
777
778   *where* should be a UTF-8 encoded string such as ``" in instance check"`` to
779   be concatenated to the :exc:`RecursionError` message caused by the recursion
780   depth limit.
781
782   .. versionchanged:: 3.9
783      This function is now also available in the limited API.
784
785.. c:function:: void Py_LeaveRecursiveCall(void)
786
787   Ends a :c:func:`Py_EnterRecursiveCall`.  Must be called once for each
788   *successful* invocation of :c:func:`Py_EnterRecursiveCall`.
789
790   .. versionchanged:: 3.9
791      This function is now also available in the limited API.
792
793Properly implementing :c:member:`~PyTypeObject.tp_repr` for container types requires
794special recursion handling.  In addition to protecting the stack,
795:c:member:`~PyTypeObject.tp_repr` also needs to track objects to prevent cycles.  The
796following two functions facilitate this functionality.  Effectively,
797these are the C equivalent to :func:`reprlib.recursive_repr`.
798
799.. c:function:: int Py_ReprEnter(PyObject *object)
800
801   Called at the beginning of the :c:member:`~PyTypeObject.tp_repr` implementation to
802   detect cycles.
803
804   If the object has already been processed, the function returns a
805   positive integer.  In that case the :c:member:`~PyTypeObject.tp_repr` implementation
806   should return a string object indicating a cycle.  As examples,
807   :class:`dict` objects return ``{...}`` and :class:`list` objects
808   return ``[...]``.
809
810   The function will return a negative integer if the recursion limit
811   is reached.  In that case the :c:member:`~PyTypeObject.tp_repr` implementation should
812   typically return ``NULL``.
813
814   Otherwise, the function returns zero and the :c:member:`~PyTypeObject.tp_repr`
815   implementation can continue normally.
816
817.. c:function:: void Py_ReprLeave(PyObject *object)
818
819   Ends a :c:func:`Py_ReprEnter`.  Must be called once for each
820   invocation of :c:func:`Py_ReprEnter` that returns zero.
821
822
823.. _standardexceptions:
824
825Standard Exceptions
826===================
827
828All standard Python exceptions are available as global variables whose names are
829``PyExc_`` followed by the Python exception name.  These have the type
830:c:type:`PyObject*`; they are all class objects.  For completeness, here are all
831the variables:
832
833.. index::
834   single: PyExc_BaseException
835   single: PyExc_Exception
836   single: PyExc_ArithmeticError
837   single: PyExc_AssertionError
838   single: PyExc_AttributeError
839   single: PyExc_BlockingIOError
840   single: PyExc_BrokenPipeError
841   single: PyExc_BufferError
842   single: PyExc_ChildProcessError
843   single: PyExc_ConnectionAbortedError
844   single: PyExc_ConnectionError
845   single: PyExc_ConnectionRefusedError
846   single: PyExc_ConnectionResetError
847   single: PyExc_EOFError
848   single: PyExc_FileExistsError
849   single: PyExc_FileNotFoundError
850   single: PyExc_FloatingPointError
851   single: PyExc_GeneratorExit
852   single: PyExc_ImportError
853   single: PyExc_IndentationError
854   single: PyExc_IndexError
855   single: PyExc_InterruptedError
856   single: PyExc_IsADirectoryError
857   single: PyExc_KeyError
858   single: PyExc_KeyboardInterrupt
859   single: PyExc_LookupError
860   single: PyExc_MemoryError
861   single: PyExc_ModuleNotFoundError
862   single: PyExc_NameError
863   single: PyExc_NotADirectoryError
864   single: PyExc_NotImplementedError
865   single: PyExc_OSError
866   single: PyExc_OverflowError
867   single: PyExc_PermissionError
868   single: PyExc_ProcessLookupError
869   single: PyExc_RecursionError
870   single: PyExc_ReferenceError
871   single: PyExc_RuntimeError
872   single: PyExc_StopAsyncIteration
873   single: PyExc_StopIteration
874   single: PyExc_SyntaxError
875   single: PyExc_SystemError
876   single: PyExc_SystemExit
877   single: PyExc_TabError
878   single: PyExc_TimeoutError
879   single: PyExc_TypeError
880   single: PyExc_UnboundLocalError
881   single: PyExc_UnicodeDecodeError
882   single: PyExc_UnicodeEncodeError
883   single: PyExc_UnicodeError
884   single: PyExc_UnicodeTranslateError
885   single: PyExc_ValueError
886   single: PyExc_ZeroDivisionError
887
888+-----------------------------------------+---------------------------------+----------+
889| C Name                                  | Python Name                     | Notes    |
890+=========================================+=================================+==========+
891| :c:data:`PyExc_BaseException`           | :exc:`BaseException`            | \(1)     |
892+-----------------------------------------+---------------------------------+----------+
893| :c:data:`PyExc_Exception`               | :exc:`Exception`                | \(1)     |
894+-----------------------------------------+---------------------------------+----------+
895| :c:data:`PyExc_ArithmeticError`         | :exc:`ArithmeticError`          | \(1)     |
896+-----------------------------------------+---------------------------------+----------+
897| :c:data:`PyExc_AssertionError`          | :exc:`AssertionError`           |          |
898+-----------------------------------------+---------------------------------+----------+
899| :c:data:`PyExc_AttributeError`          | :exc:`AttributeError`           |          |
900+-----------------------------------------+---------------------------------+----------+
901| :c:data:`PyExc_BlockingIOError`         | :exc:`BlockingIOError`          |          |
902+-----------------------------------------+---------------------------------+----------+
903| :c:data:`PyExc_BrokenPipeError`         | :exc:`BrokenPipeError`          |          |
904+-----------------------------------------+---------------------------------+----------+
905| :c:data:`PyExc_BufferError`             | :exc:`BufferError`              |          |
906+-----------------------------------------+---------------------------------+----------+
907| :c:data:`PyExc_ChildProcessError`       | :exc:`ChildProcessError`        |          |
908+-----------------------------------------+---------------------------------+----------+
909| :c:data:`PyExc_ConnectionAbortedError`  | :exc:`ConnectionAbortedError`   |          |
910+-----------------------------------------+---------------------------------+----------+
911| :c:data:`PyExc_ConnectionError`         | :exc:`ConnectionError`          |          |
912+-----------------------------------------+---------------------------------+----------+
913| :c:data:`PyExc_ConnectionRefusedError`  | :exc:`ConnectionRefusedError`   |          |
914+-----------------------------------------+---------------------------------+----------+
915| :c:data:`PyExc_ConnectionResetError`    | :exc:`ConnectionResetError`     |          |
916+-----------------------------------------+---------------------------------+----------+
917| :c:data:`PyExc_EOFError`                | :exc:`EOFError`                 |          |
918+-----------------------------------------+---------------------------------+----------+
919| :c:data:`PyExc_FileExistsError`         | :exc:`FileExistsError`          |          |
920+-----------------------------------------+---------------------------------+----------+
921| :c:data:`PyExc_FileNotFoundError`       | :exc:`FileNotFoundError`        |          |
922+-----------------------------------------+---------------------------------+----------+
923| :c:data:`PyExc_FloatingPointError`      | :exc:`FloatingPointError`       |          |
924+-----------------------------------------+---------------------------------+----------+
925| :c:data:`PyExc_GeneratorExit`           | :exc:`GeneratorExit`            |          |
926+-----------------------------------------+---------------------------------+----------+
927| :c:data:`PyExc_ImportError`             | :exc:`ImportError`              |          |
928+-----------------------------------------+---------------------------------+----------+
929| :c:data:`PyExc_IndentationError`        | :exc:`IndentationError`         |          |
930+-----------------------------------------+---------------------------------+----------+
931| :c:data:`PyExc_IndexError`              | :exc:`IndexError`               |          |
932+-----------------------------------------+---------------------------------+----------+
933| :c:data:`PyExc_InterruptedError`        | :exc:`InterruptedError`         |          |
934+-----------------------------------------+---------------------------------+----------+
935| :c:data:`PyExc_IsADirectoryError`       | :exc:`IsADirectoryError`        |          |
936+-----------------------------------------+---------------------------------+----------+
937| :c:data:`PyExc_KeyError`                | :exc:`KeyError`                 |          |
938+-----------------------------------------+---------------------------------+----------+
939| :c:data:`PyExc_KeyboardInterrupt`       | :exc:`KeyboardInterrupt`        |          |
940+-----------------------------------------+---------------------------------+----------+
941| :c:data:`PyExc_LookupError`             | :exc:`LookupError`              | \(1)     |
942+-----------------------------------------+---------------------------------+----------+
943| :c:data:`PyExc_MemoryError`             | :exc:`MemoryError`              |          |
944+-----------------------------------------+---------------------------------+----------+
945| :c:data:`PyExc_ModuleNotFoundError`     | :exc:`ModuleNotFoundError`      |          |
946+-----------------------------------------+---------------------------------+----------+
947| :c:data:`PyExc_NameError`               | :exc:`NameError`                |          |
948+-----------------------------------------+---------------------------------+----------+
949| :c:data:`PyExc_NotADirectoryError`      | :exc:`NotADirectoryError`       |          |
950+-----------------------------------------+---------------------------------+----------+
951| :c:data:`PyExc_NotImplementedError`     | :exc:`NotImplementedError`      |          |
952+-----------------------------------------+---------------------------------+----------+
953| :c:data:`PyExc_OSError`                 | :exc:`OSError`                  | \(1)     |
954+-----------------------------------------+---------------------------------+----------+
955| :c:data:`PyExc_OverflowError`           | :exc:`OverflowError`            |          |
956+-----------------------------------------+---------------------------------+----------+
957| :c:data:`PyExc_PermissionError`         | :exc:`PermissionError`          |          |
958+-----------------------------------------+---------------------------------+----------+
959| :c:data:`PyExc_ProcessLookupError`      | :exc:`ProcessLookupError`       |          |
960+-----------------------------------------+---------------------------------+----------+
961| :c:data:`PyExc_RecursionError`          | :exc:`RecursionError`           |          |
962+-----------------------------------------+---------------------------------+----------+
963| :c:data:`PyExc_ReferenceError`          | :exc:`ReferenceError`           | \(2)     |
964+-----------------------------------------+---------------------------------+----------+
965| :c:data:`PyExc_RuntimeError`            | :exc:`RuntimeError`             |          |
966+-----------------------------------------+---------------------------------+----------+
967| :c:data:`PyExc_StopAsyncIteration`      | :exc:`StopAsyncIteration`       |          |
968+-----------------------------------------+---------------------------------+----------+
969| :c:data:`PyExc_StopIteration`           | :exc:`StopIteration`            |          |
970+-----------------------------------------+---------------------------------+----------+
971| :c:data:`PyExc_SyntaxError`             | :exc:`SyntaxError`              |          |
972+-----------------------------------------+---------------------------------+----------+
973| :c:data:`PyExc_SystemError`             | :exc:`SystemError`              |          |
974+-----------------------------------------+---------------------------------+----------+
975| :c:data:`PyExc_SystemExit`              | :exc:`SystemExit`               |          |
976+-----------------------------------------+---------------------------------+----------+
977| :c:data:`PyExc_TabError`                | :exc:`TabError`                 |          |
978+-----------------------------------------+---------------------------------+----------+
979| :c:data:`PyExc_TimeoutError`            | :exc:`TimeoutError`             |          |
980+-----------------------------------------+---------------------------------+----------+
981| :c:data:`PyExc_TypeError`               | :exc:`TypeError`                |          |
982+-----------------------------------------+---------------------------------+----------+
983| :c:data:`PyExc_UnboundLocalError`       | :exc:`UnboundLocalError`        |          |
984+-----------------------------------------+---------------------------------+----------+
985| :c:data:`PyExc_UnicodeDecodeError`      | :exc:`UnicodeDecodeError`       |          |
986+-----------------------------------------+---------------------------------+----------+
987| :c:data:`PyExc_UnicodeEncodeError`      | :exc:`UnicodeEncodeError`       |          |
988+-----------------------------------------+---------------------------------+----------+
989| :c:data:`PyExc_UnicodeError`            | :exc:`UnicodeError`             |          |
990+-----------------------------------------+---------------------------------+----------+
991| :c:data:`PyExc_UnicodeTranslateError`   | :exc:`UnicodeTranslateError`    |          |
992+-----------------------------------------+---------------------------------+----------+
993| :c:data:`PyExc_ValueError`              | :exc:`ValueError`               |          |
994+-----------------------------------------+---------------------------------+----------+
995| :c:data:`PyExc_ZeroDivisionError`       | :exc:`ZeroDivisionError`        |          |
996+-----------------------------------------+---------------------------------+----------+
997
998.. versionadded:: 3.3
999   :c:data:`PyExc_BlockingIOError`, :c:data:`PyExc_BrokenPipeError`,
1000   :c:data:`PyExc_ChildProcessError`, :c:data:`PyExc_ConnectionError`,
1001   :c:data:`PyExc_ConnectionAbortedError`, :c:data:`PyExc_ConnectionRefusedError`,
1002   :c:data:`PyExc_ConnectionResetError`, :c:data:`PyExc_FileExistsError`,
1003   :c:data:`PyExc_FileNotFoundError`, :c:data:`PyExc_InterruptedError`,
1004   :c:data:`PyExc_IsADirectoryError`, :c:data:`PyExc_NotADirectoryError`,
1005   :c:data:`PyExc_PermissionError`, :c:data:`PyExc_ProcessLookupError`
1006   and :c:data:`PyExc_TimeoutError` were introduced following :pep:`3151`.
1007
1008.. versionadded:: 3.5
1009   :c:data:`PyExc_StopAsyncIteration` and :c:data:`PyExc_RecursionError`.
1010
1011.. versionadded:: 3.6
1012   :c:data:`PyExc_ModuleNotFoundError`.
1013
1014These are compatibility aliases to :c:data:`PyExc_OSError`:
1015
1016.. index::
1017   single: PyExc_EnvironmentError
1018   single: PyExc_IOError
1019   single: PyExc_WindowsError
1020
1021+-------------------------------------+----------+
1022| C Name                              | Notes    |
1023+=====================================+==========+
1024| :c:data:`PyExc_EnvironmentError`    |          |
1025+-------------------------------------+----------+
1026| :c:data:`PyExc_IOError`             |          |
1027+-------------------------------------+----------+
1028| :c:data:`PyExc_WindowsError`        | \(3)     |
1029+-------------------------------------+----------+
1030
1031.. versionchanged:: 3.3
1032   These aliases used to be separate exception types.
1033
1034Notes:
1035
1036(1)
1037   This is a base class for other standard exceptions.
1038
1039(2)
1040   Only defined on Windows; protect code that uses this by testing that the
1041   preprocessor macro ``MS_WINDOWS`` is defined.
1042
1043.. _standardwarningcategories:
1044
1045Standard Warning Categories
1046===========================
1047
1048All standard Python warning categories are available as global variables whose
1049names are ``PyExc_`` followed by the Python exception name. These have the type
1050:c:type:`PyObject*`; they are all class objects. For completeness, here are all
1051the variables:
1052
1053.. index::
1054   single: PyExc_Warning
1055   single: PyExc_BytesWarning
1056   single: PyExc_DeprecationWarning
1057   single: PyExc_FutureWarning
1058   single: PyExc_ImportWarning
1059   single: PyExc_PendingDeprecationWarning
1060   single: PyExc_ResourceWarning
1061   single: PyExc_RuntimeWarning
1062   single: PyExc_SyntaxWarning
1063   single: PyExc_UnicodeWarning
1064   single: PyExc_UserWarning
1065
1066+------------------------------------------+---------------------------------+----------+
1067| C Name                                   | Python Name                     | Notes    |
1068+==========================================+=================================+==========+
1069| :c:data:`PyExc_Warning`                  | :exc:`Warning`                  | \(1)     |
1070+------------------------------------------+---------------------------------+----------+
1071| :c:data:`PyExc_BytesWarning`             | :exc:`BytesWarning`             |          |
1072+------------------------------------------+---------------------------------+----------+
1073| :c:data:`PyExc_DeprecationWarning`       | :exc:`DeprecationWarning`       |          |
1074+------------------------------------------+---------------------------------+----------+
1075| :c:data:`PyExc_FutureWarning`            | :exc:`FutureWarning`            |          |
1076+------------------------------------------+---------------------------------+----------+
1077| :c:data:`PyExc_ImportWarning`            | :exc:`ImportWarning`            |          |
1078+------------------------------------------+---------------------------------+----------+
1079| :c:data:`PyExc_PendingDeprecationWarning`| :exc:`PendingDeprecationWarning`|          |
1080+------------------------------------------+---------------------------------+----------+
1081| :c:data:`PyExc_ResourceWarning`          | :exc:`ResourceWarning`          |          |
1082+------------------------------------------+---------------------------------+----------+
1083| :c:data:`PyExc_RuntimeWarning`           | :exc:`RuntimeWarning`           |          |
1084+------------------------------------------+---------------------------------+----------+
1085| :c:data:`PyExc_SyntaxWarning`            | :exc:`SyntaxWarning`            |          |
1086+------------------------------------------+---------------------------------+----------+
1087| :c:data:`PyExc_UnicodeWarning`           | :exc:`UnicodeWarning`           |          |
1088+------------------------------------------+---------------------------------+----------+
1089| :c:data:`PyExc_UserWarning`              | :exc:`UserWarning`              |          |
1090+------------------------------------------+---------------------------------+----------+
1091
1092.. versionadded:: 3.2
1093   :c:data:`PyExc_ResourceWarning`.
1094
1095Notes:
1096
1097(1)
1098   This is a base class for other standard warning categories.
1099