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_Print()

    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 

    51 .. cfunction:: PyObject* PyErr_Occurred()

    52 

    53    Test whether the error indicator is set.  If set, return the exception *type*

    54    (the first argument to the last call to one of the :cfunc:`PyErr_Set\*`

    55    functions or to :cfunc:`PyErr_Restore`).  If not set, return *NULL*.  You do not

    56    own a reference to the return value, so you do not need to :cfunc:`Py_DECREF`

    57    it.

    58 

    59    .. note::

    60 

    61       Do not compare the return value to a specific exception; use

    62       :cfunc:`PyErr_ExceptionMatches` instead, shown below.  (The comparison could

    63       easily fail since the exception may be an instance instead of a class, in the

    64       case of a class exception, or it may the a subclass of the expected exception.)

    65 

    66 

    67 .. cfunction:: int PyErr_ExceptionMatches(PyObject *exc)

    68 

    69    Equivalent to ``PyErr_GivenExceptionMatches(PyErr_Occurred(), exc)``.  This

    70    should only be called when an exception is actually set; a memory access

    71    violation will occur if no exception has been raised.

    72 

    73 

    74 .. cfunction:: int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc)

    75 

    76    Return true if the *given* exception matches the exception in *exc*.  If *exc*

    77    is a class object, this also returns true when *given* is an instance of a

    78    subclass.  If *exc* is a tuple, all exceptions in the tuple (and recursively in

    79    subtuples) are searched for a match.  If *given* is *NULL*, a memory access

    80    violation will occur.

    81 

    82 

    83 .. cfunction:: void PyErr_NormalizeException(PyObject**exc, PyObject**val, PyObject**tb)

    84 

    85    Under certain circumstances, the values returned by :cfunc:`PyErr_Fetch` below

    86    can be "unnormalized", meaning that ``*exc`` is a class object but ``*val`` is

    87    not an instance of the  same class.  This function can be used to instantiate

    88    the class in that case.  If the values are already normalized, nothing happens.

    89    The delayed normalization is implemented to improve performance.

    90 

    91 

    92 .. cfunction:: void PyErr_Clear()

    93 

    94    Clear the error indicator.  If the error indicator is not set, there is no

    95    effect.

    96 

    97 

    98 .. cfunction:: void PyErr_Fetch(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)

    99 

   100    Retrieve the error indicator into three variables whose addresses are passed.

   101    If the error indicator is not set, set all three variables to *NULL*.  If it is

   102    set, it will be cleared and you own a reference to each object retrieved.  The

   103    value and traceback object may be *NULL* even when the type object is not.

   104 

   105    .. note::

   106 

   107       This function is normally only used by code that needs to handle exceptions or

   108       by code that needs to save and restore the error indicator temporarily.

   109 

   110 

   111 .. cfunction:: void PyErr_Restore(PyObject *type, PyObject *value, PyObject *traceback)

   112 

   113    Set  the error indicator from the three objects.  If the error indicator is

   114    already set, it is cleared first.  If the objects are *NULL*, the error

   115    indicator is cleared.  Do not pass a *NULL* type and non-*NULL* value or

   116    traceback.  The exception type should be a class.  Do not pass an invalid

   117    exception type or value. (Violating these rules will cause subtle problems

   118    later.)  This call takes away a reference to each object: you must own a

   119    reference to each object before the call and after the call you no longer own

   120    these references.  (If you don't understand this, don't use this function.  I

   121    warned you.)

   122 

   123    .. note::

   124 

   125       This function is normally only used by code that needs to save and restore the

   126       error indicator temporarily; use :cfunc:`PyErr_Fetch` to save the current

   127       exception state.

   128 

   129 

   130 .. cfunction:: void PyErr_SetString(PyObject *type, const char *message)

   131 

   132    This is the most common way to set the error indicator.  The first argument

   133    specifies the exception type; it is normally one of the standard exceptions,

   134    e.g. :cdata:`PyExc_RuntimeError`.  You need not increment its reference count.

   135    The second argument is an error message; it is converted to a string object.

   136 

   137 

   138 .. cfunction:: void PyErr_SetObject(PyObject *type, PyObject *value)

   139 

   140    This function is similar to :cfunc:`PyErr_SetString` but lets you specify an

   141    arbitrary Python object for the "value" of the exception.

   142 

   143 

   144 .. cfunction:: PyObject* PyErr_Format(PyObject *exception, const char *format, ...)

   145 

   146    This function sets the error indicator and returns *NULL*. *exception* should be

   147    a Python exception (class, not an instance).  *format* should be a string,

   148    containing format codes, similar to :cfunc:`printf`. The ``width.precision``

   149    before a format code is parsed, but the width part is ignored.

   150 

   151    .. % This should be exactly the same as the table in PyString_FromFormat.

   152    .. % One should just refer to the other.

   153    .. % The descriptions for %zd and %zu are wrong, but the truth is complicated

   154    .. % because not all compilers support the %z width modifier -- we fake it

   155    .. % when necessary via interpolating PY_FORMAT_SIZE_T.

   156    .. % %u, %lu, %zu should have "new in Python 2.5" blurbs.

   157 

   158    +-------------------+---------------+--------------------------------+

   159    | Format Characters | Type          | Comment                        |

   160    +===================+===============+================================+

   161    | :attr:`%%`        | *n/a*         | The literal % character.       |

   162    +-------------------+---------------+--------------------------------+

   163    | :attr:`%c`        | int           | A single character,            |

   164    |                   |               | represented as an C int.       |

   165    +-------------------+---------------+--------------------------------+

   166    | :attr:`%d`        | int           | Exactly equivalent to          |

   167    |                   |               | ``printf("%d")``.              |

   168    +-------------------+---------------+--------------------------------+

   169    | :attr:`%u`        | unsigned int  | Exactly equivalent to          |

   170    |                   |               | ``printf("%u")``.              |

   171    +-------------------+---------------+--------------------------------+

   172    | :attr:`%ld`       | long          | Exactly equivalent to          |

   173    |                   |               | ``printf("%ld")``.             |

   174    +-------------------+---------------+--------------------------------+

   175    | :attr:`%lu`       | unsigned long | Exactly equivalent to          |

   176    |                   |               | ``printf("%lu")``.             |

   177    +-------------------+---------------+--------------------------------+

   178    | :attr:`%zd`       | Py_ssize_t    | Exactly equivalent to          |

   179    |                   |               | ``printf("%zd")``.             |

   180    +-------------------+---------------+--------------------------------+

   181    | :attr:`%zu`       | size_t        | Exactly equivalent to          |

   182    |                   |               | ``printf("%zu")``.             |

   183    +-------------------+---------------+--------------------------------+

   184    | :attr:`%i`        | int           | Exactly equivalent to          |

   185    |                   |               | ``printf("%i")``.              |

   186    +-------------------+---------------+--------------------------------+

   187    | :attr:`%x`        | int           | Exactly equivalent to          |

   188    |                   |               | ``printf("%x")``.              |

   189    +-------------------+---------------+--------------------------------+

   190    | :attr:`%s`        | char\*        | A null-terminated C character  |

   191    |                   |               | array.                         |

   192    +-------------------+---------------+--------------------------------+

   193    | :attr:`%p`        | void\*        | The hex representation of a C  |

   194    |                   |               | pointer. Mostly equivalent to  |

   195    |                   |               | ``printf("%p")`` except that   |

   196    |                   |               | it is guaranteed to start with |

   197    |                   |               | the literal ``0x`` regardless  |

   198    |                   |               | of what the platform's         |

   199    |                   |               | ``printf`` yields.             |

   200    +-------------------+---------------+--------------------------------+

   201 

   202    An unrecognized format character causes all the rest of the format string to be

   203    copied as-is to the result string, and any extra arguments discarded.

   204 

   205 

   206 .. cfunction:: void PyErr_SetNone(PyObject *type)

   207 

   208    This is a shorthand for ``PyErr_SetObject(type, Py_None)``.

   209 

   210 

   211 .. cfunction:: int PyErr_BadArgument()

   212 

   213    This is a shorthand for ``PyErr_SetString(PyExc_TypeError, message)``, where

   214    *message* indicates that a built-in operation was invoked with an illegal

   215    argument.  It is mostly for internal use.

   216 

   217 

   218 .. cfunction:: PyObject* PyErr_NoMemory()

   219 

   220    This is a shorthand for ``PyErr_SetNone(PyExc_MemoryError)``; it returns *NULL*

   221    so an object allocation function can write ``return PyErr_NoMemory();`` when it

   222    runs out of memory.

   223 

   224 

   225 .. cfunction:: PyObject* PyErr_SetFromErrno(PyObject *type)

   226 

   227    .. index:: single: strerror()

   228 

   229    This is a convenience function to raise an exception when a C library function

   230    has returned an error and set the C variable :cdata:`errno`.  It constructs a

   231    tuple object whose first item is the integer :cdata:`errno` value and whose

   232    second item is the corresponding error message (gotten from :cfunc:`strerror`),

   233    and then calls ``PyErr_SetObject(type, object)``.  On Unix, when the

   234    :cdata:`errno` value is :const:`EINTR`, indicating an interrupted system call,

   235    this calls :cfunc:`PyErr_CheckSignals`, and if that set the error indicator,

   236    leaves it set to that.  The function always returns *NULL*, so a wrapper

   237    function around a system call can write ``return PyErr_SetFromErrno(type);``

   238    when the system call returns an error.

   239 

   240 

   241 .. cfunction:: PyObject* PyErr_SetFromErrnoWithFilename(PyObject *type, const char *filename)

   242 

   243    Similar to :cfunc:`PyErr_SetFromErrno`, with the additional behavior that if

   244    *filename* is not *NULL*, it is passed to the constructor of *type* as a third

   245    parameter.  In the case of exceptions such as :exc:`IOError` and :exc:`OSError`,

   246    this is used to define the :attr:`filename` attribute of the exception instance.

   247 

   248 

   249 .. cfunction:: PyObject* PyErr_SetFromWindowsErr(int ierr)

   250 

   251    This is a convenience function to raise :exc:`WindowsError`. If called with

   252    *ierr* of :cdata:`0`, the error code returned by a call to :cfunc:`GetLastError`

   253    is used instead.  It calls the Win32 function :cfunc:`FormatMessage` to retrieve

   254    the Windows description of error code given by *ierr* or :cfunc:`GetLastError`,

   255    then it constructs a tuple object whose first item is the *ierr* value and whose

   256    second item is the corresponding error message (gotten from

   257    :cfunc:`FormatMessage`), and then calls ``PyErr_SetObject(PyExc_WindowsError,

   258    object)``. This function always returns *NULL*. Availability: Windows.

   259 

   260 

   261 .. cfunction:: PyObject* PyErr_SetExcFromWindowsErr(PyObject *type, int ierr)

   262 

   263    Similar to :cfunc:`PyErr_SetFromWindowsErr`, with an additional parameter

   264    specifying the exception type to be raised. Availability: Windows.

   265 

   266    .. versionadded:: 2.3

   267 

   268 

   269 .. cfunction:: PyObject* PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename)

   270 

   271    Similar to :cfunc:`PyErr_SetFromWindowsErr`, with the additional behavior that

   272    if *filename* is not *NULL*, it is passed to the constructor of

   273    :exc:`WindowsError` as a third parameter. Availability: Windows.

   274 

   275 

   276 .. cfunction:: PyObject* PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, char *filename)

   277 

   278    Similar to :cfunc:`PyErr_SetFromWindowsErrWithFilename`, with an additional

   279    parameter specifying the exception type to be raised. Availability: Windows.

   280 

   281    .. versionadded:: 2.3

   282 

   283 

   284 .. cfunction:: void PyErr_BadInternalCall()

   285 

   286    This is a shorthand for ``PyErr_SetString(PyExc_TypeError, message)``, where

   287    *message* indicates that an internal operation (e.g. a Python/C API function)

   288    was invoked with an illegal argument.  It is mostly for internal use.

   289 

   290 

   291 .. cfunction:: int PyErr_WarnEx(PyObject *category, char *message, int stacklevel)

   292 

   293    Issue a warning message.  The *category* argument is a warning category (see

   294    below) or *NULL*; the *message* argument is a message string.  *stacklevel* is a

   295    positive number giving a number of stack frames; the warning will be issued from

   296    the  currently executing line of code in that stack frame.  A *stacklevel* of 1

   297    is the function calling :cfunc:`PyErr_WarnEx`, 2 is  the function above that,

   298    and so forth.

   299 

   300    This function normally prints a warning message to *sys.stderr*; however, it is

   301    also possible that the user has specified that warnings are to be turned into

   302    errors, and in that case this will raise an exception.  It is also possible that

   303    the function raises an exception because of a problem with the warning machinery

   304    (the implementation imports the :mod:`warnings` module to do the heavy lifting).

   305    The return value is ``0`` if no exception is raised, or ``-1`` if an exception

   306    is raised.  (It is not possible to determine whether a warning message is

   307    actually printed, nor what the reason is for the exception; this is

   308    intentional.)  If an exception is raised, the caller should do its normal

   309    exception handling (for example, :cfunc:`Py_DECREF` owned references and return

   310    an error value).

   311 

   312    Warning categories must be subclasses of :cdata:`Warning`; the default warning

   313    category is :cdata:`RuntimeWarning`.  The standard Python warning categories are

   314    available as global variables whose names are ``PyExc_`` followed by the Python

   315    exception name. These have the type :ctype:`PyObject\*`; they are all class

   316    objects. Their names are :cdata:`PyExc_Warning`, :cdata:`PyExc_UserWarning`,

   317    :cdata:`PyExc_UnicodeWarning`, :cdata:`PyExc_DeprecationWarning`,

   318    :cdata:`PyExc_SyntaxWarning`, :cdata:`PyExc_RuntimeWarning`, and

   319    :cdata:`PyExc_FutureWarning`.  :cdata:`PyExc_Warning` is a subclass of

   320    :cdata:`PyExc_Exception`; the other warning categories are subclasses of

   321    :cdata:`PyExc_Warning`.

   322 

   323    For information about warning control, see the documentation for the

   324    :mod:`warnings` module and the :option:`-W` option in the command line

   325    documentation.  There is no C API for warning control.

   326 

   327 

   328 .. cfunction:: int PyErr_Warn(PyObject *category, char *message)

   329 

   330    Issue a warning message.  The *category* argument is a warning category (see

   331    below) or *NULL*; the *message* argument is a message string.  The warning will

   332    appear to be issued from the function calling :cfunc:`PyErr_Warn`, equivalent to

   333    calling :cfunc:`PyErr_WarnEx` with a *stacklevel* of 1.

   334 

   335    Deprecated; use :cfunc:`PyErr_WarnEx` instead.

   336 

   337 

   338 .. cfunction:: int PyErr_WarnExplicit(PyObject *category, const char *message, const char *filename, int lineno, const char *module, PyObject *registry)

   339 

   340    Issue a warning message with explicit control over all warning attributes.  This

   341    is a straightforward wrapper around the Python function

   342    :func:`warnings.warn_explicit`, see there for more information.  The *module*

   343    and *registry* arguments may be set to *NULL* to get the default effect

   344    described there.

   345 

   346 

   347 .. cfunction:: int PyErr_WarnPy3k(char *message, int stacklevel)

   348 

   349    Issue a :exc:`DeprecationWarning` with the given *message* and *stacklevel*

   350    if the :cdata:`Py_Py3kWarningFlag` flag is enabled.

   351 

   352    .. versionadded:: 2.6

   353 

   354 

   355 .. cfunction:: int PyErr_CheckSignals()

   356 

   357    .. index::

   358       module: signal

   359       single: SIGINT

   360       single: KeyboardInterrupt (built-in exception)

   361 

   362    This function interacts with Python's signal handling.  It checks whether a

   363    signal has been sent to the processes and if so, invokes the corresponding

   364    signal handler.  If the :mod:`signal` module is supported, this can invoke a

   365    signal handler written in Python.  In all cases, the default effect for

   366    :const:`SIGINT` is to raise the  :exc:`KeyboardInterrupt` exception.  If an

   367    exception is raised the error indicator is set and the function returns ``-1``;

   368    otherwise the function returns ``0``.  The error indicator may or may not be

   369    cleared if it was previously set.

   370 

   371 

   372 .. cfunction:: void PyErr_SetInterrupt()

   373 

   374    .. index::

   375       single: SIGINT

   376       single: KeyboardInterrupt (built-in exception)

   377 

   378    This function simulates the effect of a :const:`SIGINT` signal arriving --- the

   379    next time :cfunc:`PyErr_CheckSignals` is called,  :exc:`KeyboardInterrupt` will

   380    be raised.  It may be called without holding the interpreter lock.

   381 

   382    .. % XXX This was described as obsolete, but is used in

   383    .. % thread.interrupt_main() (used from IDLE), so it's still needed.

   384 

   385 

   386 .. cfunction:: int PySignal_SetWakeupFd(int fd)

   387 

   388    This utility function specifies a file descriptor to which a ``'\0'`` byte will

   389    be written whenever a signal is received.  It returns the previous such file

   390    descriptor.  The value ``-1`` disables the feature; this is the initial state.

   391    This is equivalent to :func:`signal.set_wakeup_fd` in Python, but without any

   392    error checking.  *fd* should be a valid file descriptor.  The function should

   393    only be called from the main thread.

   394 

   395 

   396 .. cfunction:: PyObject* PyErr_NewException(char *name, PyObject *base, PyObject *dict)

   397 

   398    This utility function creates and returns a new exception object. The *name*

   399    argument must be the name of the new exception, a C string of the form

   400    ``module.class``.  The *base* and *dict* arguments are normally *NULL*.  This

   401    creates a class object derived from :exc:`Exception` (accessible in C as

   402    :cdata:`PyExc_Exception`).

   403 

   404    The :attr:`__module__` attribute of the new class is set to the first part (up

   405    to the last dot) of the *name* argument, and the class name is set to the last

   406    part (after the last dot).  The *base* argument can be used to specify alternate

   407    base classes; it can either be only one class or a tuple of classes. The *dict*

   408    argument can be used to specify a dictionary of class variables and methods.

   409 

   410 

   411 .. cfunction:: void PyErr_WriteUnraisable(PyObject *obj)

   412 

   413    This utility function prints a warning message to ``sys.stderr`` when an

   414    exception has been set but it is impossible for the interpreter to actually

   415    raise the exception.  It is used, for example, when an exception occurs in an

   416    :meth:`__del__` method.

   417 

   418    The function is called with a single argument *obj* that identifies the context

   419    in which the unraisable exception occurred. The repr of *obj* will be printed in

   420    the warning message.

   421 

   422 

   423 .. _standardexceptions:

   424 

   425 Standard Exceptions

   426 ===================

   427 

   428 All standard Python exceptions are available as global variables whose names are

   429 ``PyExc_`` followed by the Python exception name.  These have the type

   430 :ctype:`PyObject\*`; they are all class objects.  For completeness, here are all

   431 the variables:

   432 

   433 +------------------------------------+----------------------------+----------+

   434 | C Name                             | Python Name                | Notes    |

   435 +====================================+============================+==========+

   436 | :cdata:`PyExc_BaseException`       | :exc:`BaseException`       | (1), (4) |

   437 +------------------------------------+----------------------------+----------+

   438 | :cdata:`PyExc_Exception`           | :exc:`Exception`           | \(1)     |

   439 +------------------------------------+----------------------------+----------+

   440 | :cdata:`PyExc_StandardError`       | :exc:`StandardError`       | \(1)     |

   441 +------------------------------------+----------------------------+----------+

   442 | :cdata:`PyExc_ArithmeticError`     | :exc:`ArithmeticError`     | \(1)     |

   443 +------------------------------------+----------------------------+----------+

   444 | :cdata:`PyExc_LookupError`         | :exc:`LookupError`         | \(1)     |

   445 +------------------------------------+----------------------------+----------+

   446 | :cdata:`PyExc_AssertionError`      | :exc:`AssertionError`      |          |

   447 +------------------------------------+----------------------------+----------+

   448 | :cdata:`PyExc_AttributeError`      | :exc:`AttributeError`      |          |

   449 +------------------------------------+----------------------------+----------+

   450 | :cdata:`PyExc_EOFError`            | :exc:`EOFError`            |          |

   451 +------------------------------------+----------------------------+----------+

   452 | :cdata:`PyExc_EnvironmentError`    | :exc:`EnvironmentError`    | \(1)     |

   453 +------------------------------------+----------------------------+----------+

   454 | :cdata:`PyExc_FloatingPointError`  | :exc:`FloatingPointError`  |          |

   455 +------------------------------------+----------------------------+----------+

   456 | :cdata:`PyExc_IOError`             | :exc:`IOError`             |          |

   457 +------------------------------------+----------------------------+----------+

   458 | :cdata:`PyExc_ImportError`         | :exc:`ImportError`         |          |

   459 +------------------------------------+----------------------------+----------+

   460 | :cdata:`PyExc_IndexError`          | :exc:`IndexError`          |          |

   461 +------------------------------------+----------------------------+----------+

   462 | :cdata:`PyExc_KeyError`            | :exc:`KeyError`            |          |

   463 +------------------------------------+----------------------------+----------+

   464 | :cdata:`PyExc_KeyboardInterrupt`   | :exc:`KeyboardInterrupt`   |          |

   465 +------------------------------------+----------------------------+----------+

   466 | :cdata:`PyExc_MemoryError`         | :exc:`MemoryError`         |          |

   467 +------------------------------------+----------------------------+----------+

   468 | :cdata:`PyExc_NameError`           | :exc:`NameError`           |          |

   469 +------------------------------------+----------------------------+----------+

   470 | :cdata:`PyExc_NotImplementedError` | :exc:`NotImplementedError` |          |

   471 +------------------------------------+----------------------------+----------+

   472 | :cdata:`PyExc_OSError`             | :exc:`OSError`             |          |

   473 +------------------------------------+----------------------------+----------+

   474 | :cdata:`PyExc_OverflowError`       | :exc:`OverflowError`       |          |

   475 +------------------------------------+----------------------------+----------+

   476 | :cdata:`PyExc_ReferenceError`      | :exc:`ReferenceError`      | \(2)     |

   477 +------------------------------------+----------------------------+----------+

   478 | :cdata:`PyExc_RuntimeError`        | :exc:`RuntimeError`        |          |

   479 +------------------------------------+----------------------------+----------+

   480 | :cdata:`PyExc_SyntaxError`         | :exc:`SyntaxError`         |          |

   481 +------------------------------------+----------------------------+----------+

   482 | :cdata:`PyExc_SystemError`         | :exc:`SystemError`         |          |

   483 +------------------------------------+----------------------------+----------+

   484 | :cdata:`PyExc_SystemExit`          | :exc:`SystemExit`          |          |

   485 +------------------------------------+----------------------------+----------+

   486 | :cdata:`PyExc_TypeError`           | :exc:`TypeError`           |          |

   487 +------------------------------------+----------------------------+----------+

   488 | :cdata:`PyExc_ValueError`          | :exc:`ValueError`          |          |

   489 +------------------------------------+----------------------------+----------+

   490 | :cdata:`PyExc_WindowsError`        | :exc:`WindowsError`        | \(3)     |

   491 +------------------------------------+----------------------------+----------+

   492 | :cdata:`PyExc_ZeroDivisionError`   | :exc:`ZeroDivisionError`   |          |

   493 +------------------------------------+----------------------------+----------+

   494 

   495 .. index::

   496    single: PyExc_BaseException

   497    single: PyExc_Exception

   498    single: PyExc_StandardError

   499    single: PyExc_ArithmeticError

   500    single: PyExc_LookupError

   501    single: PyExc_AssertionError

   502    single: PyExc_AttributeError

   503    single: PyExc_EOFError

   504    single: PyExc_EnvironmentError

   505    single: PyExc_FloatingPointError

   506    single: PyExc_IOError

   507    single: PyExc_ImportError

   508    single: PyExc_IndexError

   509    single: PyExc_KeyError

   510    single: PyExc_KeyboardInterrupt

   511    single: PyExc_MemoryError

   512    single: PyExc_NameError

   513    single: PyExc_NotImplementedError

   514    single: PyExc_OSError

   515    single: PyExc_OverflowError

   516    single: PyExc_ReferenceError

   517    single: PyExc_RuntimeError

   518    single: PyExc_SyntaxError

   519    single: PyExc_SystemError

   520    single: PyExc_SystemExit

   521    single: PyExc_TypeError

   522    single: PyExc_ValueError

   523    single: PyExc_WindowsError

   524    single: PyExc_ZeroDivisionError

   525 

   526 Notes:

   527 

   528 (1)

   529    This is a base class for other standard exceptions.

   530 

   531 (2)

   532    This is the same as :exc:`weakref.ReferenceError`.

   533 

   534 (3)

   535    Only defined on Windows; protect code that uses this by testing that the

   536    preprocessor macro ``MS_WINDOWS`` is defined.

   537 

   538 (4)

   539    .. versionadded:: 2.5

   540 

   541 

   542 Deprecation of String Exceptions

   543 ================================

   544 

   545 .. index:: single: BaseException (built-in exception)

   546 

   547 All exceptions built into Python or provided in the standard library are derived

   548 from :exc:`BaseException`.

   549 

   550 String exceptions are still supported in the interpreter to allow existing code

   551 to run unmodified, but this will also change in a future release.

   552