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    .. % Similar comments apply to the %ll width modifier and
 165    .. % PY_FORMAT_LONG_LONG.
 166    .. % %u, %lu, %zu should have "new in Python 2.5" blurbs.
 167
 168    +-------------------+---------------+--------------------------------+
 169    | Format Characters | Type          | Comment                        |
 170    +===================+===============+================================+
 171    | :attr:`%%`        | *n/a*         | The literal % character.       |
 172    +-------------------+---------------+--------------------------------+
 173    | :attr:`%c`        | int           | A single character,            |
 174    |                   |               | represented as an C int.       |
 175    +-------------------+---------------+--------------------------------+
 176    | :attr:`%d`        | int           | Exactly equivalent to          |
 177    |                   |               | ``printf("%d")``.              |
 178    +-------------------+---------------+--------------------------------+
 179    | :attr:`%u`        | unsigned int  | Exactly equivalent to          |
 180    |                   |               | ``printf("%u")``.              |
 181    +-------------------+---------------+--------------------------------+
 182    | :attr:`%ld`       | long          | Exactly equivalent to          |
 183    |                   |               | ``printf("%ld")``.             |
 184    +-------------------+---------------+--------------------------------+
 185    | :attr:`%lu`       | unsigned long | Exactly equivalent to          |
 186    |                   |               | ``printf("%lu")``.             |
 187    +-------------------+---------------+--------------------------------+
 188    | :attr:`%lld`      | long long     | Exactly equivalent to          |
 189    |                   |               | ``printf("%lld")``.            |
 190    +-------------------+---------------+--------------------------------+
 191    | :attr:`%llu`      | unsigned      | Exactly equivalent to          |
 192    |                   | long long     | ``printf("%llu")``.            |
 193    +-------------------+---------------+--------------------------------+
 194    | :attr:`%zd`       | Py_ssize_t    | Exactly equivalent to          |
 195    |                   |               | ``printf("%zd")``.             |
 196    +-------------------+---------------+--------------------------------+
 197    | :attr:`%zu`       | size_t        | Exactly equivalent to          |
 198    |                   |               | ``printf("%zu")``.             |
 199    +-------------------+---------------+--------------------------------+
 200    | :attr:`%i`        | int           | Exactly equivalent to          |
 201    |                   |               | ``printf("%i")``.              |
 202    +-------------------+---------------+--------------------------------+
 203    | :attr:`%x`        | int           | Exactly equivalent to          |
 204    |                   |               | ``printf("%x")``.              |
 205    +-------------------+---------------+--------------------------------+
 206    | :attr:`%s`        | char\*        | A null-terminated C character  |
 207    |                   |               | array.                         |
 208    +-------------------+---------------+--------------------------------+
 209    | :attr:`%p`        | void\*        | The hex representation of a C  |
 210    |                   |               | pointer. Mostly equivalent to  |
 211    |                   |               | ``printf("%p")`` except that   |
 212    |                   |               | it is guaranteed to start with |
 213    |                   |               | the literal ``0x`` regardless  |
 214    |                   |               | of what the platform's         |
 215    |                   |               | ``printf`` yields.             |
 216    +-------------------+---------------+--------------------------------+
 217
 218    An unrecognized format character causes all the rest of the format string to be
 219    copied as-is to the result string, and any extra arguments discarded.
 220
 221    .. note::
 222
 223       The `"%lld"` and `"%llu"` format specifiers are only available
 224       when :const:`HAVE_LONG_LONG` is defined.
 225
 226    .. versionchanged:: 2.7
 227       Support for `"%lld"` and `"%llu"` added.
 228
 229
 230 .. cfunction:: void PyErr_SetNone(PyObject *type)
 231
 232    This is a shorthand for ``PyErr_SetObject(type, Py_None)``.
 233
 234
 235 .. cfunction:: int PyErr_BadArgument()
 236
 237    This is a shorthand for ``PyErr_SetString(PyExc_TypeError, message)``, where
 238    *message* indicates that a built-in operation was invoked with an illegal
 239    argument.  It is mostly for internal use.
 240
 241
 242 .. cfunction:: PyObject* PyErr_NoMemory()
 243
 244    This is a shorthand for ``PyErr_SetNone(PyExc_MemoryError)``; it returns *NULL*
 245    so an object allocation function can write ``return PyErr_NoMemory();`` when it
 246    runs out of memory.
 247
 248
 249 .. cfunction:: PyObject* PyErr_SetFromErrno(PyObject *type)
 250
 251    .. index:: single: strerror()
 252
 253    This is a convenience function to raise an exception when a C library function
 254    has returned an error and set the C variable :cdata:`errno`.  It constructs a
 255    tuple object whose first item is the integer :cdata:`errno` value and whose
 256    second item is the corresponding error message (gotten from :cfunc:`strerror`),
 257    and then calls ``PyErr_SetObject(type, object)``.  On Unix, when the
 258    :cdata:`errno` value is :const:`EINTR`, indicating an interrupted system call,
 259    this calls :cfunc:`PyErr_CheckSignals`, and if that set the error indicator,
 260    leaves it set to that.  The function always returns *NULL*, so a wrapper
 261    function around a system call can write ``return PyErr_SetFromErrno(type);``
 262    when the system call returns an error.
 263
 264
 265 .. cfunction:: PyObject* PyErr_SetFromErrnoWithFilename(PyObject *type, const char *filename)
 266
 267    Similar to :cfunc:`PyErr_SetFromErrno`, with the additional behavior that if
 268    *filename* is not *NULL*, it is passed to the constructor of *type* as a third
 269    parameter.  In the case of exceptions such as :exc:`IOError` and :exc:`OSError`,
 270    this is used to define the :attr:`filename` attribute of the exception instance.
 271
 272
 273 .. cfunction:: PyObject* PyErr_SetFromWindowsErr(int ierr)
 274
 275    This is a convenience function to raise :exc:`WindowsError`. If called with
 276    *ierr* of :cdata:`0`, the error code returned by a call to :cfunc:`GetLastError`
 277    is used instead.  It calls the Win32 function :cfunc:`FormatMessage` to retrieve
 278    the Windows description of error code given by *ierr* or :cfunc:`GetLastError`,
 279    then it constructs a tuple object whose first item is the *ierr* value and whose
 280    second item is the corresponding error message (gotten from
 281    :cfunc:`FormatMessage`), and then calls ``PyErr_SetObject(PyExc_WindowsError,
 282    object)``. This function always returns *NULL*. Availability: Windows.
 283
 284
 285 .. cfunction:: PyObject* PyErr_SetExcFromWindowsErr(PyObject *type, int ierr)
 286
 287    Similar to :cfunc:`PyErr_SetFromWindowsErr`, with an additional parameter
 288    specifying the exception type to be raised. Availability: Windows.
 289
 290    .. versionadded:: 2.3
 291
 292
 293 .. cfunction:: PyObject* PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename)
 294
 295    Similar to :cfunc:`PyErr_SetFromWindowsErr`, with the additional behavior that
 296    if *filename* is not *NULL*, it is passed to the constructor of
 297    :exc:`WindowsError` as a third parameter. Availability: Windows.
 298
 299
 300 .. cfunction:: PyObject* PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, char *filename)
 301
 302    Similar to :cfunc:`PyErr_SetFromWindowsErrWithFilename`, with an additional
 303    parameter specifying the exception type to be raised. Availability: Windows.
 304
 305    .. versionadded:: 2.3
 306
 307
 308 .. cfunction:: void PyErr_BadInternalCall()
 309
 310    This is a shorthand for ``PyErr_SetString(PyExc_SystemError, message)``,
 311    where *message* indicates that an internal operation (e.g. a Python/C API
 312    function) was invoked with an illegal argument.  It is mostly for internal
 313    use.
 314
 315
 316 .. cfunction:: int PyErr_WarnEx(PyObject *category, char *message, int stacklevel)
 317
 318    Issue a warning message.  The *category* argument is a warning category (see
 319    below) or *NULL*; the *message* argument is a message string.  *stacklevel* is a
 320    positive number giving a number of stack frames; the warning will be issued from
 321    the  currently executing line of code in that stack frame.  A *stacklevel* of 1
 322    is the function calling :cfunc:`PyErr_WarnEx`, 2 is  the function above that,
 323    and so forth.
 324
 325    This function normally prints a warning message to *sys.stderr*; however, it is
 326    also possible that the user has specified that warnings are to be turned into
 327    errors, and in that case this will raise an exception.  It is also possible that
 328    the function raises an exception because of a problem with the warning machinery
 329    (the implementation imports the :mod:`warnings` module to do the heavy lifting).
 330    The return value is ``0`` if no exception is raised, or ``-1`` if an exception
 331    is raised.  (It is not possible to determine whether a warning message is
 332    actually printed, nor what the reason is for the exception; this is
 333    intentional.)  If an exception is raised, the caller should do its normal
 334    exception handling (for example, :cfunc:`Py_DECREF` owned references and return
 335    an error value).
 336
 337    Warning categories must be subclasses of :cdata:`Warning`; the default warning
 338    category is :cdata:`RuntimeWarning`.  The standard Python warning categories are
 339    available as global variables whose names are ``PyExc_`` followed by the Python
 340    exception name. These have the type :ctype:`PyObject\*`; they are all class
 341    objects. Their names are :cdata:`PyExc_Warning`, :cdata:`PyExc_UserWarning`,
 342    :cdata:`PyExc_UnicodeWarning`, :cdata:`PyExc_DeprecationWarning`,
 343    :cdata:`PyExc_SyntaxWarning`, :cdata:`PyExc_RuntimeWarning`, and
 344    :cdata:`PyExc_FutureWarning`.  :cdata:`PyExc_Warning` is a subclass of
 345    :cdata:`PyExc_Exception`; the other warning categories are subclasses of
 346    :cdata:`PyExc_Warning`.
 347
 348    For information about warning control, see the documentation for the
 349    :mod:`warnings` module and the :option:`-W` option in the command line
 350    documentation.  There is no C API for warning control.
 351
 352
 353 .. cfunction:: int PyErr_Warn(PyObject *category, char *message)
 354
 355    Issue a warning message.  The *category* argument is a warning category (see
 356    below) or *NULL*; the *message* argument is a message string.  The warning will
 357    appear to be issued from the function calling :cfunc:`PyErr_Warn`, equivalent to
 358    calling :cfunc:`PyErr_WarnEx` with a *stacklevel* of 1.
 359
 360    Deprecated; use :cfunc:`PyErr_WarnEx` instead.
 361
 362
 363 .. cfunction:: int PyErr_WarnExplicit(PyObject *category, const char *message, const char *filename, int lineno, const char *module, PyObject *registry)
 364
 365    Issue a warning message with explicit control over all warning attributes.  This
 366    is a straightforward wrapper around the Python function
 367    :func:`warnings.warn_explicit`, see there for more information.  The *module*
 368    and *registry* arguments may be set to *NULL* to get the default effect
 369    described there.
 370
 371
 372 .. cfunction:: int PyErr_WarnPy3k(char *message, int stacklevel)
 373
 374    Issue a :exc:`DeprecationWarning` with the given *message* and *stacklevel*
 375    if the :cdata:`Py_Py3kWarningFlag` flag is enabled.
 376
 377    .. versionadded:: 2.6
 378
 379
 380 .. cfunction:: int PyErr_CheckSignals()
 381
 382    .. index::
 383       module: signal
 384       single: SIGINT
 385       single: KeyboardInterrupt (built-in exception)
 386
 387    This function interacts with Python's signal handling.  It checks whether a
 388    signal has been sent to the processes and if so, invokes the corresponding
 389    signal handler.  If the :mod:`signal` module is supported, this can invoke a
 390    signal handler written in Python.  In all cases, the default effect for
 391    :const:`SIGINT` is to raise the  :exc:`KeyboardInterrupt` exception.  If an
 392    exception is raised the error indicator is set and the function returns ``-1``;
 393    otherwise the function returns ``0``.  The error indicator may or may not be
 394    cleared if it was previously set.
 395
 396
 397 .. cfunction:: void PyErr_SetInterrupt()
 398
 399    .. index::
 400       single: SIGINT
 401       single: KeyboardInterrupt (built-in exception)
 402
 403    This function simulates the effect of a :const:`SIGINT` signal arriving --- the
 404    next time :cfunc:`PyErr_CheckSignals` is called,  :exc:`KeyboardInterrupt` will
 405    be raised.  It may be called without holding the interpreter lock.
 406
 407    .. % XXX This was described as obsolete, but is used in
 408    .. % thread.interrupt_main() (used from IDLE), so it's still needed.
 409
 410
 411 .. cfunction:: int PySignal_SetWakeupFd(int fd)
 412
 413    This utility function specifies a file descriptor to which a ``'\0'`` byte will
 414    be written whenever a signal is received.  It returns the previous such file
 415    descriptor.  The value ``-1`` disables the feature; this is the initial state.
 416    This is equivalent to :func:`signal.set_wakeup_fd` in Python, but without any
 417    error checking.  *fd* should be a valid file descriptor.  The function should
 418    only be called from the main thread.
 419
 420
 421 .. cfunction:: PyObject* PyErr_NewException(char *name, PyObject *base, PyObject *dict)
 422
 423    This utility function creates and returns a new exception object. The *name*
 424    argument must be the name of the new exception, a C string of the form
 425    ``module.class``.  The *base* and *dict* arguments are normally *NULL*.  This
 426    creates a class object derived from :exc:`Exception` (accessible in C as
 427    :cdata:`PyExc_Exception`).
 428
 429    The :attr:`__module__` attribute of the new class is set to the first part (up
 430    to the last dot) of the *name* argument, and the class name is set to the last
 431    part (after the last dot).  The *base* argument can be used to specify alternate
 432    base classes; it can either be only one class or a tuple of classes. The *dict*
 433    argument can be used to specify a dictionary of class variables and methods.
 434
 435
 436 .. cfunction:: PyObject* PyErr_NewExceptionWithDoc(char *name, char *doc, PyObject *base, PyObject *dict)
 437
 438    Same as :cfunc:`PyErr_NewException`, except that the new exception class can
 439    easily be given a docstring: If *doc* is non-*NULL*, it will be used as the
 440    docstring for the exception class.
 441
 442    .. versionadded:: 2.7
 443
 444
 445 .. cfunction:: void PyErr_WriteUnraisable(PyObject *obj)
 446
 447    This utility function prints a warning message to ``sys.stderr`` when an
 448    exception has been set but it is impossible for the interpreter to actually
 449    raise the exception.  It is used, for example, when an exception occurs in an
 450    :meth:`__del__` method.
 451
 452    The function is called with a single argument *obj* that identifies the context
 453    in which the unraisable exception occurred. The repr of *obj* will be printed in
 454    the warning message.
 455
 456
 457 .. _unicodeexceptions:
 458
 459 Unicode Exception Objects
 460 =========================
 461
 462 The following functions are used to create and modify Unicode exceptions from C.
 463
 464 .. cfunction:: PyObject* PyUnicodeDecodeError_Create(const char *encoding, const char *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
 465
 466    Create a :class:`UnicodeDecodeError` object with the attributes *encoding*,
 467    *object*, *length*, *start*, *end* and *reason*.
 468
 469 .. cfunction:: 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)
 470
 471    Create a :class:`UnicodeEncodeError` object with the attributes *encoding*,
 472    *object*, *length*, *start*, *end* and *reason*.
 473
 474 .. cfunction:: PyObject* PyUnicodeTranslateError_Create(const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
 475
 476    Create a :class:`UnicodeTranslateError` object with the attributes *object*,
 477    *length*, *start*, *end* and *reason*.
 478
 479 .. cfunction:: PyObject* PyUnicodeDecodeError_GetEncoding(PyObject *exc)
 480                PyObject* PyUnicodeEncodeError_GetEncoding(PyObject *exc)
 481
 482    Return the *encoding* attribute of the given exception object.
 483
 484 .. cfunction:: PyObject* PyUnicodeDecodeError_GetObject(PyObject *exc)
 485                PyObject* PyUnicodeEncodeError_GetObject(PyObject *exc)
 486                PyObject* PyUnicodeTranslateError_GetObject(PyObject *exc)
 487
 488    Return the *object* attribute of the given exception object.
 489
 490 .. cfunction:: int PyUnicodeDecodeError_GetStart(PyObject *exc, Py_ssize_t *start)
 491                int PyUnicodeEncodeError_GetStart(PyObject *exc, Py_ssize_t *start)
 492                int PyUnicodeTranslateError_GetStart(PyObject *exc, Py_ssize_t *start)
 493
 494    Get the *start* attribute of the given exception object and place it into
 495    *\*start*.  *start* must not be *NULL*.  Return ``0`` on success, ``-1`` on
 496    failure.
 497
 498 .. cfunction:: int PyUnicodeDecodeError_SetStart(PyObject *exc, Py_ssize_t start)
 499                int PyUnicodeEncodeError_SetStart(PyObject *exc, Py_ssize_t start)
 500                int PyUnicodeTranslateError_SetStart(PyObject *exc, Py_ssize_t start)
 501
 502    Set the *start* attribute of the given exception object to *start*.  Return
 503    ``0`` on success, ``-1`` on failure.
 504
 505 .. cfunction:: int PyUnicodeDecodeError_GetEnd(PyObject *exc, Py_ssize_t *end)
 506                int PyUnicodeEncodeError_GetEnd(PyObject *exc, Py_ssize_t *end)
 507                int PyUnicodeTranslateError_GetEnd(PyObject *exc, Py_ssize_t *end)
 508
 509    Get the *end* attribute of the given exception object and place it into
 510    *\*end*.  *end* must not be *NULL*.  Return ``0`` on success, ``-1`` on
 511    failure.
 512
 513 .. cfunction:: int PyUnicodeDecodeError_SetEnd(PyObject *exc, Py_ssize_t end)
 514                int PyUnicodeEncodeError_SetEnd(PyObject *exc, Py_ssize_t end)
 515                int PyUnicodeTranslateError_SetEnd(PyObject *exc, Py_ssize_t end)
 516
 517    Set the *end* attribute of the given exception object to *end*.  Return ``0``
 518    on success, ``-1`` on failure.
 519
 520 .. cfunction:: PyObject* PyUnicodeDecodeError_GetReason(PyObject *exc)
 521                PyObject* PyUnicodeEncodeError_GetReason(PyObject *exc)
 522                PyObject* PyUnicodeTranslateError_GetReason(PyObject *exc)
 523
 524    Return the *reason* attribute of the given exception object.
 525
 526 .. cfunction:: int PyUnicodeDecodeError_SetReason(PyObject *exc, const char *reason)
 527                int PyUnicodeEncodeError_SetReason(PyObject *exc, const char *reason)
 528                int PyUnicodeTranslateError_SetReason(PyObject *exc, const char *reason)
 529
 530    Set the *reason* attribute of the given exception object to *reason*.  Return
 531    ``0`` on success, ``-1`` on failure.
 532
 533
 534 Recursion Control
 535 =================
 536
 537 These two functions provide a way to perform safe recursive calls at the C
 538 level, both in the core and in extension modules.  They are needed if the
 539 recursive code does not necessarily invoke Python code (which tracks its
 540 recursion depth automatically).
 541
 542 .. cfunction:: int Py_EnterRecursiveCall(char *where)
 543
 544    Marks a point where a recursive C-level call is about to be performed.
 545
 546    If :const:`USE_STACKCHECK` is defined, this function checks if the the OS
 547    stack overflowed using :cfunc:`PyOS_CheckStack`.  In this is the case, it
 548    sets a :exc:`MemoryError` and returns a nonzero value.
 549
 550    The function then checks if the recursion limit is reached.  If this is the
 551    case, a :exc:`RuntimeError` is set and a nonzero value is returned.
 552    Otherwise, zero is returned.
 553
 554    *where* should be a string such as ``" in instance check"`` to be
 555    concatenated to the :exc:`RuntimeError` message caused by the recursion depth
 556    limit.
 557
 558 .. cfunction:: void Py_LeaveRecursiveCall()
 559
 560    Ends a :cfunc:`Py_EnterRecursiveCall`.  Must be called once for each
 561    *successful* invocation of :cfunc:`Py_EnterRecursiveCall`.
 562
 563
 564 .. _standardexceptions:
 565
 566 Standard Exceptions
 567 ===================
 568
 569 All standard Python exceptions are available as global variables whose names are
 570 ``PyExc_`` followed by the Python exception name.  These have the type
 571 :ctype:`PyObject\*`; they are all class objects.  For completeness, here are all
 572 the variables:
 573
 574 +------------------------------------+----------------------------+----------+
 575 | C Name                             | Python Name                | Notes    |
 576 +====================================+============================+==========+
 577 | :cdata:`PyExc_BaseException`       | :exc:`BaseException`       | (1), (4) |
 578 +------------------------------------+----------------------------+----------+
 579 | :cdata:`PyExc_Exception`           | :exc:`Exception`           | \(1)     |
 580 +------------------------------------+----------------------------+----------+
 581 | :cdata:`PyExc_StandardError`       | :exc:`StandardError`       | \(1)     |
 582 +------------------------------------+----------------------------+----------+
 583 | :cdata:`PyExc_ArithmeticError`     | :exc:`ArithmeticError`     | \(1)     |
 584 +------------------------------------+----------------------------+----------+
 585 | :cdata:`PyExc_LookupError`         | :exc:`LookupError`         | \(1)     |
 586 +------------------------------------+----------------------------+----------+
 587 | :cdata:`PyExc_AssertionError`      | :exc:`AssertionError`      |          |
 588 +------------------------------------+----------------------------+----------+
 589 | :cdata:`PyExc_AttributeError`      | :exc:`AttributeError`      |          |
 590 +------------------------------------+----------------------------+----------+
 591 | :cdata:`PyExc_EOFError`            | :exc:`EOFError`            |          |
 592 +------------------------------------+----------------------------+----------+
 593 | :cdata:`PyExc_EnvironmentError`    | :exc:`EnvironmentError`    | \(1)     |
 594 +------------------------------------+----------------------------+----------+
 595 | :cdata:`PyExc_FloatingPointError`  | :exc:`FloatingPointError`  |          |
 596 +------------------------------------+----------------------------+----------+
 597 | :cdata:`PyExc_IOError`             | :exc:`IOError`             |          |
 598 +------------------------------------+----------------------------+----------+
 599 | :cdata:`PyExc_ImportError`         | :exc:`ImportError`         |          |
 600 +------------------------------------+----------------------------+----------+
 601 | :cdata:`PyExc_IndexError`          | :exc:`IndexError`          |          |
 602 +------------------------------------+----------------------------+----------+
 603 | :cdata:`PyExc_KeyError`            | :exc:`KeyError`            |          |
 604 +------------------------------------+----------------------------+----------+
 605 | :cdata:`PyExc_KeyboardInterrupt`   | :exc:`KeyboardInterrupt`   |          |
 606 +------------------------------------+----------------------------+----------+
 607 | :cdata:`PyExc_MemoryError`         | :exc:`MemoryError`         |          |
 608 +------------------------------------+----------------------------+----------+
 609 | :cdata:`PyExc_NameError`           | :exc:`NameError`           |          |
 610 +------------------------------------+----------------------------+----------+
 611 | :cdata:`PyExc_NotImplementedError` | :exc:`NotImplementedError` |          |
 612 +------------------------------------+----------------------------+----------+
 613 | :cdata:`PyExc_OSError`             | :exc:`OSError`             |          |
 614 +------------------------------------+----------------------------+----------+
 615 | :cdata:`PyExc_OverflowError`       | :exc:`OverflowError`       |          |
 616 +------------------------------------+----------------------------+----------+
 617 | :cdata:`PyExc_ReferenceError`      | :exc:`ReferenceError`      | \(2)     |
 618 +------------------------------------+----------------------------+----------+
 619 | :cdata:`PyExc_RuntimeError`        | :exc:`RuntimeError`        |          |
 620 +------------------------------------+----------------------------+----------+
 621 | :cdata:`PyExc_SyntaxError`         | :exc:`SyntaxError`         |          |
 622 +------------------------------------+----------------------------+----------+
 623 | :cdata:`PyExc_SystemError`         | :exc:`SystemError`         |          |
 624 +------------------------------------+----------------------------+----------+
 625 | :cdata:`PyExc_SystemExit`          | :exc:`SystemExit`          |          |
 626 +------------------------------------+----------------------------+----------+
 627 | :cdata:`PyExc_TypeError`           | :exc:`TypeError`           |          |
 628 +------------------------------------+----------------------------+----------+
 629 | :cdata:`PyExc_ValueError`          | :exc:`ValueError`          |          |
 630 +------------------------------------+----------------------------+----------+
 631 | :cdata:`PyExc_WindowsError`        | :exc:`WindowsError`        | \(3)     |
 632 +------------------------------------+----------------------------+----------+
 633 | :cdata:`PyExc_ZeroDivisionError`   | :exc:`ZeroDivisionError`   |          |
 634 +------------------------------------+----------------------------+----------+
 635
 636 .. index::
 637    single: PyExc_BaseException
 638    single: PyExc_Exception
 639    single: PyExc_StandardError
 640    single: PyExc_ArithmeticError
 641    single: PyExc_LookupError
 642    single: PyExc_AssertionError
 643    single: PyExc_AttributeError
 644    single: PyExc_EOFError
 645    single: PyExc_EnvironmentError
 646    single: PyExc_FloatingPointError
 647    single: PyExc_IOError
 648    single: PyExc_ImportError
 649    single: PyExc_IndexError
 650    single: PyExc_KeyError
 651    single: PyExc_KeyboardInterrupt
 652    single: PyExc_MemoryError
 653    single: PyExc_NameError
 654    single: PyExc_NotImplementedError
 655    single: PyExc_OSError
 656    single: PyExc_OverflowError
 657    single: PyExc_ReferenceError
 658    single: PyExc_RuntimeError
 659    single: PyExc_SyntaxError
 660    single: PyExc_SystemError
 661    single: PyExc_SystemExit
 662    single: PyExc_TypeError
 663    single: PyExc_ValueError
 664    single: PyExc_WindowsError
 665    single: PyExc_ZeroDivisionError
 666
 667 Notes:
 668
 669 (1)
 670    This is a base class for other standard exceptions.
 671
 672 (2)
 673    This is the same as :exc:`weakref.ReferenceError`.
 674
 675 (3)
 676    Only defined on Windows; protect code that uses this by testing that the
 677    preprocessor macro ``MS_WINDOWS`` is defined.
 678
 679 (4)
 680    .. versionadded:: 2.5
 681
 682
 683 Deprecation of String Exceptions
 684 ================================
 685
 686 .. index:: single: BaseException (built-in exception)
 687
 688 All exceptions built into Python or provided in the standard library are derived
 689 from :exc:`BaseException`.
 690
 691 String exceptions are still supported in the interpreter to allow existing code
 692 to run unmodified, but this will also change in a future release.
 693