Doc/c-api/exceptions.rst

   1 .. highlightlang:: c
   2
   3
   4 .. _exceptionhandling:
   5
   6 ******************
   7 Exception Handling
   8 ******************
   9
  10 The functions described in this chapter will let you handle and raise Python
  11 exceptions.  It is important to understand some of the basics of Python
  12 exception handling.  It works somewhat like the Unix :cdata:`errno` variable:
  13 there is a global indicator (per thread) of the last error that occurred.  Most
  14 functions don't clear this on success, but will set it to indicate the cause of
  15 the 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
  17 integer (exception: the :cfunc:`PyArg_\*` functions return ``1`` for success and
  18 ``0`` for failure).
  19
  20 When a function must fail because some function it called failed, it generally
  21 doesn't set the error indicator; the function it called already set it.  It is
  22 responsible for either handling the error and clearing the exception or
  23 returning after cleaning up any resources it holds (such as object references or
  24 memory allocations); it should *not* continue normally if it is not prepared to
  25 handle the error.  If returning due to an error, it is important to indicate to
  26 the caller that an error has been set.  If the error is not handled or carefully
  27 propagated, additional calls into the Python/C API may not behave as intended
  28 and 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
  35 The error indicator consists of three Python objects corresponding to   the
  36 Python variables ``sys.exc_type``, ``sys.exc_value`` and ``sys.exc_traceback``.
  37 API functions exist to interact with the error indicator in various ways.  There
  38 is 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 .. cfunction:: 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 .. cfunction:: void PyErr_Print()
  56
  57    Alias for ``PyErr_PrintEx(1)``.
  58
  59
  60 .. cfunction:: 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 :cfunc:`PyErr_Set\*`
  64    functions or to :cfunc:`PyErr_Restore`).  If not set, return *NULL*.  You do not
  65    own a reference to the return value, so you do not need to :cfunc:`Py_DECREF`
  66    it.
  67
  68    .. note::
  69
  70       Do not compare the return value to a specific exception; use
  71       :cfunc:`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 the a subclass of the expected exception.)
  74
  75
  76 .. cfunction:: 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 .. cfunction:: 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 .. cfunction:: void PyErr_NormalizeException(PyObject**exc, PyObject**val, PyObject**tb)
  92
  93    Under certain circumstances, the values returned by :cfunc:`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 .. cfunction:: void PyErr_Clear()
 101
 102    Clear the error indicator.  If the error indicator is not set, there is no
 103    effect.
 104
 105
 106 .. cfunction:: 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 .. cfunction:: 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 :cfunc:`PyErr_Fetch` to save the current
 135       exception state.
 136
 137
 138 .. cfunction:: 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. :cdata:`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 .. cfunction:: void PyErr_SetObject(PyObject *type, PyObject *value)
 147
 148    This function is similar to :cfunc:`PyErr_SetString` but lets you specify an
 149    arbitrary Python object for the "value" of the exception.
 150
 151
 152 .. cfunction:: PyObject* PyErr_Format(PyObject *exception, const char *format, ...)
 153
 154    This function sets the error indicator and returns *NULL*. *exception* should be
 155    a Python exception (class, not an instance).  *format* should be a string,
 156    containing format codes, similar to :cfunc:`printf`. The ``width.precision``
 157    before a format code is parsed, but the width part is ignored.
 158
 159    .. % This should be exactly the same as the table in PyString_FromFormat.
 160    .. % One should just refer to the other.
 161    .. % The descriptions for %zd and %zu are wrong, but the truth is complicated
 162    .. % because not all compilers support the %z width modifier -- we fake it
 163    .. % when necessary via interpolating PY_FORMAT_SIZE_T.
 164    .. % %u, %lu, %zu should have "new in Python 2.5" blurbs.
 165
 166    +-------------------+---------------+--------------------------------+
 167    | Format Characters | Type          | Comment                        |
 168    +===================+===============+================================+
 169    | :attr:`%%`        | *n/a*         | The literal % character.       |
 170    +-------------------+---------------+--------------------------------+
 171    | :attr:`%c`        | int           | A single character,            |
 172    |                   |               | represented as an C int.       |
 173    +-------------------+---------------+--------------------------------+
 174    | :attr:`%d`        | int           | Exactly equivalent to          |
 175    |                   |               | ``printf("%d")``.              |
 176    +-------------------+---------------+--------------------------------+
 177    | :attr:`%u`        | unsigned int  | Exactly equivalent to          |
 178    |                   |               | ``printf("%u")``.              |
 179    +-------------------+---------------+--------------------------------+
 180    | :attr:`%ld`       | long          | Exactly equivalent to          |
 181    |                   |               | ``printf("%ld")``.             |
 182    +-------------------+---------------+--------------------------------+
 183    | :attr:`%lu`       | unsigned long | Exactly equivalent to          |
 184    |                   |               | ``printf("%lu")``.             |
 185    +-------------------+---------------+--------------------------------+
 186    | :attr:`%zd`       | Py_ssize_t    | Exactly equivalent to          |
 187    |                   |               | ``printf("%zd")``.             |
 188    +-------------------+---------------+--------------------------------+
 189    | :attr:`%zu`       | size_t        | Exactly equivalent to          |
 190    |                   |               | ``printf("%zu")``.             |
 191    +-------------------+---------------+--------------------------------+
 192    | :attr:`%i`        | int           | Exactly equivalent to          |
 193    |                   |               | ``printf("%i")``.              |
 194    +-------------------+---------------+--------------------------------+
 195    | :attr:`%x`        | int           | Exactly equivalent to          |
 196    |                   |               | ``printf("%x")``.              |
 197    +-------------------+---------------+--------------------------------+
 198    | :attr:`%s`        | char\*        | A null-terminated C character  |
 199    |                   |               | array.                         |
 200    +-------------------+---------------+--------------------------------+
 201    | :attr:`%p`        | void\*        | The hex representation of a C  |
 202    |                   |               | pointer. Mostly equivalent to  |
 203    |                   |               | ``printf("%p")`` except that   |
 204    |                   |               | it is guaranteed to start with |
 205    |                   |               | the literal ``0x`` regardless  |
 206    |                   |               | of what the platform's         |
 207    |                   |               | ``printf`` yields.             |
 208    +-------------------+---------------+--------------------------------+
 209
 210    An unrecognized format character causes all the rest of the format string to be
 211    copied as-is to the result string, and any extra arguments discarded.
 212
 213
 214 .. cfunction:: void PyErr_SetNone(PyObject *type)
 215
 216    This is a shorthand for ``PyErr_SetObject(type, Py_None)``.
 217
 218
 219 .. cfunction:: int PyErr_BadArgument()
 220
 221    This is a shorthand for ``PyErr_SetString(PyExc_TypeError, message)``, where
 222    *message* indicates that a built-in operation was invoked with an illegal
 223    argument.  It is mostly for internal use.
 224
 225
 226 .. cfunction:: PyObject* PyErr_NoMemory()
 227
 228    This is a shorthand for ``PyErr_SetNone(PyExc_MemoryError)``; it returns *NULL*
 229    so an object allocation function can write ``return PyErr_NoMemory();`` when it
 230    runs out of memory.
 231
 232
 233 .. cfunction:: PyObject* PyErr_SetFromErrno(PyObject *type)
 234
 235    .. index:: single: strerror()
 236
 237    This is a convenience function to raise an exception when a C library function
 238    has returned an error and set the C variable :cdata:`errno`.  It constructs a
 239    tuple object whose first item is the integer :cdata:`errno` value and whose
 240    second item is the corresponding error message (gotten from :cfunc:`strerror`),
 241    and then calls ``PyErr_SetObject(type, object)``.  On Unix, when the
 242    :cdata:`errno` value is :const:`EINTR`, indicating an interrupted system call,
 243    this calls :cfunc:`PyErr_CheckSignals`, and if that set the error indicator,
 244    leaves it set to that.  The function always returns *NULL*, so a wrapper
 245    function around a system call can write ``return PyErr_SetFromErrno(type);``
 246    when the system call returns an error.
 247
 248
 249 .. cfunction:: PyObject* PyErr_SetFromErrnoWithFilename(PyObject *type, const char *filename)
 250
 251    Similar to :cfunc:`PyErr_SetFromErrno`, with the additional behavior that if
 252    *filename* is not *NULL*, it is passed to the constructor of *type* as a third
 253    parameter.  In the case of exceptions such as :exc:`IOError` and :exc:`OSError`,
 254    this is used to define the :attr:`filename` attribute of the exception instance.
 255
 256
 257 .. cfunction:: PyObject* PyErr_SetFromWindowsErr(int ierr)
 258
 259    This is a convenience function to raise :exc:`WindowsError`. If called with
 260    *ierr* of :cdata:`0`, the error code returned by a call to :cfunc:`GetLastError`
 261    is used instead.  It calls the Win32 function :cfunc:`FormatMessage` to retrieve
 262    the Windows description of error code given by *ierr* or :cfunc:`GetLastError`,
 263    then it constructs a tuple object whose first item is the *ierr* value and whose
 264    second item is the corresponding error message (gotten from
 265    :cfunc:`FormatMessage`), and then calls ``PyErr_SetObject(PyExc_WindowsError,
 266    object)``. This function always returns *NULL*. Availability: Windows.
 267
 268
 269 .. cfunction:: PyObject* PyErr_SetExcFromWindowsErr(PyObject *type, int ierr)
 270
 271    Similar to :cfunc:`PyErr_SetFromWindowsErr`, with an additional parameter
 272    specifying the exception type to be raised. Availability: Windows.
 273
 274    .. versionadded:: 2.3
 275
 276
 277 .. cfunction:: PyObject* PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename)
 278
 279    Similar to :cfunc:`PyErr_SetFromWindowsErr`, with the additional behavior that
 280    if *filename* is not *NULL*, it is passed to the constructor of
 281    :exc:`WindowsError` as a third parameter. Availability: Windows.
 282
 283
 284 .. cfunction:: PyObject* PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, char *filename)
 285
 286    Similar to :cfunc:`PyErr_SetFromWindowsErrWithFilename`, with an additional
 287    parameter specifying the exception type to be raised. Availability: Windows.
 288
 289    .. versionadded:: 2.3
 290
 291
 292 .. cfunction:: void PyErr_BadInternalCall()
 293
 294    This is a shorthand for ``PyErr_SetString(PyExc_SystemError, message)``,
 295    where *message* indicates that an internal operation (e.g. a Python/C API
 296    function) was invoked with an illegal argument.  It is mostly for internal
 297    use.
 298
 299
 300 .. cfunction:: int PyErr_WarnEx(PyObject *category, char *message, int stacklevel)
 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.  *stacklevel* is a
 304    positive number giving a number of stack frames; the warning will be issued from
 305    the  currently executing line of code in that stack frame.  A *stacklevel* of 1
 306    is the function calling :cfunc:`PyErr_WarnEx`, 2 is  the function above that,
 307    and so forth.
 308
 309    This function normally prints a warning message to *sys.stderr*; however, it is
 310    also possible that the user has specified that warnings are to be turned into
 311    errors, and in that case this will raise an exception.  It is also possible that
 312    the function raises an exception because of a problem with the warning machinery
 313    (the implementation imports the :mod:`warnings` module to do the heavy lifting).
 314    The return value is ``0`` if no exception is raised, or ``-1`` if an exception
 315    is raised.  (It is not possible to determine whether a warning message is
 316    actually printed, nor what the reason is for the exception; this is
 317    intentional.)  If an exception is raised, the caller should do its normal
 318    exception handling (for example, :cfunc:`Py_DECREF` owned references and return
 319    an error value).
 320
 321    Warning categories must be subclasses of :cdata:`Warning`; the default warning
 322    category is :cdata:`RuntimeWarning`.  The standard Python warning categories are
 323    available as global variables whose names are ``PyExc_`` followed by the Python
 324    exception name. These have the type :ctype:`PyObject\*`; they are all class
 325    objects. Their names are :cdata:`PyExc_Warning`, :cdata:`PyExc_UserWarning`,
 326    :cdata:`PyExc_UnicodeWarning`, :cdata:`PyExc_DeprecationWarning`,
 327    :cdata:`PyExc_SyntaxWarning`, :cdata:`PyExc_RuntimeWarning`, and
 328    :cdata:`PyExc_FutureWarning`.  :cdata:`PyExc_Warning` is a subclass of
 329    :cdata:`PyExc_Exception`; the other warning categories are subclasses of
 330    :cdata:`PyExc_Warning`.
 331
 332    For information about warning control, see the documentation for the
 333    :mod:`warnings` module and the :option:`-W` option in the command line
 334    documentation.  There is no C API for warning control.
 335
 336
 337 .. cfunction:: int PyErr_Warn(PyObject *category, char *message)
 338
 339    Issue a warning message.  The *category* argument is a warning category (see
 340    below) or *NULL*; the *message* argument is a message string.  The warning will
 341    appear to be issued from the function calling :cfunc:`PyErr_Warn`, equivalent to
 342    calling :cfunc:`PyErr_WarnEx` with a *stacklevel* of 1.
 343
 344    Deprecated; use :cfunc:`PyErr_WarnEx` instead.
 345
 346
 347 .. cfunction:: int PyErr_WarnExplicit(PyObject *category, const char *message, const char *filename, int lineno, const char *module, PyObject *registry)
 348
 349    Issue a warning message with explicit control over all warning attributes.  This
 350    is a straightforward wrapper around the Python function
 351    :func:`warnings.warn_explicit`, see there for more information.  The *module*
 352    and *registry* arguments may be set to *NULL* to get the default effect
 353    described there.
 354
 355
 356 .. cfunction:: int PyErr_WarnPy3k(char *message, int stacklevel)
 357
 358    Issue a :exc:`DeprecationWarning` with the given *message* and *stacklevel*
 359    if the :cdata:`Py_Py3kWarningFlag` flag is enabled.
 360
 361    .. versionadded:: 2.6
 362
 363
 364 .. cfunction:: int PyErr_CheckSignals()
 365
 366    .. index::
 367       module: signal
 368       single: SIGINT
 369       single: KeyboardInterrupt (built-in exception)
 370
 371    This function interacts with Python's signal handling.  It checks whether a
 372    signal has been sent to the processes and if so, invokes the corresponding
 373    signal handler.  If the :mod:`signal` module is supported, this can invoke a
 374    signal handler written in Python.  In all cases, the default effect for
 375    :const:`SIGINT` is to raise the  :exc:`KeyboardInterrupt` exception.  If an
 376    exception is raised the error indicator is set and the function returns ``-1``;
 377    otherwise the function returns ``0``.  The error indicator may or may not be
 378    cleared if it was previously set.
 379
 380
 381 .. cfunction:: void PyErr_SetInterrupt()
 382
 383    .. index::
 384       single: SIGINT
 385       single: KeyboardInterrupt (built-in exception)
 386
 387    This function simulates the effect of a :const:`SIGINT` signal arriving --- the
 388    next time :cfunc:`PyErr_CheckSignals` is called,  :exc:`KeyboardInterrupt` will
 389    be raised.  It may be called without holding the interpreter lock.
 390
 391    .. % XXX This was described as obsolete, but is used in
 392    .. % thread.interrupt_main() (used from IDLE), so it's still needed.
 393
 394
 395 .. cfunction:: int PySignal_SetWakeupFd(int fd)
 396
 397    This utility function specifies a file descriptor to which a ``'\0'`` byte will
 398    be written whenever a signal is received.  It returns the previous such file
 399    descriptor.  The value ``-1`` disables the feature; this is the initial state.
 400    This is equivalent to :func:`signal.set_wakeup_fd` in Python, but without any
 401    error checking.  *fd* should be a valid file descriptor.  The function should
 402    only be called from the main thread.
 403
 404
 405 .. cfunction:: PyObject* PyErr_NewException(char *name, PyObject *base, PyObject *dict)
 406
 407    This utility function creates and returns a new exception object. The *name*
 408    argument must be the name of the new exception, a C string of the form
 409    ``module.class``.  The *base* and *dict* arguments are normally *NULL*.  This
 410    creates a class object derived from :exc:`Exception` (accessible in C as
 411    :cdata:`PyExc_Exception`).
 412
 413    The :attr:`__module__` attribute of the new class is set to the first part (up
 414    to the last dot) of the *name* argument, and the class name is set to the last
 415    part (after the last dot).  The *base* argument can be used to specify alternate
 416    base classes; it can either be only one class or a tuple of classes. The *dict*
 417    argument can be used to specify a dictionary of class variables and methods.
 418
 419
 420 .. cfunction:: void PyErr_WriteUnraisable(PyObject *obj)
 421
 422    This utility function prints a warning message to ``sys.stderr`` when an
 423    exception has been set but it is impossible for the interpreter to actually
 424    raise the exception.  It is used, for example, when an exception occurs in an
 425    :meth:`__del__` method.
 426
 427    The function is called with a single argument *obj* that identifies the context
 428    in which the unraisable exception occurred. The repr of *obj* will be printed in
 429    the warning message.
 430
 431
 432 .. _standardexceptions:
 433
 434 Standard Exceptions
 435 ===================
 436
 437 All standard Python exceptions are available as global variables whose names are
 438 ``PyExc_`` followed by the Python exception name.  These have the type
 439 :ctype:`PyObject\*`; they are all class objects.  For completeness, here are all
 440 the variables:
 441
 442 +------------------------------------+----------------------------+----------+
 443 | C Name                             | Python Name                | Notes    |
 444 +====================================+============================+==========+
 445 | :cdata:`PyExc_BaseException`       | :exc:`BaseException`       | (1), (4) |
 446 +------------------------------------+----------------------------+----------+
 447 | :cdata:`PyExc_Exception`           | :exc:`Exception`           | \(1)     |
 448 +------------------------------------+----------------------------+----------+
 449 | :cdata:`PyExc_StandardError`       | :exc:`StandardError`       | \(1)     |
 450 +------------------------------------+----------------------------+----------+
 451 | :cdata:`PyExc_ArithmeticError`     | :exc:`ArithmeticError`     | \(1)     |
 452 +------------------------------------+----------------------------+----------+
 453 | :cdata:`PyExc_LookupError`         | :exc:`LookupError`         | \(1)     |
 454 +------------------------------------+----------------------------+----------+
 455 | :cdata:`PyExc_AssertionError`      | :exc:`AssertionError`      |          |
 456 +------------------------------------+----------------------------+----------+
 457 | :cdata:`PyExc_AttributeError`      | :exc:`AttributeError`      |          |
 458 +------------------------------------+----------------------------+----------+
 459 | :cdata:`PyExc_EOFError`            | :exc:`EOFError`            |          |
 460 +------------------------------------+----------------------------+----------+
 461 | :cdata:`PyExc_EnvironmentError`    | :exc:`EnvironmentError`    | \(1)     |
 462 +------------------------------------+----------------------------+----------+
 463 | :cdata:`PyExc_FloatingPointError`  | :exc:`FloatingPointError`  |          |
 464 +------------------------------------+----------------------------+----------+
 465 | :cdata:`PyExc_IOError`             | :exc:`IOError`             |          |
 466 +------------------------------------+----------------------------+----------+
 467 | :cdata:`PyExc_ImportError`         | :exc:`ImportError`         |          |
 468 +------------------------------------+----------------------------+----------+
 469 | :cdata:`PyExc_IndexError`          | :exc:`IndexError`          |          |
 470 +------------------------------------+----------------------------+----------+
 471 | :cdata:`PyExc_KeyError`            | :exc:`KeyError`            |          |
 472 +------------------------------------+----------------------------+----------+
 473 | :cdata:`PyExc_KeyboardInterrupt`   | :exc:`KeyboardInterrupt`   |          |
 474 +------------------------------------+----------------------------+----------+
 475 | :cdata:`PyExc_MemoryError`         | :exc:`MemoryError`         |          |
 476 +------------------------------------+----------------------------+----------+
 477 | :cdata:`PyExc_NameError`           | :exc:`NameError`           |          |
 478 +------------------------------------+----------------------------+----------+
 479 | :cdata:`PyExc_NotImplementedError` | :exc:`NotImplementedError` |          |
 480 +------------------------------------+----------------------------+----------+
 481 | :cdata:`PyExc_OSError`             | :exc:`OSError`             |          |
 482 +------------------------------------+----------------------------+----------+
 483 | :cdata:`PyExc_OverflowError`       | :exc:`OverflowError`       |          |
 484 +------------------------------------+----------------------------+----------+
 485 | :cdata:`PyExc_ReferenceError`      | :exc:`ReferenceError`      | \(2)     |
 486 +------------------------------------+----------------------------+----------+
 487 | :cdata:`PyExc_RuntimeError`        | :exc:`RuntimeError`        |          |
 488 +------------------------------------+----------------------------+----------+
 489 | :cdata:`PyExc_SyntaxError`         | :exc:`SyntaxError`         |          |
 490 +------------------------------------+----------------------------+----------+
 491 | :cdata:`PyExc_SystemError`         | :exc:`SystemError`         |          |
 492 +------------------------------------+----------------------------+----------+
 493 | :cdata:`PyExc_SystemExit`          | :exc:`SystemExit`          |          |
 494 +------------------------------------+----------------------------+----------+
 495 | :cdata:`PyExc_TypeError`           | :exc:`TypeError`           |          |
 496 +------------------------------------+----------------------------+----------+
 497 | :cdata:`PyExc_ValueError`          | :exc:`ValueError`          |          |
 498 +------------------------------------+----------------------------+----------+
 499 | :cdata:`PyExc_WindowsError`        | :exc:`WindowsError`        | \(3)     |
 500 +------------------------------------+----------------------------+----------+
 501 | :cdata:`PyExc_ZeroDivisionError`   | :exc:`ZeroDivisionError`   |          |
 502 +------------------------------------+----------------------------+----------+
 503
 504 .. index::
 505    single: PyExc_BaseException
 506    single: PyExc_Exception
 507    single: PyExc_StandardError
 508    single: PyExc_ArithmeticError
 509    single: PyExc_LookupError
 510    single: PyExc_AssertionError
 511    single: PyExc_AttributeError
 512    single: PyExc_EOFError
 513    single: PyExc_EnvironmentError
 514    single: PyExc_FloatingPointError
 515    single: PyExc_IOError
 516    single: PyExc_ImportError
 517    single: PyExc_IndexError
 518    single: PyExc_KeyError
 519    single: PyExc_KeyboardInterrupt
 520    single: PyExc_MemoryError
 521    single: PyExc_NameError
 522    single: PyExc_NotImplementedError
 523    single: PyExc_OSError
 524    single: PyExc_OverflowError
 525    single: PyExc_ReferenceError
 526    single: PyExc_RuntimeError
 527    single: PyExc_SyntaxError
 528    single: PyExc_SystemError
 529    single: PyExc_SystemExit
 530    single: PyExc_TypeError
 531    single: PyExc_ValueError
 532    single: PyExc_WindowsError
 533    single: PyExc_ZeroDivisionError
 534
 535 Notes:
 536
 537 (1)
 538    This is a base class for other standard exceptions.
 539
 540 (2)
 541    This is the same as :exc:`weakref.ReferenceError`.
 542
 543 (3)
 544    Only defined on Windows; protect code that uses this by testing that the
 545    preprocessor macro ``MS_WINDOWS`` is defined.
 546
 547 (4)
 548    .. versionadded:: 2.5
 549
 550
 551 Deprecation of String Exceptions
 552 ================================
 553
 554 .. index:: single: BaseException (built-in exception)
 555
 556 All exceptions built into Python or provided in the standard library are derived
 557 from :exc:`BaseException`.
 558
 559 String exceptions are still supported in the interpreter to allow existing code
 560 to run unmodified, but this will also change in a future release.
 561