Home | History | Annotate | Download | only in c-api 
      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 :c:data:`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 :c:func:`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 .. 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 
    408 Unicode Exception Objects
    409 =========================
    410 
    411 The 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 
    483 Recursion Control
    484 =================
    485 
    486 These two functions provide a way to perform safe recursive calls at the C
    487 level, both in the core and in extension modules.  They are needed if the
    488 recursive code does not necessarily invoke Python code (which tracks its
    489 recursion 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 
    515 Standard Exceptions
    516 ===================
    517 
    518 All 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
    521 the 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 
    649 Notes:
    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 
    670 Standard Warning Categories
    671 ===========================
    672 
    673 All standard Python warning categories are available as global variables whose
    674 names 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
    676 the 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 
    714 Notes:
    715 
    716 (1)
    717    This is a base class for other standard warning categories.
    718 
    719 String 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