• 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 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 pass *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   .. note::
378
379      Do not compare the return value to a specific exception; use
380      :c:func:`PyErr_ExceptionMatches` instead, shown below.  (The comparison could
381      easily fail since the exception may be an instance instead of a class, in the
382      case of a class exception, or it may be a subclass of the expected exception.)
383
384
385.. c:function:: int PyErr_ExceptionMatches(PyObject *exc)
386
387   Equivalent to ``PyErr_GivenExceptionMatches(PyErr_Occurred(), exc)``.  This
388   should only be called when an exception is actually set; a memory access
389   violation will occur if no exception has been raised.
390
391
392.. c:function:: int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc)
393
394   Return true if the *given* exception matches the exception type in *exc*.  If
395   *exc* is a class object, this also returns true when *given* is an instance
396   of a subclass.  If *exc* is a tuple, all exception types in the tuple (and
397   recursively in subtuples) are searched for a match.
398
399
400.. c:function:: void PyErr_Fetch(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)
401
402   Retrieve the error indicator into three variables whose addresses are passed.
403   If the error indicator is not set, set all three variables to ``NULL``.  If it is
404   set, it will be cleared and you own a reference to each object retrieved.  The
405   value and traceback object may be ``NULL`` even when the type object is not.
406
407   .. note::
408
409      This function is normally only used by code that needs to catch exceptions or
410      by code that needs to save and restore the error indicator temporarily, e.g.::
411
412         {
413            PyObject *type, *value, *traceback;
414            PyErr_Fetch(&type, &value, &traceback);
415
416            /* ... code that might produce other errors ... */
417
418            PyErr_Restore(type, value, traceback);
419         }
420
421
422.. c:function:: void PyErr_Restore(PyObject *type, PyObject *value, PyObject *traceback)
423
424   Set  the error indicator from the three objects.  If the error indicator is
425   already set, it is cleared first.  If the objects are ``NULL``, the error
426   indicator is cleared.  Do not pass a ``NULL`` type and non-``NULL`` value or
427   traceback.  The exception type should be a class.  Do not pass an invalid
428   exception type or value. (Violating these rules will cause subtle problems
429   later.)  This call takes away a reference to each object: you must own a
430   reference to each object before the call and after the call you no longer own
431   these references.  (If you don't understand this, don't use this function.  I
432   warned you.)
433
434   .. note::
435
436      This function is normally only used by code that needs to save and restore the
437      error indicator temporarily.  Use :c:func:`PyErr_Fetch` to save the current
438      error indicator.
439
440
441.. c:function:: void PyErr_NormalizeException(PyObject**exc, PyObject**val, PyObject**tb)
442
443   Under certain circumstances, the values returned by :c:func:`PyErr_Fetch` below
444   can be "unnormalized", meaning that ``*exc`` is a class object but ``*val`` is
445   not an instance of the  same class.  This function can be used to instantiate
446   the class in that case.  If the values are already normalized, nothing happens.
447   The delayed normalization is implemented to improve performance.
448
449   .. note::
450
451      This function *does not* implicitly set the ``__traceback__``
452      attribute on the exception value. If setting the traceback
453      appropriately is desired, the following additional snippet is needed::
454
455         if (tb != NULL) {
456           PyException_SetTraceback(val, tb);
457         }
458
459
460.. c:function:: void PyErr_GetExcInfo(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)
461
462   Retrieve the exception info, as known from ``sys.exc_info()``.  This refers
463   to an exception that was *already caught*, not to an exception that was
464   freshly raised.  Returns new references for the three objects, any of which
465   may be ``NULL``.  Does not modify the exception info state.
466
467   .. note::
468
469      This function is not normally used by code that wants to handle exceptions.
470      Rather, it can be used when code needs to save and restore the exception
471      state temporarily.  Use :c:func:`PyErr_SetExcInfo` to restore or clear the
472      exception state.
473
474   .. versionadded:: 3.3
475
476
477.. c:function:: void PyErr_SetExcInfo(PyObject *type, PyObject *value, PyObject *traceback)
478
479   Set the exception info, as known from ``sys.exc_info()``.  This refers
480   to an exception that was *already caught*, not to an exception that was
481   freshly raised.  This function steals the references of the arguments.
482   To clear the exception state, pass ``NULL`` for all three arguments.
483   For general rules about the three arguments, see :c:func:`PyErr_Restore`.
484
485   .. note::
486
487      This function is not normally used by code that wants to handle exceptions.
488      Rather, it can be used when code needs to save and restore the exception
489      state temporarily.  Use :c:func:`PyErr_GetExcInfo` to read the exception
490      state.
491
492   .. versionadded:: 3.3
493
494
495Signal Handling
496===============
497
498
499.. c:function:: int PyErr_CheckSignals()
500
501   .. index::
502      module: signal
503      single: SIGINT
504      single: KeyboardInterrupt (built-in exception)
505
506   This function interacts with Python's signal handling.  It checks whether a
507   signal has been sent to the processes and if so, invokes the corresponding
508   signal handler.  If the :mod:`signal` module is supported, this can invoke a
509   signal handler written in Python.  In all cases, the default effect for
510   :const:`SIGINT` is to raise the  :exc:`KeyboardInterrupt` exception.  If an
511   exception is raised the error indicator is set and the function returns ``-1``;
512   otherwise the function returns ``0``.  The error indicator may or may not be
513   cleared if it was previously set.
514
515
516.. c:function:: void PyErr_SetInterrupt()
517
518   .. index::
519      single: SIGINT
520      single: KeyboardInterrupt (built-in exception)
521
522   Simulate the effect of a :const:`SIGINT` signal arriving. The next time
523   :c:func:`PyErr_CheckSignals` is called,  the Python signal handler for
524   :const:`SIGINT` will be called.
525
526   If :const:`SIGINT` isn't handled by Python (it was set to
527   :data:`signal.SIG_DFL` or :data:`signal.SIG_IGN`), this function does
528   nothing.
529
530.. c:function:: int PySignal_SetWakeupFd(int fd)
531
532   This utility function specifies a file descriptor to which the signal number
533   is written as a single byte whenever a signal is received. *fd* must be
534   non-blocking. It returns the previous such file descriptor.
535
536   The value ``-1`` disables the feature; this is the initial state.
537   This is equivalent to :func:`signal.set_wakeup_fd` in Python, but without any
538   error checking.  *fd* should be a valid file descriptor.  The function should
539   only be called from the main thread.
540
541   .. versionchanged:: 3.5
542      On Windows, the function now also supports socket handles.
543
544
545Exception Classes
546=================
547
548.. c:function:: PyObject* PyErr_NewException(const char *name, PyObject *base, PyObject *dict)
549
550   This utility function creates and returns a new exception class. The *name*
551   argument must be the name of the new exception, a C string of the form
552   ``module.classname``.  The *base* and *dict* arguments are normally ``NULL``.
553   This creates a class object derived from :exc:`Exception` (accessible in C as
554   :c:data:`PyExc_Exception`).
555
556   The :attr:`__module__` attribute of the new class is set to the first part (up
557   to the last dot) of the *name* argument, and the class name is set to the last
558   part (after the last dot).  The *base* argument can be used to specify alternate
559   base classes; it can either be only one class or a tuple of classes. The *dict*
560   argument can be used to specify a dictionary of class variables and methods.
561
562
563.. c:function:: PyObject* PyErr_NewExceptionWithDoc(const char *name, const char *doc, PyObject *base, PyObject *dict)
564
565   Same as :c:func:`PyErr_NewException`, except that the new exception class can
566   easily be given a docstring: If *doc* is non-``NULL``, it will be used as the
567   docstring for the exception class.
568
569   .. versionadded:: 3.2
570
571
572Exception Objects
573=================
574
575.. c:function:: PyObject* PyException_GetTraceback(PyObject *ex)
576
577   Return the traceback associated with the exception as a new reference, as
578   accessible from Python through :attr:`__traceback__`.  If there is no
579   traceback associated, this returns ``NULL``.
580
581
582.. c:function:: int PyException_SetTraceback(PyObject *ex, PyObject *tb)
583
584   Set the traceback associated with the exception to *tb*.  Use ``Py_None`` to
585   clear it.
586
587
588.. c:function:: PyObject* PyException_GetContext(PyObject *ex)
589
590   Return the context (another exception instance during whose handling *ex* was
591   raised) associated with the exception as a new reference, as accessible from
592   Python through :attr:`__context__`.  If there is no context associated, this
593   returns ``NULL``.
594
595
596.. c:function:: void PyException_SetContext(PyObject *ex, PyObject *ctx)
597
598   Set the context associated with the exception to *ctx*.  Use ``NULL`` to clear
599   it.  There is no type check to make sure that *ctx* is an exception instance.
600   This steals a reference to *ctx*.
601
602
603.. c:function:: PyObject* PyException_GetCause(PyObject *ex)
604
605   Return the cause (either an exception instance, or :const:`None`,
606   set by ``raise ... from ...``) associated with the exception as a new
607   reference, as accessible from Python through :attr:`__cause__`.
608
609
610.. c:function:: void PyException_SetCause(PyObject *ex, PyObject *cause)
611
612   Set the cause associated with the exception to *cause*.  Use ``NULL`` to clear
613   it.  There is no type check to make sure that *cause* is either an exception
614   instance or :const:`None`.  This steals a reference to *cause*.
615
616   :attr:`__suppress_context__` is implicitly set to ``True`` by this function.
617
618
619.. _unicodeexceptions:
620
621Unicode Exception Objects
622=========================
623
624The following functions are used to create and modify Unicode exceptions from C.
625
626.. 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)
627
628   Create a :class:`UnicodeDecodeError` object with the attributes *encoding*,
629   *object*, *length*, *start*, *end* and *reason*. *encoding* and *reason* are
630   UTF-8 encoded strings.
631
632.. 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)
633
634   Create a :class:`UnicodeEncodeError` object with the attributes *encoding*,
635   *object*, *length*, *start*, *end* and *reason*. *encoding* and *reason* are
636   UTF-8 encoded strings.
637
638.. c:function:: PyObject* PyUnicodeTranslateError_Create(const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
639
640   Create a :class:`UnicodeTranslateError` object with the attributes *object*,
641   *length*, *start*, *end* and *reason*. *reason* is a UTF-8 encoded string.
642
643.. c:function:: PyObject* PyUnicodeDecodeError_GetEncoding(PyObject *exc)
644                PyObject* PyUnicodeEncodeError_GetEncoding(PyObject *exc)
645
646   Return the *encoding* attribute of the given exception object.
647
648.. c:function:: PyObject* PyUnicodeDecodeError_GetObject(PyObject *exc)
649                PyObject* PyUnicodeEncodeError_GetObject(PyObject *exc)
650                PyObject* PyUnicodeTranslateError_GetObject(PyObject *exc)
651
652   Return the *object* attribute of the given exception object.
653
654.. c:function:: int PyUnicodeDecodeError_GetStart(PyObject *exc, Py_ssize_t *start)
655                int PyUnicodeEncodeError_GetStart(PyObject *exc, Py_ssize_t *start)
656                int PyUnicodeTranslateError_GetStart(PyObject *exc, Py_ssize_t *start)
657
658   Get the *start* attribute of the given exception object and place it into
659   *\*start*.  *start* must not be ``NULL``.  Return ``0`` on success, ``-1`` on
660   failure.
661
662.. c:function:: int PyUnicodeDecodeError_SetStart(PyObject *exc, Py_ssize_t start)
663                int PyUnicodeEncodeError_SetStart(PyObject *exc, Py_ssize_t start)
664                int PyUnicodeTranslateError_SetStart(PyObject *exc, Py_ssize_t start)
665
666   Set the *start* attribute of the given exception object to *start*.  Return
667   ``0`` on success, ``-1`` on failure.
668
669.. c:function:: int PyUnicodeDecodeError_GetEnd(PyObject *exc, Py_ssize_t *end)
670                int PyUnicodeEncodeError_GetEnd(PyObject *exc, Py_ssize_t *end)
671                int PyUnicodeTranslateError_GetEnd(PyObject *exc, Py_ssize_t *end)
672
673   Get the *end* attribute of the given exception object and place it into
674   *\*end*.  *end* must not be ``NULL``.  Return ``0`` on success, ``-1`` on
675   failure.
676
677.. c:function:: int PyUnicodeDecodeError_SetEnd(PyObject *exc, Py_ssize_t end)
678                int PyUnicodeEncodeError_SetEnd(PyObject *exc, Py_ssize_t end)
679                int PyUnicodeTranslateError_SetEnd(PyObject *exc, Py_ssize_t end)
680
681   Set the *end* attribute of the given exception object to *end*.  Return ``0``
682   on success, ``-1`` on failure.
683
684.. c:function:: PyObject* PyUnicodeDecodeError_GetReason(PyObject *exc)
685                PyObject* PyUnicodeEncodeError_GetReason(PyObject *exc)
686                PyObject* PyUnicodeTranslateError_GetReason(PyObject *exc)
687
688   Return the *reason* attribute of the given exception object.
689
690.. c:function:: int PyUnicodeDecodeError_SetReason(PyObject *exc, const char *reason)
691                int PyUnicodeEncodeError_SetReason(PyObject *exc, const char *reason)
692                int PyUnicodeTranslateError_SetReason(PyObject *exc, const char *reason)
693
694   Set the *reason* attribute of the given exception object to *reason*.  Return
695   ``0`` on success, ``-1`` on failure.
696
697
698Recursion Control
699=================
700
701These two functions provide a way to perform safe recursive calls at the C
702level, both in the core and in extension modules.  They are needed if the
703recursive code does not necessarily invoke Python code (which tracks its
704recursion depth automatically).
705
706.. c:function:: int Py_EnterRecursiveCall(const char *where)
707
708   Marks a point where a recursive C-level call is about to be performed.
709
710   If :const:`USE_STACKCHECK` is defined, this function checks if the OS
711   stack overflowed using :c:func:`PyOS_CheckStack`.  In this is the case, it
712   sets a :exc:`MemoryError` and returns a nonzero value.
713
714   The function then checks if the recursion limit is reached.  If this is the
715   case, a :exc:`RecursionError` is set and a nonzero value is returned.
716   Otherwise, zero is returned.
717
718   *where* should be a string such as ``" in instance check"`` to be
719   concatenated to the :exc:`RecursionError` message caused by the recursion
720   depth limit.
721
722.. c:function:: void Py_LeaveRecursiveCall()
723
724   Ends a :c:func:`Py_EnterRecursiveCall`.  Must be called once for each
725   *successful* invocation of :c:func:`Py_EnterRecursiveCall`.
726
727Properly implementing :c:member:`~PyTypeObject.tp_repr` for container types requires
728special recursion handling.  In addition to protecting the stack,
729:c:member:`~PyTypeObject.tp_repr` also needs to track objects to prevent cycles.  The
730following two functions facilitate this functionality.  Effectively,
731these are the C equivalent to :func:`reprlib.recursive_repr`.
732
733.. c:function:: int Py_ReprEnter(PyObject *object)
734
735   Called at the beginning of the :c:member:`~PyTypeObject.tp_repr` implementation to
736   detect cycles.
737
738   If the object has already been processed, the function returns a
739   positive integer.  In that case the :c:member:`~PyTypeObject.tp_repr` implementation
740   should return a string object indicating a cycle.  As examples,
741   :class:`dict` objects return ``{...}`` and :class:`list` objects
742   return ``[...]``.
743
744   The function will return a negative integer if the recursion limit
745   is reached.  In that case the :c:member:`~PyTypeObject.tp_repr` implementation should
746   typically return ``NULL``.
747
748   Otherwise, the function returns zero and the :c:member:`~PyTypeObject.tp_repr`
749   implementation can continue normally.
750
751.. c:function:: void Py_ReprLeave(PyObject *object)
752
753   Ends a :c:func:`Py_ReprEnter`.  Must be called once for each
754   invocation of :c:func:`Py_ReprEnter` that returns zero.
755
756
757.. _standardexceptions:
758
759Standard Exceptions
760===================
761
762All standard Python exceptions are available as global variables whose names are
763``PyExc_`` followed by the Python exception name.  These have the type
764:c:type:`PyObject\*`; they are all class objects.  For completeness, here are all
765the variables:
766
767.. index::
768   single: PyExc_BaseException
769   single: PyExc_Exception
770   single: PyExc_ArithmeticError
771   single: PyExc_AssertionError
772   single: PyExc_AttributeError
773   single: PyExc_BlockingIOError
774   single: PyExc_BrokenPipeError
775   single: PyExc_BufferError
776   single: PyExc_ChildProcessError
777   single: PyExc_ConnectionAbortedError
778   single: PyExc_ConnectionError
779   single: PyExc_ConnectionRefusedError
780   single: PyExc_ConnectionResetError
781   single: PyExc_EOFError
782   single: PyExc_FileExistsError
783   single: PyExc_FileNotFoundError
784   single: PyExc_FloatingPointError
785   single: PyExc_GeneratorExit
786   single: PyExc_ImportError
787   single: PyExc_IndentationError
788   single: PyExc_IndexError
789   single: PyExc_InterruptedError
790   single: PyExc_IsADirectoryError
791   single: PyExc_KeyError
792   single: PyExc_KeyboardInterrupt
793   single: PyExc_LookupError
794   single: PyExc_MemoryError
795   single: PyExc_ModuleNotFoundError
796   single: PyExc_NameError
797   single: PyExc_NotADirectoryError
798   single: PyExc_NotImplementedError
799   single: PyExc_OSError
800   single: PyExc_OverflowError
801   single: PyExc_PermissionError
802   single: PyExc_ProcessLookupError
803   single: PyExc_RecursionError
804   single: PyExc_ReferenceError
805   single: PyExc_RuntimeError
806   single: PyExc_StopAsyncIteration
807   single: PyExc_StopIteration
808   single: PyExc_SyntaxError
809   single: PyExc_SystemError
810   single: PyExc_SystemExit
811   single: PyExc_TabError
812   single: PyExc_TimeoutError
813   single: PyExc_TypeError
814   single: PyExc_UnboundLocalError
815   single: PyExc_UnicodeDecodeError
816   single: PyExc_UnicodeEncodeError
817   single: PyExc_UnicodeError
818   single: PyExc_UnicodeTranslateError
819   single: PyExc_ValueError
820   single: PyExc_ZeroDivisionError
821
822+-----------------------------------------+---------------------------------+----------+
823| C Name                                  | Python Name                     | Notes    |
824+=========================================+=================================+==========+
825| :c:data:`PyExc_BaseException`           | :exc:`BaseException`            | \(1)     |
826+-----------------------------------------+---------------------------------+----------+
827| :c:data:`PyExc_Exception`               | :exc:`Exception`                | \(1)     |
828+-----------------------------------------+---------------------------------+----------+
829| :c:data:`PyExc_ArithmeticError`         | :exc:`ArithmeticError`          | \(1)     |
830+-----------------------------------------+---------------------------------+----------+
831| :c:data:`PyExc_AssertionError`          | :exc:`AssertionError`           |          |
832+-----------------------------------------+---------------------------------+----------+
833| :c:data:`PyExc_AttributeError`          | :exc:`AttributeError`           |          |
834+-----------------------------------------+---------------------------------+----------+
835| :c:data:`PyExc_BlockingIOError`         | :exc:`BlockingIOError`          |          |
836+-----------------------------------------+---------------------------------+----------+
837| :c:data:`PyExc_BrokenPipeError`         | :exc:`BrokenPipeError`          |          |
838+-----------------------------------------+---------------------------------+----------+
839| :c:data:`PyExc_BufferError`             | :exc:`BufferError`              |          |
840+-----------------------------------------+---------------------------------+----------+
841| :c:data:`PyExc_ChildProcessError`       | :exc:`ChildProcessError`        |          |
842+-----------------------------------------+---------------------------------+----------+
843| :c:data:`PyExc_ConnectionAbortedError`  | :exc:`ConnectionAbortedError`   |          |
844+-----------------------------------------+---------------------------------+----------+
845| :c:data:`PyExc_ConnectionError`         | :exc:`ConnectionError`          |          |
846+-----------------------------------------+---------------------------------+----------+
847| :c:data:`PyExc_ConnectionRefusedError`  | :exc:`ConnectionRefusedError`   |          |
848+-----------------------------------------+---------------------------------+----------+
849| :c:data:`PyExc_ConnectionResetError`    | :exc:`ConnectionResetError`     |          |
850+-----------------------------------------+---------------------------------+----------+
851| :c:data:`PyExc_EOFError`                | :exc:`EOFError`                 |          |
852+-----------------------------------------+---------------------------------+----------+
853| :c:data:`PyExc_FileExistsError`         | :exc:`FileExistsError`          |          |
854+-----------------------------------------+---------------------------------+----------+
855| :c:data:`PyExc_FileNotFoundError`       | :exc:`FileNotFoundError`        |          |
856+-----------------------------------------+---------------------------------+----------+
857| :c:data:`PyExc_FloatingPointError`      | :exc:`FloatingPointError`       |          |
858+-----------------------------------------+---------------------------------+----------+
859| :c:data:`PyExc_GeneratorExit`           | :exc:`GeneratorExit`            |          |
860+-----------------------------------------+---------------------------------+----------+
861| :c:data:`PyExc_ImportError`             | :exc:`ImportError`              |          |
862+-----------------------------------------+---------------------------------+----------+
863| :c:data:`PyExc_IndentationError`        | :exc:`IndentationError`         |          |
864+-----------------------------------------+---------------------------------+----------+
865| :c:data:`PyExc_IndexError`              | :exc:`IndexError`               |          |
866+-----------------------------------------+---------------------------------+----------+
867| :c:data:`PyExc_InterruptedError`        | :exc:`InterruptedError`         |          |
868+-----------------------------------------+---------------------------------+----------+
869| :c:data:`PyExc_IsADirectoryError`       | :exc:`IsADirectoryError`        |          |
870+-----------------------------------------+---------------------------------+----------+
871| :c:data:`PyExc_KeyError`                | :exc:`KeyError`                 |          |
872+-----------------------------------------+---------------------------------+----------+
873| :c:data:`PyExc_KeyboardInterrupt`       | :exc:`KeyboardInterrupt`        |          |
874+-----------------------------------------+---------------------------------+----------+
875| :c:data:`PyExc_LookupError`             | :exc:`LookupError`              | \(1)     |
876+-----------------------------------------+---------------------------------+----------+
877| :c:data:`PyExc_MemoryError`             | :exc:`MemoryError`              |          |
878+-----------------------------------------+---------------------------------+----------+
879| :c:data:`PyExc_ModuleNotFoundError`     | :exc:`ModuleNotFoundError`      |          |
880+-----------------------------------------+---------------------------------+----------+
881| :c:data:`PyExc_NameError`               | :exc:`NameError`                |          |
882+-----------------------------------------+---------------------------------+----------+
883| :c:data:`PyExc_NotADirectoryError`      | :exc:`NotADirectoryError`       |          |
884+-----------------------------------------+---------------------------------+----------+
885| :c:data:`PyExc_NotImplementedError`     | :exc:`NotImplementedError`      |          |
886+-----------------------------------------+---------------------------------+----------+
887| :c:data:`PyExc_OSError`                 | :exc:`OSError`                  | \(1)     |
888+-----------------------------------------+---------------------------------+----------+
889| :c:data:`PyExc_OverflowError`           | :exc:`OverflowError`            |          |
890+-----------------------------------------+---------------------------------+----------+
891| :c:data:`PyExc_PermissionError`         | :exc:`PermissionError`          |          |
892+-----------------------------------------+---------------------------------+----------+
893| :c:data:`PyExc_ProcessLookupError`      | :exc:`ProcessLookupError`       |          |
894+-----------------------------------------+---------------------------------+----------+
895| :c:data:`PyExc_RecursionError`          | :exc:`RecursionError`           |          |
896+-----------------------------------------+---------------------------------+----------+
897| :c:data:`PyExc_ReferenceError`          | :exc:`ReferenceError`           | \(2)     |
898+-----------------------------------------+---------------------------------+----------+
899| :c:data:`PyExc_RuntimeError`            | :exc:`RuntimeError`             |          |
900+-----------------------------------------+---------------------------------+----------+
901| :c:data:`PyExc_StopAsyncIteration`      | :exc:`StopAsyncIteration`       |          |
902+-----------------------------------------+---------------------------------+----------+
903| :c:data:`PyExc_StopIteration`           | :exc:`StopIteration`            |          |
904+-----------------------------------------+---------------------------------+----------+
905| :c:data:`PyExc_SyntaxError`             | :exc:`SyntaxError`              |          |
906+-----------------------------------------+---------------------------------+----------+
907| :c:data:`PyExc_SystemError`             | :exc:`SystemError`              |          |
908+-----------------------------------------+---------------------------------+----------+
909| :c:data:`PyExc_SystemExit`              | :exc:`SystemExit`               |          |
910+-----------------------------------------+---------------------------------+----------+
911| :c:data:`PyExc_TabError`                | :exc:`TabError`                 |          |
912+-----------------------------------------+---------------------------------+----------+
913| :c:data:`PyExc_TimeoutError`            | :exc:`TimeoutError`             |          |
914+-----------------------------------------+---------------------------------+----------+
915| :c:data:`PyExc_TypeError`               | :exc:`TypeError`                |          |
916+-----------------------------------------+---------------------------------+----------+
917| :c:data:`PyExc_UnboundLocalError`       | :exc:`UnboundLocalError`        |          |
918+-----------------------------------------+---------------------------------+----------+
919| :c:data:`PyExc_UnicodeDecodeError`      | :exc:`UnicodeDecodeError`       |          |
920+-----------------------------------------+---------------------------------+----------+
921| :c:data:`PyExc_UnicodeEncodeError`      | :exc:`UnicodeEncodeError`       |          |
922+-----------------------------------------+---------------------------------+----------+
923| :c:data:`PyExc_UnicodeError`            | :exc:`UnicodeError`             |          |
924+-----------------------------------------+---------------------------------+----------+
925| :c:data:`PyExc_UnicodeTranslateError`   | :exc:`UnicodeTranslateError`    |          |
926+-----------------------------------------+---------------------------------+----------+
927| :c:data:`PyExc_ValueError`              | :exc:`ValueError`               |          |
928+-----------------------------------------+---------------------------------+----------+
929| :c:data:`PyExc_ZeroDivisionError`       | :exc:`ZeroDivisionError`        |          |
930+-----------------------------------------+---------------------------------+----------+
931
932.. versionadded:: 3.3
933   :c:data:`PyExc_BlockingIOError`, :c:data:`PyExc_BrokenPipeError`,
934   :c:data:`PyExc_ChildProcessError`, :c:data:`PyExc_ConnectionError`,
935   :c:data:`PyExc_ConnectionAbortedError`, :c:data:`PyExc_ConnectionRefusedError`,
936   :c:data:`PyExc_ConnectionResetError`, :c:data:`PyExc_FileExistsError`,
937   :c:data:`PyExc_FileNotFoundError`, :c:data:`PyExc_InterruptedError`,
938   :c:data:`PyExc_IsADirectoryError`, :c:data:`PyExc_NotADirectoryError`,
939   :c:data:`PyExc_PermissionError`, :c:data:`PyExc_ProcessLookupError`
940   and :c:data:`PyExc_TimeoutError` were introduced following :pep:`3151`.
941
942.. versionadded:: 3.5
943   :c:data:`PyExc_StopAsyncIteration` and :c:data:`PyExc_RecursionError`.
944
945.. versionadded:: 3.6
946   :c:data:`PyExc_ModuleNotFoundError`.
947
948These are compatibility aliases to :c:data:`PyExc_OSError`:
949
950.. index::
951   single: PyExc_EnvironmentError
952   single: PyExc_IOError
953   single: PyExc_WindowsError
954
955+-------------------------------------+----------+
956| C Name                              | Notes    |
957+=====================================+==========+
958| :c:data:`PyExc_EnvironmentError`    |          |
959+-------------------------------------+----------+
960| :c:data:`PyExc_IOError`             |          |
961+-------------------------------------+----------+
962| :c:data:`PyExc_WindowsError`        | \(3)     |
963+-------------------------------------+----------+
964
965.. versionchanged:: 3.3
966   These aliases used to be separate exception types.
967
968Notes:
969
970(1)
971   This is a base class for other standard exceptions.
972
973(2)
974   This is the same as :exc:`weakref.ReferenceError`.
975
976(3)
977   Only defined on Windows; protect code that uses this by testing that the
978   preprocessor macro ``MS_WINDOWS`` is defined.
979
980.. _standardwarningcategories:
981
982Standard Warning Categories
983===========================
984
985All standard Python warning categories are available as global variables whose
986names are ``PyExc_`` followed by the Python exception name. These have the type
987:c:type:`PyObject\*`; they are all class objects. For completeness, here are all
988the variables:
989
990.. index::
991   single: PyExc_Warning
992   single: PyExc_BytesWarning
993   single: PyExc_DeprecationWarning
994   single: PyExc_FutureWarning
995   single: PyExc_ImportWarning
996   single: PyExc_PendingDeprecationWarning
997   single: PyExc_ResourceWarning
998   single: PyExc_RuntimeWarning
999   single: PyExc_SyntaxWarning
1000   single: PyExc_UnicodeWarning
1001   single: PyExc_UserWarning
1002
1003+------------------------------------------+---------------------------------+----------+
1004| C Name                                   | Python Name                     | Notes    |
1005+==========================================+=================================+==========+
1006| :c:data:`PyExc_Warning`                  | :exc:`Warning`                  | \(1)     |
1007+------------------------------------------+---------------------------------+----------+
1008| :c:data:`PyExc_BytesWarning`             | :exc:`BytesWarning`             |          |
1009+------------------------------------------+---------------------------------+----------+
1010| :c:data:`PyExc_DeprecationWarning`       | :exc:`DeprecationWarning`       |          |
1011+------------------------------------------+---------------------------------+----------+
1012| :c:data:`PyExc_FutureWarning`            | :exc:`FutureWarning`            |          |
1013+------------------------------------------+---------------------------------+----------+
1014| :c:data:`PyExc_ImportWarning`            | :exc:`ImportWarning`            |          |
1015+------------------------------------------+---------------------------------+----------+
1016| :c:data:`PyExc_PendingDeprecationWarning`| :exc:`PendingDeprecationWarning`|          |
1017+------------------------------------------+---------------------------------+----------+
1018| :c:data:`PyExc_ResourceWarning`          | :exc:`ResourceWarning`          |          |
1019+------------------------------------------+---------------------------------+----------+
1020| :c:data:`PyExc_RuntimeWarning`           | :exc:`RuntimeWarning`           |          |
1021+------------------------------------------+---------------------------------+----------+
1022| :c:data:`PyExc_SyntaxWarning`            | :exc:`SyntaxWarning`            |          |
1023+------------------------------------------+---------------------------------+----------+
1024| :c:data:`PyExc_UnicodeWarning`           | :exc:`UnicodeWarning`           |          |
1025+------------------------------------------+---------------------------------+----------+
1026| :c:data:`PyExc_UserWarning`              | :exc:`UserWarning`              |          |
1027+------------------------------------------+---------------------------------+----------+
1028
1029.. versionadded:: 3.2
1030   :c:data:`PyExc_ResourceWarning`.
1031
1032Notes:
1033
1034(1)
1035   This is a base class for other standard warning categories.
1036