1.. 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 12exception handling. It works somewhat like the Unix :c:data:`errno` variable: 13there 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 17integer (exception: the :c:func:`PyArg_\*` functions return ``1`` for success and 18``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 30.. index:: 31 single: exc_type (in module sys) 32 single: exc_value (in module sys) 33 single: exc_traceback (in module sys) 34 35The error indicator consists of three Python objects corresponding to the 36Python variables ``sys.exc_type``, ``sys.exc_value`` and ``sys.exc_traceback``. 37API functions exist to interact with the error indicator in various ways. There 38is a separate error indicator for each thread. 39 40.. XXX Order of these should be more thoughtful. 41 Either alphabetical or some kind of structure. 42 43 44.. c:function:: void PyErr_PrintEx(int set_sys_last_vars) 45 46 Print a standard traceback to ``sys.stderr`` and clear the error indicator. 47 Call this function only when the error indicator is set. (Otherwise it will 48 cause a fatal error!) 49 50 If *set_sys_last_vars* is nonzero, the variables :data:`sys.last_type`, 51 :data:`sys.last_value` and :data:`sys.last_traceback` will be set to the 52 type, value and traceback of the printed exception, respectively. 53 54 55.. c:function:: void PyErr_Print() 56 57 Alias for ``PyErr_PrintEx(1)``. 58 59 60.. c:function:: PyObject* PyErr_Occurred() 61 62 Test whether the error indicator is set. If set, return the exception *type* 63 (the first argument to the last call to one of the :c:func:`PyErr_Set\*` 64 functions or to :c:func:`PyErr_Restore`). If not set, return *NULL*. You do not 65 own a reference to the return value, so you do not need to :c:func:`Py_DECREF` 66 it. 67 68 .. note:: 69 70 Do not compare the return value to a specific exception; use 71 :c:func:`PyErr_ExceptionMatches` instead, shown below. (The comparison could 72 easily fail since the exception may be an instance instead of a class, in the 73 case of a class exception, or it may be a subclass of the expected exception.) 74 75 76.. c:function:: int PyErr_ExceptionMatches(PyObject *exc) 77 78 Equivalent to ``PyErr_GivenExceptionMatches(PyErr_Occurred(), exc)``. This 79 should only be called when an exception is actually set; a memory access 80 violation will occur if no exception has been raised. 81 82 83.. c:function:: int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc) 84 85 Return true if the *given* exception matches the exception in *exc*. If 86 *exc* is a class object, this also returns true when *given* is an instance 87 of a subclass. If *exc* is a tuple, all exceptions in the tuple (and 88 recursively in subtuples) are searched for a match. 89 90 91.. c:function:: void PyErr_NormalizeException(PyObject**exc, PyObject**val, PyObject**tb) 92 93 Under certain circumstances, the values returned by :c:func:`PyErr_Fetch` below 94 can be "unnormalized", meaning that ``*exc`` is a class object but ``*val`` is 95 not an instance of the same class. This function can be used to instantiate 96 the class in that case. If the values are already normalized, nothing happens. 97 The delayed normalization is implemented to improve performance. 98 99 100.. c:function:: void PyErr_Clear() 101 102 Clear the error indicator. If the error indicator is not set, there is no 103 effect. 104 105 106.. c:function:: void PyErr_Fetch(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback) 107 108 Retrieve the error indicator into three variables whose addresses are passed. 109 If the error indicator is not set, set all three variables to *NULL*. If it is 110 set, it will be cleared and you own a reference to each object retrieved. The 111 value and traceback object may be *NULL* even when the type object is not. 112 113 .. note:: 114 115 This function is normally only used by code that needs to handle exceptions or 116 by code that needs to save and restore the error indicator temporarily. 117 118 119.. c:function:: void PyErr_Restore(PyObject *type, PyObject *value, PyObject *traceback) 120 121 Set the error indicator from the three objects. If the error indicator is 122 already set, it is cleared first. If the objects are *NULL*, the error 123 indicator is cleared. Do not pass a *NULL* type and non-*NULL* value or 124 traceback. The exception type should be a class. Do not pass an invalid 125 exception type or value. (Violating these rules will cause subtle problems 126 later.) This call takes away a reference to each object: you must own a 127 reference to each object before the call and after the call you no longer own 128 these references. (If you don't understand this, don't use this function. I 129 warned you.) 130 131 .. note:: 132 133 This function is normally only used by code that needs to save and restore the 134 error indicator temporarily; use :c:func:`PyErr_Fetch` to save the current 135 exception state. 136 137 138.. c:function:: void PyErr_SetString(PyObject *type, const char *message) 139 140 This is the most common way to set the error indicator. The first argument 141 specifies the exception type; it is normally one of the standard exceptions, 142 e.g. :c:data:`PyExc_RuntimeError`. You need not increment its reference count. 143 The second argument is an error message; it is converted to a string object. 144 145 146.. c:function:: void PyErr_SetObject(PyObject *type, PyObject *value) 147 148 This function is similar to :c:func:`PyErr_SetString` but lets you specify an 149 arbitrary Python object for the "value" of the exception. 150 151 152.. c:function:: PyObject* PyErr_Format(PyObject *exception, const char *format, ...) 153 154 This function sets the error indicator and returns *NULL*. *exception* 155 should be a Python exception class. The *format* and subsequent 156 parameters help format the error message; they have the same meaning and 157 values as in :c:func:`PyString_FromFormat`. 158 159 160.. c:function:: void PyErr_SetNone(PyObject *type) 161 162 This is a shorthand for ``PyErr_SetObject(type, Py_None)``. 163 164 165.. c:function:: int PyErr_BadArgument() 166 167 This is a shorthand for ``PyErr_SetString(PyExc_TypeError, message)``, where 168 *message* indicates that a built-in operation was invoked with an illegal 169 argument. It is mostly for internal use. 170 171 172.. c:function:: PyObject* PyErr_NoMemory() 173 174 This is a shorthand for ``PyErr_SetNone(PyExc_MemoryError)``; it returns *NULL* 175 so an object allocation function can write ``return PyErr_NoMemory();`` when it 176 runs out of memory. 177 178 179.. c:function:: PyObject* PyErr_SetFromErrno(PyObject *type) 180 181 .. index:: single: strerror() 182 183 This is a convenience function to raise an exception when a C library function 184 has returned an error and set the C variable :c:data:`errno`. It constructs a 185 tuple object whose first item is the integer :c:data:`errno` value and whose 186 second item is the corresponding error message (gotten from :c:func:`strerror`), 187 and then calls ``PyErr_SetObject(type, object)``. On Unix, when the 188 :c:data:`errno` value is :const:`EINTR`, indicating an interrupted system call, 189 this calls :c:func:`PyErr_CheckSignals`, and if that set the error indicator, 190 leaves it set to that. The function always returns *NULL*, so a wrapper 191 function around a system call can write ``return PyErr_SetFromErrno(type);`` 192 when the system call returns an error. 193 194 195.. c:function:: PyObject* PyErr_SetFromErrnoWithFilenameObject(PyObject *type, PyObject *filenameObject) 196 197 Similar to :c:func:`PyErr_SetFromErrno`, with the additional behavior that if 198 *filenameObject* is not *NULL*, it is passed to the constructor of *type* as 199 a third parameter. In the case of exceptions such as :exc:`IOError` and 200 :exc:`OSError`, this is used to define the :attr:`filename` attribute of the 201 exception instance. 202 203 204.. c:function:: PyObject* PyErr_SetFromErrnoWithFilename(PyObject *type, const char *filename) 205 206 Similar to :c:func:`PyErr_SetFromErrnoWithFilenameObject`, but the filename 207 is given as a C string. 208 209 210.. c:function:: PyObject* PyErr_SetFromWindowsErr(int ierr) 211 212 This is a convenience function to raise :exc:`WindowsError`. If called with 213 *ierr* of :c:data:`0`, the error code returned by a call to :c:func:`GetLastError` 214 is used instead. It calls the Win32 function :c:func:`FormatMessage` to retrieve 215 the Windows description of error code given by *ierr* or :c:func:`GetLastError`, 216 then it constructs a tuple object whose first item is the *ierr* value and whose 217 second item is the corresponding error message (gotten from 218 :c:func:`FormatMessage`), and then calls ``PyErr_SetObject(PyExc_WindowsError, 219 object)``. This function always returns *NULL*. Availability: Windows. 220 221 222.. c:function:: PyObject* PyErr_SetExcFromWindowsErr(PyObject *type, int ierr) 223 224 Similar to :c:func:`PyErr_SetFromWindowsErr`, with an additional parameter 225 specifying the exception type to be raised. Availability: Windows. 226 227 .. versionadded:: 2.3 228 229 230.. c:function:: PyObject* PyErr_SetFromWindowsErrWithFilenameObject(int ierr, PyObject *filenameObject) 231 232 Similar to :c:func:`PyErr_SetFromWindowsErr`, with the additional behavior that 233 if *filenameObject* is not *NULL*, it is passed to the constructor of 234 :exc:`WindowsError` as a third parameter. Availability: Windows. 235 236 237.. c:function:: PyObject* PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename) 238 239 Similar to :c:func:`PyErr_SetFromWindowsErrWithFilenameObject`, but the 240 filename is given as a C string. Availability: Windows. 241 242 243.. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilenameObject(PyObject *type, int ierr, PyObject *filename) 244 245 Similar to :c:func:`PyErr_SetFromWindowsErrWithFilenameObject`, with an 246 additional parameter specifying the exception type to be raised. 247 Availability: Windows. 248 249 .. versionadded:: 2.3 250 251 252.. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, const char *filename) 253 254 Similar to :c:func:`PyErr_SetFromWindowsErrWithFilename`, with an additional 255 parameter specifying the exception type to be raised. Availability: Windows. 256 257 .. versionadded:: 2.3 258 259 260.. c:function:: void PyErr_BadInternalCall() 261 262 This is a shorthand for ``PyErr_SetString(PyExc_SystemError, message)``, 263 where *message* indicates that an internal operation (e.g. a Python/C API 264 function) was invoked with an illegal argument. It is mostly for internal 265 use. 266 267 268.. c:function:: int PyErr_WarnEx(PyObject *category, char *message, int stacklevel) 269 270 Issue a warning message. The *category* argument is a warning category (see 271 below) or *NULL*; the *message* argument is a message string. *stacklevel* is a 272 positive number giving a number of stack frames; the warning will be issued from 273 the currently executing line of code in that stack frame. A *stacklevel* of 1 274 is the function calling :c:func:`PyErr_WarnEx`, 2 is the function above that, 275 and so forth. 276 277 This function normally prints a warning message to *sys.stderr*; however, it is 278 also possible that the user has specified that warnings are to be turned into 279 errors, and in that case this will raise an exception. It is also possible that 280 the function raises an exception because of a problem with the warning machinery 281 (the implementation imports the :mod:`warnings` module to do the heavy lifting). 282 The return value is ``0`` if no exception is raised, or ``-1`` if an exception 283 is raised. (It is not possible to determine whether a warning message is 284 actually printed, nor what the reason is for the exception; this is 285 intentional.) If an exception is raised, the caller should do its normal 286 exception handling (for example, :c:func:`Py_DECREF` owned references and return 287 an error value). 288 289 Warning categories must be subclasses of :c:data:`PyExc_Warning`; 290 :c:data:`PyExc_Warning` is a subclass of :c:data:`PyExc_Exception`; 291 the default warning category is :c:data:`PyExc_RuntimeWarning`. The standard 292 Python warning categories are available as global variables whose names are 293 enumerated at :ref:`standardwarningcategories`. 294 295 For information about warning control, see the documentation for the 296 :mod:`warnings` module and the :option:`-W` option in the command line 297 documentation. There is no C API for warning control. 298 299 300.. c:function:: int PyErr_Warn(PyObject *category, char *message) 301 302 Issue a warning message. The *category* argument is a warning category (see 303 below) or *NULL*; the *message* argument is a message string. The warning will 304 appear to be issued from the function calling :c:func:`PyErr_Warn`, equivalent to 305 calling :c:func:`PyErr_WarnEx` with a *stacklevel* of 1. 306 307 Deprecated; use :c:func:`PyErr_WarnEx` instead. 308 309 310.. c:function:: int PyErr_WarnExplicit(PyObject *category, const char *message, const char *filename, int lineno, const char *module, PyObject *registry) 311 312 Issue a warning message with explicit control over all warning attributes. This 313 is a straightforward wrapper around the Python function 314 :func:`warnings.warn_explicit`, see there for more information. The *module* 315 and *registry* arguments may be set to *NULL* to get the default effect 316 described there. 317 318 319.. c:function:: int PyErr_WarnPy3k(char *message, int stacklevel) 320 321 Issue a :exc:`DeprecationWarning` with the given *message* and *stacklevel* 322 if the :c:data:`Py_Py3kWarningFlag` flag is enabled. 323 324 .. versionadded:: 2.6 325 326 327.. c:function:: int PyErr_CheckSignals() 328 329 .. index:: 330 module: signal 331 single: SIGINT 332 single: KeyboardInterrupt (built-in exception) 333 334 This function interacts with Python's signal handling. It checks whether a 335 signal has been sent to the processes and if so, invokes the corresponding 336 signal handler. If the :mod:`signal` module is supported, this can invoke a 337 signal handler written in Python. In all cases, the default effect for 338 :const:`SIGINT` is to raise the :exc:`KeyboardInterrupt` exception. If an 339 exception is raised the error indicator is set and the function returns ``-1``; 340 otherwise the function returns ``0``. The error indicator may or may not be 341 cleared if it was previously set. 342 343 344.. c:function:: void PyErr_SetInterrupt() 345 346 .. index:: 347 single: SIGINT 348 single: KeyboardInterrupt (built-in exception) 349 350 This function simulates the effect of a :const:`SIGINT` signal arriving --- the 351 next time :c:func:`PyErr_CheckSignals` is called, :exc:`KeyboardInterrupt` will 352 be raised. It may be called without holding the interpreter lock. 353 354 .. % XXX This was described as obsolete, but is used in 355 .. % thread.interrupt_main() (used from IDLE), so it's still needed. 356 357 358.. c:function:: int PySignal_SetWakeupFd(int fd) 359 360 This utility function specifies a file descriptor to which a ``'\0'`` byte will 361 be written whenever a signal is received. It returns the previous such file 362 descriptor. The value ``-1`` disables the feature; this is the initial state. 363 This is equivalent to :func:`signal.set_wakeup_fd` in Python, but without any 364 error checking. *fd* should be a valid file descriptor. The function should 365 only be called from the main thread. 366 367 .. versionadded:: 2.6 368 369 370.. c:function:: PyObject* PyErr_NewException(char *name, PyObject *base, PyObject *dict) 371 372 This utility function creates and returns a new exception class. The *name* 373 argument must be the name of the new exception, a C string of the form 374 ``module.classname``. The *base* and *dict* arguments are normally *NULL*. 375 This creates a class object derived from :exc:`Exception` (accessible in C as 376 :c:data:`PyExc_Exception`). 377 378 The :attr:`__module__` attribute of the new class is set to the first part (up 379 to the last dot) of the *name* argument, and the class name is set to the last 380 part (after the last dot). The *base* argument can be used to specify alternate 381 base classes; it can either be only one class or a tuple of classes. The *dict* 382 argument can be used to specify a dictionary of class variables and methods. 383 384 385.. c:function:: PyObject* PyErr_NewExceptionWithDoc(char *name, char *doc, PyObject *base, PyObject *dict) 386 387 Same as :c:func:`PyErr_NewException`, except that the new exception class can 388 easily be given a docstring: If *doc* is non-*NULL*, it will be used as the 389 docstring for the exception class. 390 391 .. versionadded:: 2.7 392 393 394.. c:function:: void PyErr_WriteUnraisable(PyObject *obj) 395 396 This utility function prints a warning message to ``sys.stderr`` when an 397 exception has been set but it is impossible for the interpreter to actually 398 raise the exception. It is used, for example, when an exception occurs in an 399 :meth:`__del__` method. 400 401 The function is called with a single argument *obj* that identifies the context 402 in which the unraisable exception occurred. If possible, 403 the repr of *obj* will be printed in the warning message. 404 405 406.. _unicodeexceptions: 407 408Unicode Exception Objects 409========================= 410 411The following functions are used to create and modify Unicode exceptions from C. 412 413.. 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) 414 415 Create a :class:`UnicodeDecodeError` object with the attributes *encoding*, 416 *object*, *length*, *start*, *end* and *reason*. 417 418.. 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) 419 420 Create a :class:`UnicodeEncodeError` object with the attributes *encoding*, 421 *object*, *length*, *start*, *end* and *reason*. 422 423.. c:function:: PyObject* PyUnicodeTranslateError_Create(const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason) 424 425 Create a :class:`UnicodeTranslateError` object with the attributes *object*, 426 *length*, *start*, *end* and *reason*. 427 428.. c:function:: PyObject* PyUnicodeDecodeError_GetEncoding(PyObject *exc) 429 PyObject* PyUnicodeEncodeError_GetEncoding(PyObject *exc) 430 431 Return the *encoding* attribute of the given exception object. 432 433.. c:function:: PyObject* PyUnicodeDecodeError_GetObject(PyObject *exc) 434 PyObject* PyUnicodeEncodeError_GetObject(PyObject *exc) 435 PyObject* PyUnicodeTranslateError_GetObject(PyObject *exc) 436 437 Return the *object* attribute of the given exception object. 438 439.. c:function:: int PyUnicodeDecodeError_GetStart(PyObject *exc, Py_ssize_t *start) 440 int PyUnicodeEncodeError_GetStart(PyObject *exc, Py_ssize_t *start) 441 int PyUnicodeTranslateError_GetStart(PyObject *exc, Py_ssize_t *start) 442 443 Get the *start* attribute of the given exception object and place it into 444 *\*start*. *start* must not be *NULL*. Return ``0`` on success, ``-1`` on 445 failure. 446 447.. c:function:: int PyUnicodeDecodeError_SetStart(PyObject *exc, Py_ssize_t start) 448 int PyUnicodeEncodeError_SetStart(PyObject *exc, Py_ssize_t start) 449 int PyUnicodeTranslateError_SetStart(PyObject *exc, Py_ssize_t start) 450 451 Set the *start* attribute of the given exception object to *start*. Return 452 ``0`` on success, ``-1`` on failure. 453 454.. c:function:: int PyUnicodeDecodeError_GetEnd(PyObject *exc, Py_ssize_t *end) 455 int PyUnicodeEncodeError_GetEnd(PyObject *exc, Py_ssize_t *end) 456 int PyUnicodeTranslateError_GetEnd(PyObject *exc, Py_ssize_t *end) 457 458 Get the *end* attribute of the given exception object and place it into 459 *\*end*. *end* must not be *NULL*. Return ``0`` on success, ``-1`` on 460 failure. 461 462.. c:function:: int PyUnicodeDecodeError_SetEnd(PyObject *exc, Py_ssize_t end) 463 int PyUnicodeEncodeError_SetEnd(PyObject *exc, Py_ssize_t end) 464 int PyUnicodeTranslateError_SetEnd(PyObject *exc, Py_ssize_t end) 465 466 Set the *end* attribute of the given exception object to *end*. Return ``0`` 467 on success, ``-1`` on failure. 468 469.. c:function:: PyObject* PyUnicodeDecodeError_GetReason(PyObject *exc) 470 PyObject* PyUnicodeEncodeError_GetReason(PyObject *exc) 471 PyObject* PyUnicodeTranslateError_GetReason(PyObject *exc) 472 473 Return the *reason* attribute of the given exception object. 474 475.. c:function:: int PyUnicodeDecodeError_SetReason(PyObject *exc, const char *reason) 476 int PyUnicodeEncodeError_SetReason(PyObject *exc, const char *reason) 477 int PyUnicodeTranslateError_SetReason(PyObject *exc, const char *reason) 478 479 Set the *reason* attribute of the given exception object to *reason*. Return 480 ``0`` on success, ``-1`` on failure. 481 482 483Recursion Control 484================= 485 486These two functions provide a way to perform safe recursive calls at the C 487level, both in the core and in extension modules. They are needed if the 488recursive code does not necessarily invoke Python code (which tracks its 489recursion depth automatically). 490 491.. c:function:: int Py_EnterRecursiveCall(const char *where) 492 493 Marks a point where a recursive C-level call is about to be performed. 494 495 If :const:`USE_STACKCHECK` is defined, this function checks if the OS 496 stack overflowed using :c:func:`PyOS_CheckStack`. In this is the case, it 497 sets a :exc:`MemoryError` and returns a nonzero value. 498 499 The function then checks if the recursion limit is reached. If this is the 500 case, a :exc:`RuntimeError` is set and a nonzero value is returned. 501 Otherwise, zero is returned. 502 503 *where* should be a string such as ``" in instance check"`` to be 504 concatenated to the :exc:`RuntimeError` message caused by the recursion depth 505 limit. 506 507.. c:function:: void Py_LeaveRecursiveCall() 508 509 Ends a :c:func:`Py_EnterRecursiveCall`. Must be called once for each 510 *successful* invocation of :c:func:`Py_EnterRecursiveCall`. 511 512 513.. _standardexceptions: 514 515Standard Exceptions 516=================== 517 518All standard Python exceptions are available as global variables whose names are 519``PyExc_`` followed by the Python exception name. These have the type 520:c:type:`PyObject\*`; they are all class objects. For completeness, here are all 521the variables: 522 523.. index:: 524 single: PyExc_BaseException 525 single: PyExc_Exception 526 single: PyExc_StandardError 527 single: PyExc_ArithmeticError 528 single: PyExc_AssertionError 529 single: PyExc_AttributeError 530 single: PyExc_BufferError 531 single: PyExc_EnvironmentError 532 single: PyExc_EOFError 533 single: PyExc_FloatingPointError 534 single: PyExc_GeneratorExit 535 single: PyExc_ImportError 536 single: PyExc_IndentationError 537 single: PyExc_IndexError 538 single: PyExc_IOError 539 single: PyExc_KeyError 540 single: PyExc_KeyboardInterrupt 541 single: PyExc_LookupError 542 single: PyExc_MemoryError 543 single: PyExc_NameError 544 single: PyExc_NotImplementedError 545 single: PyExc_OSError 546 single: PyExc_OverflowError 547 single: PyExc_ReferenceError 548 single: PyExc_RuntimeError 549 single: PyExc_StopIteration 550 single: PyExc_SyntaxError 551 single: PyExc_SystemError 552 single: PyExc_SystemExit 553 single: PyExc_TabError 554 single: PyExc_TypeError 555 single: PyExc_UnboundLocalError 556 single: PyExc_UnicodeDecodeError 557 single: PyExc_UnicodeEncodeError 558 single: PyExc_UnicodeError 559 single: PyExc_UnicodeTranslateError 560 single: PyExc_VMSError 561 single: PyExc_ValueError 562 single: PyExc_WindowsError 563 single: PyExc_ZeroDivisionError 564 565+-----------------------------------------+---------------------------------+----------+ 566| C Name | Python Name | Notes | 567+=========================================+=================================+==========+ 568| :c:data:`PyExc_BaseException` | :exc:`BaseException` | (1), (4) | 569+-----------------------------------------+---------------------------------+----------+ 570| :c:data:`PyExc_Exception` | :exc:`Exception` | \(1) | 571+-----------------------------------------+---------------------------------+----------+ 572| :c:data:`PyExc_StandardError` | :exc:`StandardError` | \(1) | 573+-----------------------------------------+---------------------------------+----------+ 574| :c:data:`PyExc_ArithmeticError` | :exc:`ArithmeticError` | \(1) | 575+-----------------------------------------+---------------------------------+----------+ 576| :c:data:`PyExc_AssertionError` | :exc:`AssertionError` | | 577+-----------------------------------------+---------------------------------+----------+ 578| :c:data:`PyExc_AttributeError` | :exc:`AttributeError` | | 579+-----------------------------------------+---------------------------------+----------+ 580| :c:data:`PyExc_BufferError` | :exc:`BufferError` | | 581+-----------------------------------------+---------------------------------+----------+ 582| :c:data:`PyExc_EnvironmentError` | :exc:`EnvironmentError` | \(1) | 583+-----------------------------------------+---------------------------------+----------+ 584| :c:data:`PyExc_EOFError` | :exc:`EOFError` | | 585+-----------------------------------------+---------------------------------+----------+ 586| :c:data:`PyExc_FloatingPointError` | :exc:`FloatingPointError` | | 587+-----------------------------------------+---------------------------------+----------+ 588| :c:data:`PyExc_GeneratorExit` | :exc:`GeneratorExit` | | 589+-----------------------------------------+---------------------------------+----------+ 590| :c:data:`PyExc_ImportError` | :exc:`ImportError` | | 591+-----------------------------------------+---------------------------------+----------+ 592| :c:data:`PyExc_IndentationError` | :exc:`IndentationError` | | 593+-----------------------------------------+---------------------------------+----------+ 594| :c:data:`PyExc_IndexError` | :exc:`IndexError` | | 595+-----------------------------------------+---------------------------------+----------+ 596| :c:data:`PyExc_IOError` | :exc:`IOError` | | 597+-----------------------------------------+---------------------------------+----------+ 598| :c:data:`PyExc_KeyError` | :exc:`KeyError` | | 599+-----------------------------------------+---------------------------------+----------+ 600| :c:data:`PyExc_KeyboardInterrupt` | :exc:`KeyboardInterrupt` | | 601+-----------------------------------------+---------------------------------+----------+ 602| :c:data:`PyExc_LookupError` | :exc:`LookupError` | \(1) | 603+-----------------------------------------+---------------------------------+----------+ 604| :c:data:`PyExc_MemoryError` | :exc:`MemoryError` | | 605+-----------------------------------------+---------------------------------+----------+ 606| :c:data:`PyExc_NameError` | :exc:`NameError` | | 607+-----------------------------------------+---------------------------------+----------+ 608| :c:data:`PyExc_NotImplementedError` | :exc:`NotImplementedError` | | 609+-----------------------------------------+---------------------------------+----------+ 610| :c:data:`PyExc_OSError` | :exc:`OSError` | | 611+-----------------------------------------+---------------------------------+----------+ 612| :c:data:`PyExc_OverflowError` | :exc:`OverflowError` | | 613+-----------------------------------------+---------------------------------+----------+ 614| :c:data:`PyExc_ReferenceError` | :exc:`ReferenceError` | \(2) | 615+-----------------------------------------+---------------------------------+----------+ 616| :c:data:`PyExc_RuntimeError` | :exc:`RuntimeError` | | 617+-----------------------------------------+---------------------------------+----------+ 618| :c:data:`PyExc_StopIteration` | :exc:`StopIteration` | | 619+-----------------------------------------+---------------------------------+----------+ 620| :c:data:`PyExc_SyntaxError` | :exc:`SyntaxError` | | 621+-----------------------------------------+---------------------------------+----------+ 622| :c:data:`PyExc_SystemError` | :exc:`SystemError` | | 623+-----------------------------------------+---------------------------------+----------+ 624| :c:data:`PyExc_SystemExit` | :exc:`SystemExit` | | 625+-----------------------------------------+---------------------------------+----------+ 626| :c:data:`PyExc_TabError` | :exc:`TabError` | | 627+-----------------------------------------+---------------------------------+----------+ 628| :c:data:`PyExc_TypeError` | :exc:`TypeError` | | 629+-----------------------------------------+---------------------------------+----------+ 630| :c:data:`PyExc_UnboundLocalError` | :exc:`UnboundLocalError` | | 631+-----------------------------------------+---------------------------------+----------+ 632| :c:data:`PyExc_UnicodeDecodeError` | :exc:`UnicodeDecodeError` | | 633+-----------------------------------------+---------------------------------+----------+ 634| :c:data:`PyExc_UnicodeEncodeError` | :exc:`UnicodeEncodeError` | | 635+-----------------------------------------+---------------------------------+----------+ 636| :c:data:`PyExc_UnicodeError` | :exc:`UnicodeError` | | 637+-----------------------------------------+---------------------------------+----------+ 638| :c:data:`PyExc_UnicodeTranslateError` | :exc:`UnicodeTranslateError` | | 639+-----------------------------------------+---------------------------------+----------+ 640| :c:data:`PyExc_VMSError` | :exc:`VMSError` | \(5) | 641+-----------------------------------------+---------------------------------+----------+ 642| :c:data:`PyExc_ValueError` | :exc:`ValueError` | | 643+-----------------------------------------+---------------------------------+----------+ 644| :c:data:`PyExc_WindowsError` | :exc:`WindowsError` | \(3) | 645+-----------------------------------------+---------------------------------+----------+ 646| :c:data:`PyExc_ZeroDivisionError` | :exc:`ZeroDivisionError` | | 647+-----------------------------------------+---------------------------------+----------+ 648 649Notes: 650 651(1) 652 This is a base class for other standard exceptions. 653 654(2) 655 This is the same as :exc:`weakref.ReferenceError`. 656 657(3) 658 Only defined on Windows; protect code that uses this by testing that the 659 preprocessor macro ``MS_WINDOWS`` is defined. 660 661(4) 662 .. versionadded:: 2.5 663 664(5) 665 Only defined on VMS; protect code that uses this by testing that the 666 preprocessor macro ``__VMS`` is defined. 667 668.. _standardwarningcategories: 669 670Standard Warning Categories 671=========================== 672 673All standard Python warning categories are available as global variables whose 674names are ``PyExc_`` followed by the Python exception name. These have the type 675:c:type:`PyObject\*`; they are all class objects. For completeness, here are all 676the variables: 677 678.. index:: 679 single: PyExc_Warning 680 single: PyExc_BytesWarning 681 single: PyExc_DeprecationWarning 682 single: PyExc_FutureWarning 683 single: PyExc_ImportWarning 684 single: PyExc_PendingDeprecationWarning 685 single: PyExc_RuntimeWarning 686 single: PyExc_SyntaxWarning 687 single: PyExc_UnicodeWarning 688 single: PyExc_UserWarning 689 690+------------------------------------------+---------------------------------+----------+ 691| C Name | Python Name | Notes | 692+==========================================+=================================+==========+ 693| :c:data:`PyExc_Warning` | :exc:`Warning` | \(1) | 694+------------------------------------------+---------------------------------+----------+ 695| :c:data:`PyExc_BytesWarning` | :exc:`BytesWarning` | | 696+------------------------------------------+---------------------------------+----------+ 697| :c:data:`PyExc_DeprecationWarning` | :exc:`DeprecationWarning` | | 698+------------------------------------------+---------------------------------+----------+ 699| :c:data:`PyExc_FutureWarning` | :exc:`FutureWarning` | | 700+------------------------------------------+---------------------------------+----------+ 701| :c:data:`PyExc_ImportWarning` | :exc:`ImportWarning` | | 702+------------------------------------------+---------------------------------+----------+ 703| :c:data:`PyExc_PendingDeprecationWarning`| :exc:`PendingDeprecationWarning`| | 704+------------------------------------------+---------------------------------+----------+ 705| :c:data:`PyExc_RuntimeWarning` | :exc:`RuntimeWarning` | | 706+------------------------------------------+---------------------------------+----------+ 707| :c:data:`PyExc_SyntaxWarning` | :exc:`SyntaxWarning` | | 708+------------------------------------------+---------------------------------+----------+ 709| :c:data:`PyExc_UnicodeWarning` | :exc:`UnicodeWarning` | | 710+------------------------------------------+---------------------------------+----------+ 711| :c:data:`PyExc_UserWarning` | :exc:`UserWarning` | | 712+------------------------------------------+---------------------------------+----------+ 713 714Notes: 715 716(1) 717 This is a base class for other standard warning categories. 718 719String Exceptions 720================= 721 722.. versionchanged:: 2.6 723 All exceptions to be raised or caught must be derived from :exc:`BaseException`. 724 Trying to raise a string exception now raises :exc:`TypeError`. 725