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 filesystem encoding
186   (:func:`os.fsdecode`).
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 filesystem encoding (:func:`os.fsdecode`).
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   filesystem encoding (:func:`os.fsdecode`).
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.  It checks whether a
509   signal has been sent to the processes and if so, invokes the corresponding
510   signal handler.  If the :mod:`signal` module is supported, this can invoke a
511   signal handler written in Python.  In all cases, the default effect for
512   :const:`SIGINT` is to raise the  :exc:`KeyboardInterrupt` exception.  If an
513   exception is raised the error indicator is set and the function returns ``-1``;
514   otherwise the function returns ``0``.  The error indicator may or may not be
515   cleared if it was previously set.
516
517
518.. c:function:: void PyErr_SetInterrupt()
519
520   .. index::
521      single: SIGINT
522      single: KeyboardInterrupt (built-in exception)
523
524   Simulate the effect of a :const:`SIGINT` signal arriving. The next time
525   :c:func:`PyErr_CheckSignals` is called,  the Python signal handler for
526   :const:`SIGINT` will be called.
527
528   If :const:`SIGINT` isn't handled by Python (it was set to
529   :data:`signal.SIG_DFL` or :data:`signal.SIG_IGN`), this function does
530   nothing.
531
532.. c:function:: int PySignal_SetWakeupFd(int fd)
533
534   This utility function specifies a file descriptor to which the signal number
535   is written as a single byte whenever a signal is received. *fd* must be
536   non-blocking. It returns the previous such file descriptor.
537
538   The value ``-1`` disables the feature; this is the initial state.
539   This is equivalent to :func:`signal.set_wakeup_fd` in Python, but without any
540   error checking.  *fd* should be a valid file descriptor.  The function should
541   only be called from the main thread.
542
543   .. versionchanged:: 3.5
544      On Windows, the function now also supports socket handles.
545
546
547Exception Classes
548=================
549
550.. c:function:: PyObject* PyErr_NewException(const char *name, PyObject *base, PyObject *dict)
551
552   This utility function creates and returns a new exception class. The *name*
553   argument must be the name of the new exception, a C string of the form
554   ``module.classname``.  The *base* and *dict* arguments are normally ``NULL``.
555   This creates a class object derived from :exc:`Exception` (accessible in C as
556   :c:data:`PyExc_Exception`).
557
558   The :attr:`__module__` attribute of the new class is set to the first part (up
559   to the last dot) of the *name* argument, and the class name is set to the last
560   part (after the last dot).  The *base* argument can be used to specify alternate
561   base classes; it can either be only one class or a tuple of classes. The *dict*
562   argument can be used to specify a dictionary of class variables and methods.
563
564
565.. c:function:: PyObject* PyErr_NewExceptionWithDoc(const char *name, const char *doc, PyObject *base, PyObject *dict)
566
567   Same as :c:func:`PyErr_NewException`, except that the new exception class can
568   easily be given a docstring: If *doc* is non-``NULL``, it will be used as the
569   docstring for the exception class.
570
571   .. versionadded:: 3.2
572
573
574Exception Objects
575=================
576
577.. c:function:: PyObject* PyException_GetTraceback(PyObject *ex)
578
579   Return the traceback associated with the exception as a new reference, as
580   accessible from Python through :attr:`__traceback__`.  If there is no
581   traceback associated, this returns ``NULL``.
582
583
584.. c:function:: int PyException_SetTraceback(PyObject *ex, PyObject *tb)
585
586   Set the traceback associated with the exception to *tb*.  Use ``Py_None`` to
587   clear it.
588
589
590.. c:function:: PyObject* PyException_GetContext(PyObject *ex)
591
592   Return the context (another exception instance during whose handling *ex* was
593   raised) associated with the exception as a new reference, as accessible from
594   Python through :attr:`__context__`.  If there is no context associated, this
595   returns ``NULL``.
596
597
598.. c:function:: void PyException_SetContext(PyObject *ex, PyObject *ctx)
599
600   Set the context associated with the exception to *ctx*.  Use ``NULL`` to clear
601   it.  There is no type check to make sure that *ctx* is an exception instance.
602   This steals a reference to *ctx*.
603
604
605.. c:function:: PyObject* PyException_GetCause(PyObject *ex)
606
607   Return the cause (either an exception instance, or :const:`None`,
608   set by ``raise ... from ...``) associated with the exception as a new
609   reference, as accessible from Python through :attr:`__cause__`.
610
611
612.. c:function:: void PyException_SetCause(PyObject *ex, PyObject *cause)
613
614   Set the cause associated with the exception to *cause*.  Use ``NULL`` to clear
615   it.  There is no type check to make sure that *cause* is either an exception
616   instance or :const:`None`.  This steals a reference to *cause*.
617
618   :attr:`__suppress_context__` is implicitly set to ``True`` by this function.
619
620
621.. _unicodeexceptions:
622
623Unicode Exception Objects
624=========================
625
626The following functions are used to create and modify Unicode exceptions from C.
627
628.. 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)
629
630   Create a :class:`UnicodeDecodeError` object with the attributes *encoding*,
631   *object*, *length*, *start*, *end* and *reason*. *encoding* and *reason* are
632   UTF-8 encoded strings.
633
634.. 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)
635
636   Create a :class:`UnicodeEncodeError` object with the attributes *encoding*,
637   *object*, *length*, *start*, *end* and *reason*. *encoding* and *reason* are
638   UTF-8 encoded strings.
639
640   .. deprecated:: 3.3 3.11
641
642      ``Py_UNICODE`` is deprecated since Python 3.3. Please migrate to
643      ``PyObject_CallFunction(PyExc_UnicodeEncodeError, "sOnns", ...)``.
644
645.. c:function:: PyObject* PyUnicodeTranslateError_Create(const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
646
647   Create a :class:`UnicodeTranslateError` object with the attributes *object*,
648   *length*, *start*, *end* and *reason*. *reason* is a UTF-8 encoded string.
649
650   .. deprecated:: 3.3 3.11
651
652      ``Py_UNICODE`` is deprecated since Python 3.3. Please migrate to
653      ``PyObject_CallFunction(PyExc_UnicodeTranslateError, "Onns", ...)``.
654
655.. c:function:: PyObject* PyUnicodeDecodeError_GetEncoding(PyObject *exc)
656                PyObject* PyUnicodeEncodeError_GetEncoding(PyObject *exc)
657
658   Return the *encoding* attribute of the given exception object.
659
660.. c:function:: PyObject* PyUnicodeDecodeError_GetObject(PyObject *exc)
661                PyObject* PyUnicodeEncodeError_GetObject(PyObject *exc)
662                PyObject* PyUnicodeTranslateError_GetObject(PyObject *exc)
663
664   Return the *object* attribute of the given exception object.
665
666.. c:function:: int PyUnicodeDecodeError_GetStart(PyObject *exc, Py_ssize_t *start)
667                int PyUnicodeEncodeError_GetStart(PyObject *exc, Py_ssize_t *start)
668                int PyUnicodeTranslateError_GetStart(PyObject *exc, Py_ssize_t *start)
669
670   Get the *start* attribute of the given exception object and place it into
671   *\*start*.  *start* must not be ``NULL``.  Return ``0`` on success, ``-1`` on
672   failure.
673
674.. c:function:: int PyUnicodeDecodeError_SetStart(PyObject *exc, Py_ssize_t start)
675                int PyUnicodeEncodeError_SetStart(PyObject *exc, Py_ssize_t start)
676                int PyUnicodeTranslateError_SetStart(PyObject *exc, Py_ssize_t start)
677
678   Set the *start* attribute of the given exception object to *start*.  Return
679   ``0`` on success, ``-1`` on failure.
680
681.. c:function:: int PyUnicodeDecodeError_GetEnd(PyObject *exc, Py_ssize_t *end)
682                int PyUnicodeEncodeError_GetEnd(PyObject *exc, Py_ssize_t *end)
683                int PyUnicodeTranslateError_GetEnd(PyObject *exc, Py_ssize_t *end)
684
685   Get the *end* attribute of the given exception object and place it into
686   *\*end*.  *end* must not be ``NULL``.  Return ``0`` on success, ``-1`` on
687   failure.
688
689.. c:function:: int PyUnicodeDecodeError_SetEnd(PyObject *exc, Py_ssize_t end)
690                int PyUnicodeEncodeError_SetEnd(PyObject *exc, Py_ssize_t end)
691                int PyUnicodeTranslateError_SetEnd(PyObject *exc, Py_ssize_t end)
692
693   Set the *end* attribute of the given exception object to *end*.  Return ``0``
694   on success, ``-1`` on failure.
695
696.. c:function:: PyObject* PyUnicodeDecodeError_GetReason(PyObject *exc)
697                PyObject* PyUnicodeEncodeError_GetReason(PyObject *exc)
698                PyObject* PyUnicodeTranslateError_GetReason(PyObject *exc)
699
700   Return the *reason* attribute of the given exception object.
701
702.. c:function:: int PyUnicodeDecodeError_SetReason(PyObject *exc, const char *reason)
703                int PyUnicodeEncodeError_SetReason(PyObject *exc, const char *reason)
704                int PyUnicodeTranslateError_SetReason(PyObject *exc, const char *reason)
705
706   Set the *reason* attribute of the given exception object to *reason*.  Return
707   ``0`` on success, ``-1`` on failure.
708
709
710.. _recursion:
711
712Recursion Control
713=================
714
715These two functions provide a way to perform safe recursive calls at the C
716level, both in the core and in extension modules.  They are needed if the
717recursive code does not necessarily invoke Python code (which tracks its
718recursion depth automatically).
719They are also not needed for *tp_call* implementations
720because the :ref:`call protocol <call>` takes care of recursion handling.
721
722.. c:function:: int Py_EnterRecursiveCall(const char *where)
723
724   Marks a point where a recursive C-level call is about to be performed.
725
726   If :const:`USE_STACKCHECK` is defined, this function checks if the OS
727   stack overflowed using :c:func:`PyOS_CheckStack`.  In this is the case, it
728   sets a :exc:`MemoryError` and returns a nonzero value.
729
730   The function then checks if the recursion limit is reached.  If this is the
731   case, a :exc:`RecursionError` is set and a nonzero value is returned.
732   Otherwise, zero is returned.
733
734   *where* should be a UTF-8 encoded string such as ``" in instance check"`` to
735   be concatenated to the :exc:`RecursionError` message caused by the recursion
736   depth limit.
737
738   .. versionchanged:: 3.9
739      This function is now also available in the limited API.
740
741.. c:function:: void Py_LeaveRecursiveCall(void)
742
743   Ends a :c:func:`Py_EnterRecursiveCall`.  Must be called once for each
744   *successful* invocation of :c:func:`Py_EnterRecursiveCall`.
745
746   .. versionchanged:: 3.9
747      This function is now also available in the limited API.
748
749Properly implementing :c:member:`~PyTypeObject.tp_repr` for container types requires
750special recursion handling.  In addition to protecting the stack,
751:c:member:`~PyTypeObject.tp_repr` also needs to track objects to prevent cycles.  The
752following two functions facilitate this functionality.  Effectively,
753these are the C equivalent to :func:`reprlib.recursive_repr`.
754
755.. c:function:: int Py_ReprEnter(PyObject *object)
756
757   Called at the beginning of the :c:member:`~PyTypeObject.tp_repr` implementation to
758   detect cycles.
759
760   If the object has already been processed, the function returns a
761   positive integer.  In that case the :c:member:`~PyTypeObject.tp_repr` implementation
762   should return a string object indicating a cycle.  As examples,
763   :class:`dict` objects return ``{...}`` and :class:`list` objects
764   return ``[...]``.
765
766   The function will return a negative integer if the recursion limit
767   is reached.  In that case the :c:member:`~PyTypeObject.tp_repr` implementation should
768   typically return ``NULL``.
769
770   Otherwise, the function returns zero and the :c:member:`~PyTypeObject.tp_repr`
771   implementation can continue normally.
772
773.. c:function:: void Py_ReprLeave(PyObject *object)
774
775   Ends a :c:func:`Py_ReprEnter`.  Must be called once for each
776   invocation of :c:func:`Py_ReprEnter` that returns zero.
777
778
779.. _standardexceptions:
780
781Standard Exceptions
782===================
783
784All standard Python exceptions are available as global variables whose names are
785``PyExc_`` followed by the Python exception name.  These have the type
786:c:type:`PyObject*`; they are all class objects.  For completeness, here are all
787the variables:
788
789.. index::
790   single: PyExc_BaseException
791   single: PyExc_Exception
792   single: PyExc_ArithmeticError
793   single: PyExc_AssertionError
794   single: PyExc_AttributeError
795   single: PyExc_BlockingIOError
796   single: PyExc_BrokenPipeError
797   single: PyExc_BufferError
798   single: PyExc_ChildProcessError
799   single: PyExc_ConnectionAbortedError
800   single: PyExc_ConnectionError
801   single: PyExc_ConnectionRefusedError
802   single: PyExc_ConnectionResetError
803   single: PyExc_EOFError
804   single: PyExc_FileExistsError
805   single: PyExc_FileNotFoundError
806   single: PyExc_FloatingPointError
807   single: PyExc_GeneratorExit
808   single: PyExc_ImportError
809   single: PyExc_IndentationError
810   single: PyExc_IndexError
811   single: PyExc_InterruptedError
812   single: PyExc_IsADirectoryError
813   single: PyExc_KeyError
814   single: PyExc_KeyboardInterrupt
815   single: PyExc_LookupError
816   single: PyExc_MemoryError
817   single: PyExc_ModuleNotFoundError
818   single: PyExc_NameError
819   single: PyExc_NotADirectoryError
820   single: PyExc_NotImplementedError
821   single: PyExc_OSError
822   single: PyExc_OverflowError
823   single: PyExc_PermissionError
824   single: PyExc_ProcessLookupError
825   single: PyExc_RecursionError
826   single: PyExc_ReferenceError
827   single: PyExc_RuntimeError
828   single: PyExc_StopAsyncIteration
829   single: PyExc_StopIteration
830   single: PyExc_SyntaxError
831   single: PyExc_SystemError
832   single: PyExc_SystemExit
833   single: PyExc_TabError
834   single: PyExc_TimeoutError
835   single: PyExc_TypeError
836   single: PyExc_UnboundLocalError
837   single: PyExc_UnicodeDecodeError
838   single: PyExc_UnicodeEncodeError
839   single: PyExc_UnicodeError
840   single: PyExc_UnicodeTranslateError
841   single: PyExc_ValueError
842   single: PyExc_ZeroDivisionError
843
844+-----------------------------------------+---------------------------------+----------+
845| C Name                                  | Python Name                     | Notes    |
846+=========================================+=================================+==========+
847| :c:data:`PyExc_BaseException`           | :exc:`BaseException`            | \(1)     |
848+-----------------------------------------+---------------------------------+----------+
849| :c:data:`PyExc_Exception`               | :exc:`Exception`                | \(1)     |
850+-----------------------------------------+---------------------------------+----------+
851| :c:data:`PyExc_ArithmeticError`         | :exc:`ArithmeticError`          | \(1)     |
852+-----------------------------------------+---------------------------------+----------+
853| :c:data:`PyExc_AssertionError`          | :exc:`AssertionError`           |          |
854+-----------------------------------------+---------------------------------+----------+
855| :c:data:`PyExc_AttributeError`          | :exc:`AttributeError`           |          |
856+-----------------------------------------+---------------------------------+----------+
857| :c:data:`PyExc_BlockingIOError`         | :exc:`BlockingIOError`          |          |
858+-----------------------------------------+---------------------------------+----------+
859| :c:data:`PyExc_BrokenPipeError`         | :exc:`BrokenPipeError`          |          |
860+-----------------------------------------+---------------------------------+----------+
861| :c:data:`PyExc_BufferError`             | :exc:`BufferError`              |          |
862+-----------------------------------------+---------------------------------+----------+
863| :c:data:`PyExc_ChildProcessError`       | :exc:`ChildProcessError`        |          |
864+-----------------------------------------+---------------------------------+----------+
865| :c:data:`PyExc_ConnectionAbortedError`  | :exc:`ConnectionAbortedError`   |          |
866+-----------------------------------------+---------------------------------+----------+
867| :c:data:`PyExc_ConnectionError`         | :exc:`ConnectionError`          |          |
868+-----------------------------------------+---------------------------------+----------+
869| :c:data:`PyExc_ConnectionRefusedError`  | :exc:`ConnectionRefusedError`   |          |
870+-----------------------------------------+---------------------------------+----------+
871| :c:data:`PyExc_ConnectionResetError`    | :exc:`ConnectionResetError`     |          |
872+-----------------------------------------+---------------------------------+----------+
873| :c:data:`PyExc_EOFError`                | :exc:`EOFError`                 |          |
874+-----------------------------------------+---------------------------------+----------+
875| :c:data:`PyExc_FileExistsError`         | :exc:`FileExistsError`          |          |
876+-----------------------------------------+---------------------------------+----------+
877| :c:data:`PyExc_FileNotFoundError`       | :exc:`FileNotFoundError`        |          |
878+-----------------------------------------+---------------------------------+----------+
879| :c:data:`PyExc_FloatingPointError`      | :exc:`FloatingPointError`       |          |
880+-----------------------------------------+---------------------------------+----------+
881| :c:data:`PyExc_GeneratorExit`           | :exc:`GeneratorExit`            |          |
882+-----------------------------------------+---------------------------------+----------+
883| :c:data:`PyExc_ImportError`             | :exc:`ImportError`              |          |
884+-----------------------------------------+---------------------------------+----------+
885| :c:data:`PyExc_IndentationError`        | :exc:`IndentationError`         |          |
886+-----------------------------------------+---------------------------------+----------+
887| :c:data:`PyExc_IndexError`              | :exc:`IndexError`               |          |
888+-----------------------------------------+---------------------------------+----------+
889| :c:data:`PyExc_InterruptedError`        | :exc:`InterruptedError`         |          |
890+-----------------------------------------+---------------------------------+----------+
891| :c:data:`PyExc_IsADirectoryError`       | :exc:`IsADirectoryError`        |          |
892+-----------------------------------------+---------------------------------+----------+
893| :c:data:`PyExc_KeyError`                | :exc:`KeyError`                 |          |
894+-----------------------------------------+---------------------------------+----------+
895| :c:data:`PyExc_KeyboardInterrupt`       | :exc:`KeyboardInterrupt`        |          |
896+-----------------------------------------+---------------------------------+----------+
897| :c:data:`PyExc_LookupError`             | :exc:`LookupError`              | \(1)     |
898+-----------------------------------------+---------------------------------+----------+
899| :c:data:`PyExc_MemoryError`             | :exc:`MemoryError`              |          |
900+-----------------------------------------+---------------------------------+----------+
901| :c:data:`PyExc_ModuleNotFoundError`     | :exc:`ModuleNotFoundError`      |          |
902+-----------------------------------------+---------------------------------+----------+
903| :c:data:`PyExc_NameError`               | :exc:`NameError`                |          |
904+-----------------------------------------+---------------------------------+----------+
905| :c:data:`PyExc_NotADirectoryError`      | :exc:`NotADirectoryError`       |          |
906+-----------------------------------------+---------------------------------+----------+
907| :c:data:`PyExc_NotImplementedError`     | :exc:`NotImplementedError`      |          |
908+-----------------------------------------+---------------------------------+----------+
909| :c:data:`PyExc_OSError`                 | :exc:`OSError`                  | \(1)     |
910+-----------------------------------------+---------------------------------+----------+
911| :c:data:`PyExc_OverflowError`           | :exc:`OverflowError`            |          |
912+-----------------------------------------+---------------------------------+----------+
913| :c:data:`PyExc_PermissionError`         | :exc:`PermissionError`          |          |
914+-----------------------------------------+---------------------------------+----------+
915| :c:data:`PyExc_ProcessLookupError`      | :exc:`ProcessLookupError`       |          |
916+-----------------------------------------+---------------------------------+----------+
917| :c:data:`PyExc_RecursionError`          | :exc:`RecursionError`           |          |
918+-----------------------------------------+---------------------------------+----------+
919| :c:data:`PyExc_ReferenceError`          | :exc:`ReferenceError`           | \(2)     |
920+-----------------------------------------+---------------------------------+----------+
921| :c:data:`PyExc_RuntimeError`            | :exc:`RuntimeError`             |          |
922+-----------------------------------------+---------------------------------+----------+
923| :c:data:`PyExc_StopAsyncIteration`      | :exc:`StopAsyncIteration`       |          |
924+-----------------------------------------+---------------------------------+----------+
925| :c:data:`PyExc_StopIteration`           | :exc:`StopIteration`            |          |
926+-----------------------------------------+---------------------------------+----------+
927| :c:data:`PyExc_SyntaxError`             | :exc:`SyntaxError`              |          |
928+-----------------------------------------+---------------------------------+----------+
929| :c:data:`PyExc_SystemError`             | :exc:`SystemError`              |          |
930+-----------------------------------------+---------------------------------+----------+
931| :c:data:`PyExc_SystemExit`              | :exc:`SystemExit`               |          |
932+-----------------------------------------+---------------------------------+----------+
933| :c:data:`PyExc_TabError`                | :exc:`TabError`                 |          |
934+-----------------------------------------+---------------------------------+----------+
935| :c:data:`PyExc_TimeoutError`            | :exc:`TimeoutError`             |          |
936+-----------------------------------------+---------------------------------+----------+
937| :c:data:`PyExc_TypeError`               | :exc:`TypeError`                |          |
938+-----------------------------------------+---------------------------------+----------+
939| :c:data:`PyExc_UnboundLocalError`       | :exc:`UnboundLocalError`        |          |
940+-----------------------------------------+---------------------------------+----------+
941| :c:data:`PyExc_UnicodeDecodeError`      | :exc:`UnicodeDecodeError`       |          |
942+-----------------------------------------+---------------------------------+----------+
943| :c:data:`PyExc_UnicodeEncodeError`      | :exc:`UnicodeEncodeError`       |          |
944+-----------------------------------------+---------------------------------+----------+
945| :c:data:`PyExc_UnicodeError`            | :exc:`UnicodeError`             |          |
946+-----------------------------------------+---------------------------------+----------+
947| :c:data:`PyExc_UnicodeTranslateError`   | :exc:`UnicodeTranslateError`    |          |
948+-----------------------------------------+---------------------------------+----------+
949| :c:data:`PyExc_ValueError`              | :exc:`ValueError`               |          |
950+-----------------------------------------+---------------------------------+----------+
951| :c:data:`PyExc_ZeroDivisionError`       | :exc:`ZeroDivisionError`        |          |
952+-----------------------------------------+---------------------------------+----------+
953
954.. versionadded:: 3.3
955   :c:data:`PyExc_BlockingIOError`, :c:data:`PyExc_BrokenPipeError`,
956   :c:data:`PyExc_ChildProcessError`, :c:data:`PyExc_ConnectionError`,
957   :c:data:`PyExc_ConnectionAbortedError`, :c:data:`PyExc_ConnectionRefusedError`,
958   :c:data:`PyExc_ConnectionResetError`, :c:data:`PyExc_FileExistsError`,
959   :c:data:`PyExc_FileNotFoundError`, :c:data:`PyExc_InterruptedError`,
960   :c:data:`PyExc_IsADirectoryError`, :c:data:`PyExc_NotADirectoryError`,
961   :c:data:`PyExc_PermissionError`, :c:data:`PyExc_ProcessLookupError`
962   and :c:data:`PyExc_TimeoutError` were introduced following :pep:`3151`.
963
964.. versionadded:: 3.5
965   :c:data:`PyExc_StopAsyncIteration` and :c:data:`PyExc_RecursionError`.
966
967.. versionadded:: 3.6
968   :c:data:`PyExc_ModuleNotFoundError`.
969
970These are compatibility aliases to :c:data:`PyExc_OSError`:
971
972.. index::
973   single: PyExc_EnvironmentError
974   single: PyExc_IOError
975   single: PyExc_WindowsError
976
977+-------------------------------------+----------+
978| C Name                              | Notes    |
979+=====================================+==========+
980| :c:data:`PyExc_EnvironmentError`    |          |
981+-------------------------------------+----------+
982| :c:data:`PyExc_IOError`             |          |
983+-------------------------------------+----------+
984| :c:data:`PyExc_WindowsError`        | \(3)     |
985+-------------------------------------+----------+
986
987.. versionchanged:: 3.3
988   These aliases used to be separate exception types.
989
990Notes:
991
992(1)
993   This is a base class for other standard exceptions.
994
995(2)
996   Only defined on Windows; protect code that uses this by testing that the
997   preprocessor macro ``MS_WINDOWS`` is defined.
998
999.. _standardwarningcategories:
1000
1001Standard Warning Categories
1002===========================
1003
1004All standard Python warning categories are available as global variables whose
1005names are ``PyExc_`` followed by the Python exception name. These have the type
1006:c:type:`PyObject*`; they are all class objects. For completeness, here are all
1007the variables:
1008
1009.. index::
1010   single: PyExc_Warning
1011   single: PyExc_BytesWarning
1012   single: PyExc_DeprecationWarning
1013   single: PyExc_FutureWarning
1014   single: PyExc_ImportWarning
1015   single: PyExc_PendingDeprecationWarning
1016   single: PyExc_ResourceWarning
1017   single: PyExc_RuntimeWarning
1018   single: PyExc_SyntaxWarning
1019   single: PyExc_UnicodeWarning
1020   single: PyExc_UserWarning
1021
1022+------------------------------------------+---------------------------------+----------+
1023| C Name                                   | Python Name                     | Notes    |
1024+==========================================+=================================+==========+
1025| :c:data:`PyExc_Warning`                  | :exc:`Warning`                  | \(1)     |
1026+------------------------------------------+---------------------------------+----------+
1027| :c:data:`PyExc_BytesWarning`             | :exc:`BytesWarning`             |          |
1028+------------------------------------------+---------------------------------+----------+
1029| :c:data:`PyExc_DeprecationWarning`       | :exc:`DeprecationWarning`       |          |
1030+------------------------------------------+---------------------------------+----------+
1031| :c:data:`PyExc_FutureWarning`            | :exc:`FutureWarning`            |          |
1032+------------------------------------------+---------------------------------+----------+
1033| :c:data:`PyExc_ImportWarning`            | :exc:`ImportWarning`            |          |
1034+------------------------------------------+---------------------------------+----------+
1035| :c:data:`PyExc_PendingDeprecationWarning`| :exc:`PendingDeprecationWarning`|          |
1036+------------------------------------------+---------------------------------+----------+
1037| :c:data:`PyExc_ResourceWarning`          | :exc:`ResourceWarning`          |          |
1038+------------------------------------------+---------------------------------+----------+
1039| :c:data:`PyExc_RuntimeWarning`           | :exc:`RuntimeWarning`           |          |
1040+------------------------------------------+---------------------------------+----------+
1041| :c:data:`PyExc_SyntaxWarning`            | :exc:`SyntaxWarning`            |          |
1042+------------------------------------------+---------------------------------+----------+
1043| :c:data:`PyExc_UnicodeWarning`           | :exc:`UnicodeWarning`           |          |
1044+------------------------------------------+---------------------------------+----------+
1045| :c:data:`PyExc_UserWarning`              | :exc:`UserWarning`              |          |
1046+------------------------------------------+---------------------------------+----------+
1047
1048.. versionadded:: 3.2
1049   :c:data:`PyExc_ResourceWarning`.
1050
1051Notes:
1052
1053(1)
1054   This is a base class for other standard warning categories.
1055