blob: 8658a585410463a36a03c02d5432ab03c87a02a6 [file] [log] [blame]
Georg Brandl116aa622007-08-15 14:28:22 +00001.. highlightlang:: 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
Georg Brandl60203b42010-10-06 10:11:56 +000012exception handling. It works somewhat like the Unix :c:data:`errno` variable:
Georg Brandl116aa622007-08-15 14:28:22 +000013there is a global indicator (per thread) of the last error that occurred. Most
14functions don't clear this on success, but will set it to indicate the cause of
15the error on failure. Most functions also return an error indicator, usually
16*NULL* if they are supposed to return a pointer, or ``-1`` if they return an
Georg Brandl60203b42010-10-06 10:11:56 +000017integer (exception: the :c:func:`PyArg_\*` functions return ``1`` for success and
Georg Brandl116aa622007-08-15 14:28:22 +000018``0`` for failure).
19
20When a function must fail because some function it called failed, it generally
21doesn't set the error indicator; the function it called already set it. It is
22responsible for either handling the error and clearing the exception or
23returning after cleaning up any resources it holds (such as object references or
24memory allocations); it should *not* continue normally if it is not prepared to
25handle the error. If returning due to an error, it is important to indicate to
26the caller that an error has been set. If the error is not handled or carefully
27propagated, additional calls into the Python/C API may not behave as intended
28and may fail in mysterious ways.
29
30The error indicator consists of three Python objects corresponding to the result
31of ``sys.exc_info()``. API functions exist to interact with the error indicator
32in various ways. There is a separate error indicator for each thread.
33
Christian Heimes5b5e81c2007-12-31 16:14:33 +000034.. XXX Order of these should be more thoughtful.
35 Either alphabetical or some kind of structure.
Georg Brandl116aa622007-08-15 14:28:22 +000036
37
Georg Brandl60203b42010-10-06 10:11:56 +000038.. c:function:: void PyErr_PrintEx(int set_sys_last_vars)
Georg Brandl116aa622007-08-15 14:28:22 +000039
40 Print a standard traceback to ``sys.stderr`` and clear the error indicator.
41 Call this function only when the error indicator is set. (Otherwise it will
42 cause a fatal error!)
43
Georg Brandl115fb352009-02-05 10:56:37 +000044 If *set_sys_last_vars* is nonzero, the variables :data:`sys.last_type`,
45 :data:`sys.last_value` and :data:`sys.last_traceback` will be set to the
46 type, value and traceback of the printed exception, respectively.
47
48
Georg Brandl60203b42010-10-06 10:11:56 +000049.. c:function:: void PyErr_Print()
Georg Brandl115fb352009-02-05 10:56:37 +000050
51 Alias for ``PyErr_PrintEx(1)``.
52
Georg Brandl116aa622007-08-15 14:28:22 +000053
Georg Brandl60203b42010-10-06 10:11:56 +000054.. c:function:: PyObject* PyErr_Occurred()
Georg Brandl116aa622007-08-15 14:28:22 +000055
56 Test whether the error indicator is set. If set, return the exception *type*
Georg Brandl60203b42010-10-06 10:11:56 +000057 (the first argument to the last call to one of the :c:func:`PyErr_Set\*`
58 functions or to :c:func:`PyErr_Restore`). If not set, return *NULL*. You do not
59 own a reference to the return value, so you do not need to :c:func:`Py_DECREF`
Georg Brandl116aa622007-08-15 14:28:22 +000060 it.
61
62 .. note::
63
64 Do not compare the return value to a specific exception; use
Georg Brandl60203b42010-10-06 10:11:56 +000065 :c:func:`PyErr_ExceptionMatches` instead, shown below. (The comparison could
Georg Brandl116aa622007-08-15 14:28:22 +000066 easily fail since the exception may be an instance instead of a class, in the
67 case of a class exception, or it may the a subclass of the expected exception.)
68
69
Georg Brandl60203b42010-10-06 10:11:56 +000070.. c:function:: int PyErr_ExceptionMatches(PyObject *exc)
Georg Brandl116aa622007-08-15 14:28:22 +000071
72 Equivalent to ``PyErr_GivenExceptionMatches(PyErr_Occurred(), exc)``. This
73 should only be called when an exception is actually set; a memory access
74 violation will occur if no exception has been raised.
75
76
Georg Brandl60203b42010-10-06 10:11:56 +000077.. c:function:: int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc)
Georg Brandl116aa622007-08-15 14:28:22 +000078
Benjamin Petersonda10d3b2009-01-01 00:23:30 +000079 Return true if the *given* exception matches the exception in *exc*. If
80 *exc* is a class object, this also returns true when *given* is an instance
81 of a subclass. If *exc* is a tuple, all exceptions in the tuple (and
82 recursively in subtuples) are searched for a match.
Georg Brandl116aa622007-08-15 14:28:22 +000083
84
Georg Brandl60203b42010-10-06 10:11:56 +000085.. c:function:: void PyErr_NormalizeException(PyObject**exc, PyObject**val, PyObject**tb)
Georg Brandl116aa622007-08-15 14:28:22 +000086
Georg Brandl60203b42010-10-06 10:11:56 +000087 Under certain circumstances, the values returned by :c:func:`PyErr_Fetch` below
Georg Brandl116aa622007-08-15 14:28:22 +000088 can be "unnormalized", meaning that ``*exc`` is a class object but ``*val`` is
89 not an instance of the same class. This function can be used to instantiate
90 the class in that case. If the values are already normalized, nothing happens.
91 The delayed normalization is implemented to improve performance.
92
93
Georg Brandl60203b42010-10-06 10:11:56 +000094.. c:function:: void PyErr_Clear()
Georg Brandl116aa622007-08-15 14:28:22 +000095
96 Clear the error indicator. If the error indicator is not set, there is no
97 effect.
98
99
Georg Brandl60203b42010-10-06 10:11:56 +0000100.. c:function:: void PyErr_Fetch(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)
Georg Brandl116aa622007-08-15 14:28:22 +0000101
102 Retrieve the error indicator into three variables whose addresses are passed.
103 If the error indicator is not set, set all three variables to *NULL*. If it is
104 set, it will be cleared and you own a reference to each object retrieved. The
105 value and traceback object may be *NULL* even when the type object is not.
106
107 .. note::
108
109 This function is normally only used by code that needs to handle exceptions or
110 by code that needs to save and restore the error indicator temporarily.
111
112
Georg Brandl60203b42010-10-06 10:11:56 +0000113.. c:function:: void PyErr_Restore(PyObject *type, PyObject *value, PyObject *traceback)
Georg Brandl116aa622007-08-15 14:28:22 +0000114
115 Set the error indicator from the three objects. If the error indicator is
116 already set, it is cleared first. If the objects are *NULL*, the error
117 indicator is cleared. Do not pass a *NULL* type and non-*NULL* value or
118 traceback. The exception type should be a class. Do not pass an invalid
119 exception type or value. (Violating these rules will cause subtle problems
120 later.) This call takes away a reference to each object: you must own a
121 reference to each object before the call and after the call you no longer own
122 these references. (If you don't understand this, don't use this function. I
123 warned you.)
124
125 .. note::
126
127 This function is normally only used by code that needs to save and restore the
Georg Brandl60203b42010-10-06 10:11:56 +0000128 error indicator temporarily; use :c:func:`PyErr_Fetch` to save the current
Georg Brandl116aa622007-08-15 14:28:22 +0000129 exception state.
130
131
Martin v. Löwisaa2efcb2012-04-19 14:33:43 +0200132.. c:function:: void PyErr_GetExcInfo(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)
133
134 Retrieve the exception info, as known from ``sys.exc_info()``. This refers
135 to an exception that was already caught, not to an exception that was
136 freshly raised. Returns new references for the three objects, any of which
137 may be *NULL*. Does not modify the exception info state.
138
139 .. note::
140
141 This function is not normally used by code that wants to handle exceptions.
142 Rather, it can be used when code needs to save and restore the exception
143 state temporarily. Use :c:func:`PyErr_SetExcInfo` to restore or clear the
144 exception state.
145
Georg Brandlf4095832012-04-24 19:16:24 +0200146 .. versionadded:: 3.3
Martin v. Löwisaa2efcb2012-04-19 14:33:43 +0200147
148
149.. c:function:: void PyErr_SetExcInfo(PyObject *type, PyObject *value, PyObject *traceback)
150
151 Set the exception info, as known from ``sys.exc_info()``. This refers
152 to an exception that was already caught, not to an exception that was
153 freshly raised. This function steals the references of the arguments.
154 To clear the exception state, pass *NULL* for all three arguments.
155 For general rules about the three arguments, see :c:func:`PyErr_Restore`.
156
157 .. note::
158
159 This function is not normally used by code that wants to handle exceptions.
160 Rather, it can be used when code needs to save and restore the exception
161 state temporarily. Use :c:func:`PyErr_GetExcInfo` to read the exception
162 state.
163
Georg Brandlf4095832012-04-24 19:16:24 +0200164 .. versionadded:: 3.3
Martin v. Löwisaa2efcb2012-04-19 14:33:43 +0200165
166
Georg Brandl60203b42010-10-06 10:11:56 +0000167.. c:function:: void PyErr_SetString(PyObject *type, const char *message)
Georg Brandl116aa622007-08-15 14:28:22 +0000168
169 This is the most common way to set the error indicator. The first argument
170 specifies the exception type; it is normally one of the standard exceptions,
Georg Brandl60203b42010-10-06 10:11:56 +0000171 e.g. :c:data:`PyExc_RuntimeError`. You need not increment its reference count.
Victor Stinner257d38f2010-10-09 10:12:11 +0000172 The second argument is an error message; it is decoded from ``'utf-8``'.
Georg Brandl116aa622007-08-15 14:28:22 +0000173
174
Georg Brandl60203b42010-10-06 10:11:56 +0000175.. c:function:: void PyErr_SetObject(PyObject *type, PyObject *value)
Georg Brandl116aa622007-08-15 14:28:22 +0000176
Georg Brandl60203b42010-10-06 10:11:56 +0000177 This function is similar to :c:func:`PyErr_SetString` but lets you specify an
Georg Brandl116aa622007-08-15 14:28:22 +0000178 arbitrary Python object for the "value" of the exception.
179
180
Georg Brandl60203b42010-10-06 10:11:56 +0000181.. c:function:: PyObject* PyErr_Format(PyObject *exception, const char *format, ...)
Georg Brandl116aa622007-08-15 14:28:22 +0000182
Antoine Pitroua66e0292010-11-27 20:40:43 +0000183 This function sets the error indicator and returns *NULL*. *exception*
184 should be a Python exception class. The *format* and subsequent
185 parameters help format the error message; they have the same meaning and
Victor Stinnerb1dbd102010-12-28 11:02:46 +0000186 values as in :c:func:`PyUnicode_FromFormat`. *format* is an ASCII-encoded
Victor Stinner555a24f2010-12-27 01:49:26 +0000187 string.
Mark Dickinson6ce4a9a2009-11-16 17:00:11 +0000188
Georg Brandl116aa622007-08-15 14:28:22 +0000189
Georg Brandl60203b42010-10-06 10:11:56 +0000190.. c:function:: void PyErr_SetNone(PyObject *type)
Georg Brandl116aa622007-08-15 14:28:22 +0000191
192 This is a shorthand for ``PyErr_SetObject(type, Py_None)``.
193
194
Georg Brandl60203b42010-10-06 10:11:56 +0000195.. c:function:: int PyErr_BadArgument()
Georg Brandl116aa622007-08-15 14:28:22 +0000196
197 This is a shorthand for ``PyErr_SetString(PyExc_TypeError, message)``, where
198 *message* indicates that a built-in operation was invoked with an illegal
199 argument. It is mostly for internal use.
200
201
Georg Brandl60203b42010-10-06 10:11:56 +0000202.. c:function:: PyObject* PyErr_NoMemory()
Georg Brandl116aa622007-08-15 14:28:22 +0000203
204 This is a shorthand for ``PyErr_SetNone(PyExc_MemoryError)``; it returns *NULL*
205 so an object allocation function can write ``return PyErr_NoMemory();`` when it
206 runs out of memory.
207
208
Georg Brandl60203b42010-10-06 10:11:56 +0000209.. c:function:: PyObject* PyErr_SetFromErrno(PyObject *type)
Georg Brandl116aa622007-08-15 14:28:22 +0000210
211 .. index:: single: strerror()
212
213 This is a convenience function to raise an exception when a C library function
Georg Brandl60203b42010-10-06 10:11:56 +0000214 has returned an error and set the C variable :c:data:`errno`. It constructs a
215 tuple object whose first item is the integer :c:data:`errno` value and whose
216 second item is the corresponding error message (gotten from :c:func:`strerror`),
Georg Brandl116aa622007-08-15 14:28:22 +0000217 and then calls ``PyErr_SetObject(type, object)``. On Unix, when the
Georg Brandl60203b42010-10-06 10:11:56 +0000218 :c:data:`errno` value is :const:`EINTR`, indicating an interrupted system call,
219 this calls :c:func:`PyErr_CheckSignals`, and if that set the error indicator,
Georg Brandl116aa622007-08-15 14:28:22 +0000220 leaves it set to that. The function always returns *NULL*, so a wrapper
221 function around a system call can write ``return PyErr_SetFromErrno(type);``
222 when the system call returns an error.
223
224
Georg Brandl991fc572013-04-14 11:12:16 +0200225.. c:function:: PyObject* PyErr_SetFromErrnoWithFilenameObject(PyObject *type, PyObject *filenameObject)
Georg Brandl116aa622007-08-15 14:28:22 +0000226
Georg Brandl60203b42010-10-06 10:11:56 +0000227 Similar to :c:func:`PyErr_SetFromErrno`, with the additional behavior that if
Georg Brandl991fc572013-04-14 11:12:16 +0200228 *filenameObject* is not *NULL*, it is passed to the constructor of *type* as
229 a third parameter. In the case of exceptions such as :exc:`IOError` and
230 :exc:`OSError`, this is used to define the :attr:`filename` attribute of the
231 exception instance.
232
233
234.. c:function:: PyObject* PyErr_SetFromErrnoWithFilename(PyObject *type, const char *filename)
235
236 Similar to :c:func:`PyErr_SetFromErrnoWithFilenameObject`, but the filename
237 is given as a C string. *filename* is decoded from the filesystem encoding
Victor Stinner14e461d2013-08-26 22:28:21 +0200238 (:func:`os.fsdecode`).
Georg Brandl116aa622007-08-15 14:28:22 +0000239
240
Georg Brandl60203b42010-10-06 10:11:56 +0000241.. c:function:: PyObject* PyErr_SetFromWindowsErr(int ierr)
Georg Brandl116aa622007-08-15 14:28:22 +0000242
243 This is a convenience function to raise :exc:`WindowsError`. If called with
Georg Brandl60203b42010-10-06 10:11:56 +0000244 *ierr* of :c:data:`0`, the error code returned by a call to :c:func:`GetLastError`
245 is used instead. It calls the Win32 function :c:func:`FormatMessage` to retrieve
246 the Windows description of error code given by *ierr* or :c:func:`GetLastError`,
Georg Brandl116aa622007-08-15 14:28:22 +0000247 then it constructs a tuple object whose first item is the *ierr* value and whose
248 second item is the corresponding error message (gotten from
Georg Brandl60203b42010-10-06 10:11:56 +0000249 :c:func:`FormatMessage`), and then calls ``PyErr_SetObject(PyExc_WindowsError,
Georg Brandl116aa622007-08-15 14:28:22 +0000250 object)``. This function always returns *NULL*. Availability: Windows.
251
252
Georg Brandl60203b42010-10-06 10:11:56 +0000253.. c:function:: PyObject* PyErr_SetExcFromWindowsErr(PyObject *type, int ierr)
Georg Brandl116aa622007-08-15 14:28:22 +0000254
Georg Brandl60203b42010-10-06 10:11:56 +0000255 Similar to :c:func:`PyErr_SetFromWindowsErr`, with an additional parameter
Georg Brandl116aa622007-08-15 14:28:22 +0000256 specifying the exception type to be raised. Availability: Windows.
257
Georg Brandl116aa622007-08-15 14:28:22 +0000258
Georg Brandl991fc572013-04-14 11:12:16 +0200259.. c:function:: PyObject* PyErr_SetFromWindowsErrWithFilenameObject(int ierr, PyObject *filenameObject)
260
261 Similar to :c:func:`PyErr_SetFromWindowsErr`, with the additional behavior
262 that if *filenameObject* is not *NULL*, it is passed to the constructor of
263 :exc:`WindowsError` as a third parameter. Availability: Windows.
264
265
Georg Brandl60203b42010-10-06 10:11:56 +0000266.. c:function:: PyObject* PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename)
Georg Brandl116aa622007-08-15 14:28:22 +0000267
Georg Brandl991fc572013-04-14 11:12:16 +0200268 Similar to :c:func:`PyErr_SetFromWindowsErrWithFilenameObject`, but the
269 filename is given as a C string. *filename* is decoded from the filesystem
Victor Stinner14e461d2013-08-26 22:28:21 +0200270 encoding (:func:`os.fsdecode`). Availability: Windows.
Georg Brandl116aa622007-08-15 14:28:22 +0000271
272
Georg Brandl991fc572013-04-14 11:12:16 +0200273.. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilenameObject(PyObject *type, int ierr, PyObject *filename)
274
275 Similar to :c:func:`PyErr_SetFromWindowsErrWithFilenameObject`, with an
276 additional parameter specifying the exception type to be raised.
277 Availability: Windows.
278
279
280.. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, const char *filename)
Georg Brandl116aa622007-08-15 14:28:22 +0000281
Georg Brandl60203b42010-10-06 10:11:56 +0000282 Similar to :c:func:`PyErr_SetFromWindowsErrWithFilename`, with an additional
Georg Brandl116aa622007-08-15 14:28:22 +0000283 parameter specifying the exception type to be raised. Availability: Windows.
284
Georg Brandlf4095832012-04-24 19:16:24 +0200285
Brian Curtin09b86d12012-04-17 16:57:09 -0500286.. c:function:: PyObject* PyErr_SetImportError(PyObject *msg, PyObject *name, PyObject *path)
Brian Curtinbd439742012-04-16 15:14:36 -0500287
288 This is a convenience function to raise :exc:`ImportError`. *msg* will be
Brian Curtin09b86d12012-04-17 16:57:09 -0500289 set as the exception's message string. *name* and *path*, both of which can
290 be ``NULL``, will be set as the :exc:`ImportError`'s respective ``name``
291 and ``path`` attributes.
Brian Curtinbd439742012-04-16 15:14:36 -0500292
Brian Curtinbded8942012-04-16 18:14:09 -0500293 .. versionadded:: 3.3
Georg Brandl116aa622007-08-15 14:28:22 +0000294
Georg Brandlf4095832012-04-24 19:16:24 +0200295
Victor Stinner14e461d2013-08-26 22:28:21 +0200296.. c:function:: void PyErr_SyntaxLocationObject(PyObject *filename, int lineno, int col_offset)
Benjamin Peterson2c539712010-09-20 22:42:10 +0000297
298 Set file, line, and offset information for the current exception. If the
299 current exception is not a :exc:`SyntaxError`, then it sets additional
300 attributes, which make the exception printing subsystem think the exception
Victor Stinner14e461d2013-08-26 22:28:21 +0200301 is a :exc:`SyntaxError`.
Benjamin Peterson2c539712010-09-20 22:42:10 +0000302
Victor Stinner14e461d2013-08-26 22:28:21 +0200303.. versionadded:: 3.4
304
305
306.. c:function:: void PyErr_SyntaxLocationEx(char *filename, int lineno, int col_offset)
307
308 Like :c:func:`PyErr_SyntaxLocationObject`, but *filename* is a byte string
309 decoded from the filesystem encoding (:func:`os.fsdecode`).
310
311.. versionadded:: 3.2
Benjamin Petersonb5d23b42010-09-21 21:29:26 +0000312
Benjamin Peterson2c539712010-09-20 22:42:10 +0000313
Georg Brandl60203b42010-10-06 10:11:56 +0000314.. c:function:: void PyErr_SyntaxLocation(char *filename, int lineno)
Benjamin Peterson2c539712010-09-20 22:42:10 +0000315
Victor Stinner14e461d2013-08-26 22:28:21 +0200316 Like :c:func:`PyErr_SyntaxLocationEx`, but the col_offset parameter is
Benjamin Peterson2c539712010-09-20 22:42:10 +0000317 omitted.
318
319
Georg Brandl60203b42010-10-06 10:11:56 +0000320.. c:function:: void PyErr_BadInternalCall()
Georg Brandl116aa622007-08-15 14:28:22 +0000321
Benjamin Peterson5c6d7872009-02-06 02:40:07 +0000322 This is a shorthand for ``PyErr_SetString(PyExc_SystemError, message)``,
323 where *message* indicates that an internal operation (e.g. a Python/C API
324 function) was invoked with an illegal argument. It is mostly for internal
325 use.
Georg Brandl116aa622007-08-15 14:28:22 +0000326
327
Georg Brandl60203b42010-10-06 10:11:56 +0000328.. c:function:: int PyErr_WarnEx(PyObject *category, char *message, int stack_level)
Georg Brandl116aa622007-08-15 14:28:22 +0000329
330 Issue a warning message. The *category* argument is a warning category (see
Victor Stinner555a24f2010-12-27 01:49:26 +0000331 below) or *NULL*; the *message* argument is an UTF-8 encoded string. *stack_level* is a
Georg Brandl116aa622007-08-15 14:28:22 +0000332 positive number giving a number of stack frames; the warning will be issued from
Victor Stinner4a2b7a12010-08-13 14:03:48 +0000333 the currently executing line of code in that stack frame. A *stack_level* of 1
Georg Brandl60203b42010-10-06 10:11:56 +0000334 is the function calling :c:func:`PyErr_WarnEx`, 2 is the function above that,
Georg Brandl116aa622007-08-15 14:28:22 +0000335 and so forth.
336
337 This function normally prints a warning message to *sys.stderr*; however, it is
338 also possible that the user has specified that warnings are to be turned into
339 errors, and in that case this will raise an exception. It is also possible that
340 the function raises an exception because of a problem with the warning machinery
341 (the implementation imports the :mod:`warnings` module to do the heavy lifting).
342 The return value is ``0`` if no exception is raised, or ``-1`` if an exception
343 is raised. (It is not possible to determine whether a warning message is
344 actually printed, nor what the reason is for the exception; this is
345 intentional.) If an exception is raised, the caller should do its normal
Georg Brandl60203b42010-10-06 10:11:56 +0000346 exception handling (for example, :c:func:`Py_DECREF` owned references and return
Georg Brandl116aa622007-08-15 14:28:22 +0000347 an error value).
348
Georg Brandl60203b42010-10-06 10:11:56 +0000349 Warning categories must be subclasses of :c:data:`Warning`; the default warning
350 category is :c:data:`RuntimeWarning`. The standard Python warning categories are
Georg Brandl116aa622007-08-15 14:28:22 +0000351 available as global variables whose names are ``PyExc_`` followed by the Python
Georg Brandl60203b42010-10-06 10:11:56 +0000352 exception name. These have the type :c:type:`PyObject\*`; they are all class
353 objects. Their names are :c:data:`PyExc_Warning`, :c:data:`PyExc_UserWarning`,
354 :c:data:`PyExc_UnicodeWarning`, :c:data:`PyExc_DeprecationWarning`,
355 :c:data:`PyExc_SyntaxWarning`, :c:data:`PyExc_RuntimeWarning`, and
356 :c:data:`PyExc_FutureWarning`. :c:data:`PyExc_Warning` is a subclass of
357 :c:data:`PyExc_Exception`; the other warning categories are subclasses of
358 :c:data:`PyExc_Warning`.
Georg Brandl116aa622007-08-15 14:28:22 +0000359
360 For information about warning control, see the documentation for the
361 :mod:`warnings` module and the :option:`-W` option in the command line
362 documentation. There is no C API for warning control.
363
364
Victor Stinner14e461d2013-08-26 22:28:21 +0200365.. c:function:: int PyErr_WarnExplicitObject(PyObject *category, PyObject *message, PyObject *filename, int lineno, PyObject *module, PyObject *registry)
Georg Brandl116aa622007-08-15 14:28:22 +0000366
367 Issue a warning message with explicit control over all warning attributes. This
368 is a straightforward wrapper around the Python function
369 :func:`warnings.warn_explicit`, see there for more information. The *module*
370 and *registry* arguments may be set to *NULL* to get the default effect
Victor Stinner14e461d2013-08-26 22:28:21 +0200371 described there.
372
373 .. versionadded:: 3.4
374
375
376.. c:function:: int PyErr_WarnExplicit(PyObject *category, const char *message, const char *filename, int lineno, const char *module, PyObject *registry)
377
378 Similar to :c:func:`PyErr_WarnExplicitObject` except that *message* and
379 *module* are UTF-8 encoded strings, and *filename* is decoded from the
380 filesystem encoding (:func:`os.fsdecode`).
Georg Brandl116aa622007-08-15 14:28:22 +0000381
382
Georg Brandl60203b42010-10-06 10:11:56 +0000383.. c:function:: int PyErr_WarnFormat(PyObject *category, Py_ssize_t stack_level, const char *format, ...)
Victor Stinner4a2b7a12010-08-13 14:03:48 +0000384
Georg Brandl60203b42010-10-06 10:11:56 +0000385 Function similar to :c:func:`PyErr_WarnEx`, but use
Victor Stinner555a24f2010-12-27 01:49:26 +0000386 :c:func:`PyUnicode_FromFormat` to format the warning message. *format* is
387 an ASCII-encoded string.
Victor Stinner4a2b7a12010-08-13 14:03:48 +0000388
389 .. versionadded:: 3.2
390
Georg Brandlf4095832012-04-24 19:16:24 +0200391
Georg Brandl60203b42010-10-06 10:11:56 +0000392.. c:function:: int PyErr_CheckSignals()
Georg Brandl116aa622007-08-15 14:28:22 +0000393
394 .. index::
395 module: signal
396 single: SIGINT
397 single: KeyboardInterrupt (built-in exception)
398
399 This function interacts with Python's signal handling. It checks whether a
400 signal has been sent to the processes and if so, invokes the corresponding
401 signal handler. If the :mod:`signal` module is supported, this can invoke a
402 signal handler written in Python. In all cases, the default effect for
403 :const:`SIGINT` is to raise the :exc:`KeyboardInterrupt` exception. If an
404 exception is raised the error indicator is set and the function returns ``-1``;
405 otherwise the function returns ``0``. The error indicator may or may not be
406 cleared if it was previously set.
407
408
Georg Brandl60203b42010-10-06 10:11:56 +0000409.. c:function:: void PyErr_SetInterrupt()
Georg Brandl116aa622007-08-15 14:28:22 +0000410
411 .. index::
412 single: SIGINT
413 single: KeyboardInterrupt (built-in exception)
414
415 This function simulates the effect of a :const:`SIGINT` signal arriving --- the
Georg Brandl60203b42010-10-06 10:11:56 +0000416 next time :c:func:`PyErr_CheckSignals` is called, :exc:`KeyboardInterrupt` will
Georg Brandl116aa622007-08-15 14:28:22 +0000417 be raised. It may be called without holding the interpreter lock.
418
419 .. % XXX This was described as obsolete, but is used in
Georg Brandl2067bfd2008-05-25 13:05:15 +0000420 .. % _thread.interrupt_main() (used from IDLE), so it's still needed.
Georg Brandl116aa622007-08-15 14:28:22 +0000421
422
Georg Brandl60203b42010-10-06 10:11:56 +0000423.. c:function:: int PySignal_SetWakeupFd(int fd)
Christian Heimes5fb7c2a2007-12-24 08:52:31 +0000424
425 This utility function specifies a file descriptor to which a ``'\0'`` byte will
426 be written whenever a signal is received. It returns the previous such file
427 descriptor. The value ``-1`` disables the feature; this is the initial state.
428 This is equivalent to :func:`signal.set_wakeup_fd` in Python, but without any
429 error checking. *fd* should be a valid file descriptor. The function should
430 only be called from the main thread.
431
432
Georg Brandl60203b42010-10-06 10:11:56 +0000433.. c:function:: PyObject* PyErr_NewException(char *name, PyObject *base, PyObject *dict)
Georg Brandl116aa622007-08-15 14:28:22 +0000434
Georg Brandl325eb472011-07-13 15:59:24 +0200435 This utility function creates and returns a new exception class. The *name*
Georg Brandl116aa622007-08-15 14:28:22 +0000436 argument must be the name of the new exception, a C string of the form
Georg Brandl325eb472011-07-13 15:59:24 +0200437 ``module.classname``. The *base* and *dict* arguments are normally *NULL*.
438 This creates a class object derived from :exc:`Exception` (accessible in C as
Georg Brandl60203b42010-10-06 10:11:56 +0000439 :c:data:`PyExc_Exception`).
Georg Brandl116aa622007-08-15 14:28:22 +0000440
441 The :attr:`__module__` attribute of the new class is set to the first part (up
442 to the last dot) of the *name* argument, and the class name is set to the last
443 part (after the last dot). The *base* argument can be used to specify alternate
444 base classes; it can either be only one class or a tuple of classes. The *dict*
445 argument can be used to specify a dictionary of class variables and methods.
446
447
Georg Brandl60203b42010-10-06 10:11:56 +0000448.. c:function:: PyObject* PyErr_NewExceptionWithDoc(char *name, char *doc, PyObject *base, PyObject *dict)
Georg Brandl1e28a272009-12-28 08:41:01 +0000449
Georg Brandl60203b42010-10-06 10:11:56 +0000450 Same as :c:func:`PyErr_NewException`, except that the new exception class can
Georg Brandl1e28a272009-12-28 08:41:01 +0000451 easily be given a docstring: If *doc* is non-*NULL*, it will be used as the
452 docstring for the exception class.
453
454 .. versionadded:: 3.2
455
456
Georg Brandl60203b42010-10-06 10:11:56 +0000457.. c:function:: void PyErr_WriteUnraisable(PyObject *obj)
Georg Brandl116aa622007-08-15 14:28:22 +0000458
459 This utility function prints a warning message to ``sys.stderr`` when an
460 exception has been set but it is impossible for the interpreter to actually
461 raise the exception. It is used, for example, when an exception occurs in an
462 :meth:`__del__` method.
463
464 The function is called with a single argument *obj* that identifies the context
465 in which the unraisable exception occurred. The repr of *obj* will be printed in
466 the warning message.
467
468
Georg Brandlab6f2f62009-03-31 04:16:10 +0000469Exception Objects
470=================
471
Georg Brandl60203b42010-10-06 10:11:56 +0000472.. c:function:: PyObject* PyException_GetTraceback(PyObject *ex)
Georg Brandlab6f2f62009-03-31 04:16:10 +0000473
474 Return the traceback associated with the exception as a new reference, as
475 accessible from Python through :attr:`__traceback__`. If there is no
476 traceback associated, this returns *NULL*.
477
478
Georg Brandl60203b42010-10-06 10:11:56 +0000479.. c:function:: int PyException_SetTraceback(PyObject *ex, PyObject *tb)
Georg Brandlab6f2f62009-03-31 04:16:10 +0000480
481 Set the traceback associated with the exception to *tb*. Use ``Py_None`` to
482 clear it.
483
484
Georg Brandl60203b42010-10-06 10:11:56 +0000485.. c:function:: PyObject* PyException_GetContext(PyObject *ex)
Georg Brandlab6f2f62009-03-31 04:16:10 +0000486
487 Return the context (another exception instance during whose handling *ex* was
488 raised) associated with the exception as a new reference, as accessible from
489 Python through :attr:`__context__`. If there is no context associated, this
490 returns *NULL*.
491
492
Georg Brandl60203b42010-10-06 10:11:56 +0000493.. c:function:: void PyException_SetContext(PyObject *ex, PyObject *ctx)
Georg Brandlab6f2f62009-03-31 04:16:10 +0000494
495 Set the context associated with the exception to *ctx*. Use *NULL* to clear
496 it. There is no type check to make sure that *ctx* is an exception instance.
497 This steals a reference to *ctx*.
498
499
Georg Brandl60203b42010-10-06 10:11:56 +0000500.. c:function:: PyObject* PyException_GetCause(PyObject *ex)
Georg Brandlab6f2f62009-03-31 04:16:10 +0000501
Nick Coghlanab7bf212012-02-26 17:49:52 +1000502 Return the cause (either an exception instance, or :const:`None`,
503 set by ``raise ... from ...``) associated with the exception as a new
504 reference, as accessible from Python through :attr:`__cause__`.
505
Georg Brandlab6f2f62009-03-31 04:16:10 +0000506
Georg Brandl60203b42010-10-06 10:11:56 +0000507.. c:function:: void PyException_SetCause(PyObject *ex, PyObject *ctx)
Georg Brandlab6f2f62009-03-31 04:16:10 +0000508
509 Set the cause associated with the exception to *ctx*. Use *NULL* to clear
Nick Coghlanab7bf212012-02-26 17:49:52 +1000510 it. There is no type check to make sure that *ctx* is either an exception
511 instance or :const:`None`. This steals a reference to *ctx*.
512
Benjamin Petersond5a1c442012-05-14 22:09:31 -0700513 :attr:`__suppress_context__` is implicitly set to ``True`` by this function.
Georg Brandlab6f2f62009-03-31 04:16:10 +0000514
515
Georg Brandl5a932652010-11-23 07:54:19 +0000516.. _unicodeexceptions:
517
518Unicode Exception Objects
519=========================
520
521The following functions are used to create and modify Unicode exceptions from C.
522
523.. 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)
524
525 Create a :class:`UnicodeDecodeError` object with the attributes *encoding*,
Victor Stinner555a24f2010-12-27 01:49:26 +0000526 *object*, *length*, *start*, *end* and *reason*. *encoding* and *reason* are
527 UTF-8 encoded strings.
Georg Brandl5a932652010-11-23 07:54:19 +0000528
529.. 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)
530
531 Create a :class:`UnicodeEncodeError` object with the attributes *encoding*,
Victor Stinner555a24f2010-12-27 01:49:26 +0000532 *object*, *length*, *start*, *end* and *reason*. *encoding* and *reason* are
533 UTF-8 encoded strings.
Georg Brandl5a932652010-11-23 07:54:19 +0000534
535.. c:function:: PyObject* PyUnicodeTranslateError_Create(const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
536
537 Create a :class:`UnicodeTranslateError` object with the attributes *object*,
Victor Stinner555a24f2010-12-27 01:49:26 +0000538 *length*, *start*, *end* and *reason*. *reason* is an UTF-8 encoded string.
Georg Brandl5a932652010-11-23 07:54:19 +0000539
540.. c:function:: PyObject* PyUnicodeDecodeError_GetEncoding(PyObject *exc)
541 PyObject* PyUnicodeEncodeError_GetEncoding(PyObject *exc)
542
543 Return the *encoding* attribute of the given exception object.
544
545.. c:function:: PyObject* PyUnicodeDecodeError_GetObject(PyObject *exc)
546 PyObject* PyUnicodeEncodeError_GetObject(PyObject *exc)
547 PyObject* PyUnicodeTranslateError_GetObject(PyObject *exc)
548
549 Return the *object* attribute of the given exception object.
550
551.. c:function:: int PyUnicodeDecodeError_GetStart(PyObject *exc, Py_ssize_t *start)
552 int PyUnicodeEncodeError_GetStart(PyObject *exc, Py_ssize_t *start)
553 int PyUnicodeTranslateError_GetStart(PyObject *exc, Py_ssize_t *start)
554
555 Get the *start* attribute of the given exception object and place it into
556 *\*start*. *start* must not be *NULL*. Return ``0`` on success, ``-1`` on
557 failure.
558
559.. c:function:: int PyUnicodeDecodeError_SetStart(PyObject *exc, Py_ssize_t start)
560 int PyUnicodeEncodeError_SetStart(PyObject *exc, Py_ssize_t start)
561 int PyUnicodeTranslateError_SetStart(PyObject *exc, Py_ssize_t start)
562
563 Set the *start* attribute of the given exception object to *start*. Return
564 ``0`` on success, ``-1`` on failure.
565
566.. c:function:: int PyUnicodeDecodeError_GetEnd(PyObject *exc, Py_ssize_t *end)
567 int PyUnicodeEncodeError_GetEnd(PyObject *exc, Py_ssize_t *end)
568 int PyUnicodeTranslateError_GetEnd(PyObject *exc, Py_ssize_t *end)
569
570 Get the *end* attribute of the given exception object and place it into
571 *\*end*. *end* must not be *NULL*. Return ``0`` on success, ``-1`` on
572 failure.
573
574.. c:function:: int PyUnicodeDecodeError_SetEnd(PyObject *exc, Py_ssize_t end)
575 int PyUnicodeEncodeError_SetEnd(PyObject *exc, Py_ssize_t end)
576 int PyUnicodeTranslateError_SetEnd(PyObject *exc, Py_ssize_t end)
577
578 Set the *end* attribute of the given exception object to *end*. Return ``0``
579 on success, ``-1`` on failure.
580
581.. c:function:: PyObject* PyUnicodeDecodeError_GetReason(PyObject *exc)
582 PyObject* PyUnicodeEncodeError_GetReason(PyObject *exc)
583 PyObject* PyUnicodeTranslateError_GetReason(PyObject *exc)
584
585 Return the *reason* attribute of the given exception object.
586
587.. c:function:: int PyUnicodeDecodeError_SetReason(PyObject *exc, const char *reason)
588 int PyUnicodeEncodeError_SetReason(PyObject *exc, const char *reason)
589 int PyUnicodeTranslateError_SetReason(PyObject *exc, const char *reason)
590
591 Set the *reason* attribute of the given exception object to *reason*. Return
592 ``0`` on success, ``-1`` on failure.
593
594
Georg Brandl93dc9eb2010-03-14 10:56:14 +0000595Recursion Control
596=================
597
598These two functions provide a way to perform safe recursive calls at the C
599level, both in the core and in extension modules. They are needed if the
600recursive code does not necessarily invoke Python code (which tracks its
601recursion depth automatically).
602
Georg Brandl60203b42010-10-06 10:11:56 +0000603.. c:function:: int Py_EnterRecursiveCall(char *where)
Georg Brandl93dc9eb2010-03-14 10:56:14 +0000604
605 Marks a point where a recursive C-level call is about to be performed.
606
Ezio Melottif1064492011-10-19 11:06:26 +0300607 If :const:`USE_STACKCHECK` is defined, this function checks if the OS
Georg Brandl60203b42010-10-06 10:11:56 +0000608 stack overflowed using :c:func:`PyOS_CheckStack`. In this is the case, it
Georg Brandl93dc9eb2010-03-14 10:56:14 +0000609 sets a :exc:`MemoryError` and returns a nonzero value.
610
611 The function then checks if the recursion limit is reached. If this is the
612 case, a :exc:`RuntimeError` is set and a nonzero value is returned.
613 Otherwise, zero is returned.
614
615 *where* should be a string such as ``" in instance check"`` to be
616 concatenated to the :exc:`RuntimeError` message caused by the recursion depth
617 limit.
618
Georg Brandl60203b42010-10-06 10:11:56 +0000619.. c:function:: void Py_LeaveRecursiveCall()
Georg Brandl93dc9eb2010-03-14 10:56:14 +0000620
Georg Brandl60203b42010-10-06 10:11:56 +0000621 Ends a :c:func:`Py_EnterRecursiveCall`. Must be called once for each
622 *successful* invocation of :c:func:`Py_EnterRecursiveCall`.
Georg Brandl93dc9eb2010-03-14 10:56:14 +0000623
Antoine Pitrou39668f52013-08-01 21:12:45 +0200624Properly implementing :c:member:`~PyTypeObject.tp_repr` for container types requires
Daniel Stutzbach7cb30512010-12-17 16:31:32 +0000625special recursion handling. In addition to protecting the stack,
Antoine Pitrou39668f52013-08-01 21:12:45 +0200626:c:member:`~PyTypeObject.tp_repr` also needs to track objects to prevent cycles. The
Daniel Stutzbach7cb30512010-12-17 16:31:32 +0000627following two functions facilitate this functionality. Effectively,
628these are the C equivalent to :func:`reprlib.recursive_repr`.
629
Daniel Stutzbachc5895dc2010-12-17 22:28:07 +0000630.. c:function:: int Py_ReprEnter(PyObject *object)
Daniel Stutzbach7cb30512010-12-17 16:31:32 +0000631
Antoine Pitrou39668f52013-08-01 21:12:45 +0200632 Called at the beginning of the :c:member:`~PyTypeObject.tp_repr` implementation to
Daniel Stutzbach7cb30512010-12-17 16:31:32 +0000633 detect cycles.
634
635 If the object has already been processed, the function returns a
Antoine Pitrou39668f52013-08-01 21:12:45 +0200636 positive integer. In that case the :c:member:`~PyTypeObject.tp_repr` implementation
Daniel Stutzbach7cb30512010-12-17 16:31:32 +0000637 should return a string object indicating a cycle. As examples,
638 :class:`dict` objects return ``{...}`` and :class:`list` objects
639 return ``[...]``.
640
641 The function will return a negative integer if the recursion limit
Antoine Pitrou39668f52013-08-01 21:12:45 +0200642 is reached. In that case the :c:member:`~PyTypeObject.tp_repr` implementation should
Daniel Stutzbach7cb30512010-12-17 16:31:32 +0000643 typically return ``NULL``.
644
Antoine Pitrou39668f52013-08-01 21:12:45 +0200645 Otherwise, the function returns zero and the :c:member:`~PyTypeObject.tp_repr`
Daniel Stutzbach7cb30512010-12-17 16:31:32 +0000646 implementation can continue normally.
647
648.. c:function:: void Py_ReprLeave(PyObject *object)
649
Daniel Stutzbachc5895dc2010-12-17 22:28:07 +0000650 Ends a :c:func:`Py_ReprEnter`. Must be called once for each
651 invocation of :c:func:`Py_ReprEnter` that returns zero.
Daniel Stutzbach7cb30512010-12-17 16:31:32 +0000652
Georg Brandl93dc9eb2010-03-14 10:56:14 +0000653
Georg Brandl116aa622007-08-15 14:28:22 +0000654.. _standardexceptions:
655
656Standard Exceptions
657===================
658
659All standard Python exceptions are available as global variables whose names are
660``PyExc_`` followed by the Python exception name. These have the type
Georg Brandl60203b42010-10-06 10:11:56 +0000661:c:type:`PyObject\*`; they are all class objects. For completeness, here are all
Georg Brandl116aa622007-08-15 14:28:22 +0000662the variables:
663
Antoine Pitrou9a4a3422011-10-12 18:28:01 +0200664+-----------------------------------------+---------------------------------+----------+
665| C Name | Python Name | Notes |
666+=========================================+=================================+==========+
667| :c:data:`PyExc_BaseException` | :exc:`BaseException` | \(1) |
668+-----------------------------------------+---------------------------------+----------+
669| :c:data:`PyExc_Exception` | :exc:`Exception` | \(1) |
670+-----------------------------------------+---------------------------------+----------+
671| :c:data:`PyExc_ArithmeticError` | :exc:`ArithmeticError` | \(1) |
672+-----------------------------------------+---------------------------------+----------+
673| :c:data:`PyExc_LookupError` | :exc:`LookupError` | \(1) |
674+-----------------------------------------+---------------------------------+----------+
675| :c:data:`PyExc_AssertionError` | :exc:`AssertionError` | |
676+-----------------------------------------+---------------------------------+----------+
677| :c:data:`PyExc_AttributeError` | :exc:`AttributeError` | |
678+-----------------------------------------+---------------------------------+----------+
679| :c:data:`PyExc_BlockingIOError` | :exc:`BlockingIOError` | |
680+-----------------------------------------+---------------------------------+----------+
681| :c:data:`PyExc_BrokenPipeError` | :exc:`BrokenPipeError` | |
682+-----------------------------------------+---------------------------------+----------+
683| :c:data:`PyExc_ChildProcessError` | :exc:`ChildProcessError` | |
684+-----------------------------------------+---------------------------------+----------+
685| :c:data:`PyExc_ConnectionError` | :exc:`ConnectionError` | |
686+-----------------------------------------+---------------------------------+----------+
687| :c:data:`PyExc_ConnectionAbortedError` | :exc:`ConnectionAbortedError` | |
688+-----------------------------------------+---------------------------------+----------+
689| :c:data:`PyExc_ConnectionRefusedError` | :exc:`ConnectionRefusedError` | |
690+-----------------------------------------+---------------------------------+----------+
691| :c:data:`PyExc_ConnectionResetError` | :exc:`ConnectionResetError` | |
692+-----------------------------------------+---------------------------------+----------+
693| :c:data:`PyExc_FileExistsError` | :exc:`FileExistsError` | |
694+-----------------------------------------+---------------------------------+----------+
695| :c:data:`PyExc_FileNotFoundError` | :exc:`FileNotFoundError` | |
696+-----------------------------------------+---------------------------------+----------+
697| :c:data:`PyExc_EOFError` | :exc:`EOFError` | |
698+-----------------------------------------+---------------------------------+----------+
699| :c:data:`PyExc_FloatingPointError` | :exc:`FloatingPointError` | |
700+-----------------------------------------+---------------------------------+----------+
701| :c:data:`PyExc_ImportError` | :exc:`ImportError` | |
702+-----------------------------------------+---------------------------------+----------+
703| :c:data:`PyExc_IndexError` | :exc:`IndexError` | |
704+-----------------------------------------+---------------------------------+----------+
705| :c:data:`PyExc_InterruptedError` | :exc:`InterruptedError` | |
706+-----------------------------------------+---------------------------------+----------+
707| :c:data:`PyExc_IsADirectoryError` | :exc:`IsADirectoryError` | |
708+-----------------------------------------+---------------------------------+----------+
709| :c:data:`PyExc_KeyError` | :exc:`KeyError` | |
710+-----------------------------------------+---------------------------------+----------+
711| :c:data:`PyExc_KeyboardInterrupt` | :exc:`KeyboardInterrupt` | |
712+-----------------------------------------+---------------------------------+----------+
713| :c:data:`PyExc_MemoryError` | :exc:`MemoryError` | |
714+-----------------------------------------+---------------------------------+----------+
715| :c:data:`PyExc_NameError` | :exc:`NameError` | |
716+-----------------------------------------+---------------------------------+----------+
717| :c:data:`PyExc_NotADirectoryError` | :exc:`NotADirectoryError` | |
718+-----------------------------------------+---------------------------------+----------+
719| :c:data:`PyExc_NotImplementedError` | :exc:`NotImplementedError` | |
720+-----------------------------------------+---------------------------------+----------+
721| :c:data:`PyExc_OSError` | :exc:`OSError` | \(1) |
722+-----------------------------------------+---------------------------------+----------+
723| :c:data:`PyExc_OverflowError` | :exc:`OverflowError` | |
724+-----------------------------------------+---------------------------------+----------+
725| :c:data:`PyExc_PermissionError` | :exc:`PermissionError` | |
726+-----------------------------------------+---------------------------------+----------+
727| :c:data:`PyExc_ProcessLookupError` | :exc:`ProcessLookupError` | |
728+-----------------------------------------+---------------------------------+----------+
729| :c:data:`PyExc_ReferenceError` | :exc:`ReferenceError` | \(2) |
730+-----------------------------------------+---------------------------------+----------+
731| :c:data:`PyExc_RuntimeError` | :exc:`RuntimeError` | |
732+-----------------------------------------+---------------------------------+----------+
733| :c:data:`PyExc_SyntaxError` | :exc:`SyntaxError` | |
734+-----------------------------------------+---------------------------------+----------+
735| :c:data:`PyExc_SystemError` | :exc:`SystemError` | |
736+-----------------------------------------+---------------------------------+----------+
737| :c:data:`PyExc_TimeoutError` | :exc:`TimeoutError` | |
738+-----------------------------------------+---------------------------------+----------+
739| :c:data:`PyExc_SystemExit` | :exc:`SystemExit` | |
740+-----------------------------------------+---------------------------------+----------+
741| :c:data:`PyExc_TypeError` | :exc:`TypeError` | |
742+-----------------------------------------+---------------------------------+----------+
743| :c:data:`PyExc_ValueError` | :exc:`ValueError` | |
744+-----------------------------------------+---------------------------------+----------+
745| :c:data:`PyExc_ZeroDivisionError` | :exc:`ZeroDivisionError` | |
746+-----------------------------------------+---------------------------------+----------+
747
748.. versionadded:: 3.3
749 :c:data:`PyExc_BlockingIOError`, :c:data:`PyExc_BrokenPipeError`,
750 :c:data:`PyExc_ChildProcessError`, :c:data:`PyExc_ConnectionError`,
751 :c:data:`PyExc_ConnectionAbortedError`, :c:data:`PyExc_ConnectionRefusedError`,
752 :c:data:`PyExc_ConnectionResetError`, :c:data:`PyExc_FileExistsError`,
753 :c:data:`PyExc_FileNotFoundError`, :c:data:`PyExc_InterruptedError`,
754 :c:data:`PyExc_IsADirectoryError`, :c:data:`PyExc_NotADirectoryError`,
755 :c:data:`PyExc_PermissionError`, :c:data:`PyExc_ProcessLookupError`
756 and :c:data:`PyExc_TimeoutError` were introduced following :pep:`3151`.
757
758
759These are compatibility aliases to :c:data:`PyExc_OSError`:
760
761+-------------------------------------+----------+
762| C Name | Notes |
763+=====================================+==========+
764| :c:data:`PyExc_EnvironmentError` | |
765+-------------------------------------+----------+
766| :c:data:`PyExc_IOError` | |
767+-------------------------------------+----------+
768| :c:data:`PyExc_WindowsError` | \(3) |
769+-------------------------------------+----------+
770
771.. versionchanged:: 3.3
772 These aliases used to be separate exception types.
773
Georg Brandl116aa622007-08-15 14:28:22 +0000774
775.. index::
776 single: PyExc_BaseException
777 single: PyExc_Exception
778 single: PyExc_ArithmeticError
779 single: PyExc_LookupError
780 single: PyExc_AssertionError
781 single: PyExc_AttributeError
Antoine Pitrou23a580f2011-10-12 18:33:15 +0200782 single: PyExc_BlockingIOError
783 single: PyExc_BrokenPipeError
784 single: PyExc_ConnectionError
785 single: PyExc_ConnectionAbortedError
786 single: PyExc_ConnectionRefusedError
787 single: PyExc_ConnectionResetError
Georg Brandl116aa622007-08-15 14:28:22 +0000788 single: PyExc_EOFError
Antoine Pitrou23a580f2011-10-12 18:33:15 +0200789 single: PyExc_FileExistsError
790 single: PyExc_FileNotFoundError
Georg Brandl116aa622007-08-15 14:28:22 +0000791 single: PyExc_FloatingPointError
Georg Brandl116aa622007-08-15 14:28:22 +0000792 single: PyExc_ImportError
793 single: PyExc_IndexError
Antoine Pitrou23a580f2011-10-12 18:33:15 +0200794 single: PyExc_InterruptedError
795 single: PyExc_IsADirectoryError
Georg Brandl116aa622007-08-15 14:28:22 +0000796 single: PyExc_KeyError
797 single: PyExc_KeyboardInterrupt
798 single: PyExc_MemoryError
799 single: PyExc_NameError
Antoine Pitrou23a580f2011-10-12 18:33:15 +0200800 single: PyExc_NotADirectoryError
Georg Brandl116aa622007-08-15 14:28:22 +0000801 single: PyExc_NotImplementedError
802 single: PyExc_OSError
803 single: PyExc_OverflowError
Antoine Pitrou23a580f2011-10-12 18:33:15 +0200804 single: PyExc_PermissionError
805 single: PyExc_ProcessLookupError
Georg Brandl116aa622007-08-15 14:28:22 +0000806 single: PyExc_ReferenceError
807 single: PyExc_RuntimeError
808 single: PyExc_SyntaxError
809 single: PyExc_SystemError
810 single: PyExc_SystemExit
Antoine Pitrou23a580f2011-10-12 18:33:15 +0200811 single: PyExc_TimeoutError
Georg Brandl116aa622007-08-15 14:28:22 +0000812 single: PyExc_TypeError
813 single: PyExc_ValueError
Georg Brandl116aa622007-08-15 14:28:22 +0000814 single: PyExc_ZeroDivisionError
Antoine Pitrou23a580f2011-10-12 18:33:15 +0200815 single: PyExc_EnvironmentError
816 single: PyExc_IOError
817 single: PyExc_WindowsError
Georg Brandl116aa622007-08-15 14:28:22 +0000818
819Notes:
820
821(1)
822 This is a base class for other standard exceptions.
823
824(2)
825 This is the same as :exc:`weakref.ReferenceError`.
826
827(3)
828 Only defined on Windows; protect code that uses this by testing that the
829 preprocessor macro ``MS_WINDOWS`` is defined.