1.. highlight:: c 2 3 4.. _exceptionhandling: 5 6****************** 7Exception Handling 8****************** 9 10The functions described in this chapter will let you handle and raise Python 11exceptions. It is important to understand some of the basics of Python 12exception handling. It works somewhat like the POSIX :c:data:`errno` variable: 13there is a global indicator (per thread) of the last error that occurred. Most 14C API functions don't clear this on success, but will set it to indicate the 15cause of the error on failure. Most C API functions also return an error 16indicator, usually ``NULL`` if they are supposed to return a pointer, or ``-1`` 17if they return an integer (exception: the :c:func:`PyArg_\*` functions 18return ``1`` for success and ``0`` for failure). 19 20Concretely, the error indicator consists of three object pointers: the 21exception's type, the exception's value, and the traceback object. Any 22of those pointers can be ``NULL`` if non-set (although some combinations are 23forbidden, for example you can't have a non-``NULL`` traceback if the exception 24type is ``NULL``). 25 26When a function must fail because some function it called failed, it generally 27doesn't set the error indicator; the function it called already set it. It is 28responsible for either handling the error and clearing the exception or 29returning after cleaning up any resources it holds (such as object references or 30memory allocations); it should *not* continue normally if it is not prepared to 31handle the error. If returning due to an error, it is important to indicate to 32the caller that an error has been set. If the error is not handled or carefully 33propagated, additional calls into the Python/C API may not behave as intended 34and may fail in mysterious ways. 35 36.. note:: 37 The error indicator is **not** the result of :func:`sys.exc_info()`. 38 The former corresponds to an exception that is not yet caught (and is 39 therefore still propagating), while the latter returns an exception after 40 it is caught (and has therefore stopped propagating). 41 42 43Printing and clearing 44===================== 45 46 47.. c:function:: void PyErr_Clear() 48 49 Clear the error indicator. If the error indicator is not set, there is no 50 effect. 51 52 53.. c:function:: void PyErr_PrintEx(int set_sys_last_vars) 54 55 Print a standard traceback to ``sys.stderr`` and clear the error indicator. 56 **Unless** the error is a ``SystemExit``, in that case no traceback is 57 printed and the Python process will exit with the error code specified by 58 the ``SystemExit`` instance. 59 60 Call this function **only** when the error indicator is set. Otherwise it 61 will cause a fatal error! 62 63 If *set_sys_last_vars* is nonzero, the variables :data:`sys.last_type`, 64 :data:`sys.last_value` and :data:`sys.last_traceback` will be set to the 65 type, value and traceback of the printed exception, respectively. 66 67 68.. c:function:: void PyErr_Print() 69 70 Alias for ``PyErr_PrintEx(1)``. 71 72 73.. c:function:: void PyErr_WriteUnraisable(PyObject *obj) 74 75 Call :func:`sys.unraisablehook` using the current exception and *obj* 76 argument. 77 78 This utility function prints a warning message to ``sys.stderr`` when an 79 exception has been set but it is impossible for the interpreter to actually 80 raise the exception. It is used, for example, when an exception occurs in an 81 :meth:`__del__` method. 82 83 The function is called with a single argument *obj* that identifies the context 84 in which the unraisable exception occurred. If possible, 85 the repr of *obj* will be printed in the warning message. 86 87 An exception must be set when calling this function. 88 89 90Raising exceptions 91================== 92 93These functions help you set the current thread's error indicator. 94For convenience, some of these functions will always return a 95``NULL`` pointer for use in a ``return`` statement. 96 97 98.. c:function:: void PyErr_SetString(PyObject *type, const char *message) 99 100 This is the most common way to set the error indicator. The first argument 101 specifies the exception type; it is normally one of the standard exceptions, 102 e.g. :c:data:`PyExc_RuntimeError`. You need not increment its reference count. 103 The second argument is an error message; it is decoded from ``'utf-8``'. 104 105 106.. c:function:: void PyErr_SetObject(PyObject *type, PyObject *value) 107 108 This function is similar to :c:func:`PyErr_SetString` but lets you specify an 109 arbitrary Python object for the "value" of the exception. 110 111 112.. c:function:: PyObject* PyErr_Format(PyObject *exception, const char *format, ...) 113 114 This function sets the error indicator and returns ``NULL``. *exception* 115 should be a Python exception class. The *format* and subsequent 116 parameters help format the error message; they have the same meaning and 117 values as in :c:func:`PyUnicode_FromFormat`. *format* is an ASCII-encoded 118 string. 119 120 121.. c:function:: PyObject* PyErr_FormatV(PyObject *exception, const char *format, va_list vargs) 122 123 Same as :c:func:`PyErr_Format`, but taking a :c:type:`va_list` argument rather 124 than a variable number of arguments. 125 126 .. versionadded:: 3.5 127 128 129.. c:function:: void PyErr_SetNone(PyObject *type) 130 131 This is a shorthand for ``PyErr_SetObject(type, Py_None)``. 132 133 134.. c:function:: int PyErr_BadArgument() 135 136 This is a shorthand for ``PyErr_SetString(PyExc_TypeError, message)``, where 137 *message* indicates that a built-in operation was invoked with an illegal 138 argument. It is mostly for internal use. 139 140 141.. c:function:: PyObject* PyErr_NoMemory() 142 143 This is a shorthand for ``PyErr_SetNone(PyExc_MemoryError)``; it returns ``NULL`` 144 so an object allocation function can write ``return PyErr_NoMemory();`` when it 145 runs out of memory. 146 147 148.. c:function:: PyObject* PyErr_SetFromErrno(PyObject *type) 149 150 .. index:: single: strerror() 151 152 This is a convenience function to raise an exception when a C library function 153 has returned an error and set the C variable :c:data:`errno`. It constructs a 154 tuple object whose first item is the integer :c:data:`errno` value and whose 155 second item is the corresponding error message (gotten from :c:func:`strerror`), 156 and then calls ``PyErr_SetObject(type, object)``. On Unix, when the 157 :c:data:`errno` value is :const:`EINTR`, indicating an interrupted system call, 158 this calls :c:func:`PyErr_CheckSignals`, and if that set the error indicator, 159 leaves it set to that. The function always returns ``NULL``, so a wrapper 160 function around a system call can write ``return PyErr_SetFromErrno(type);`` 161 when the system call returns an error. 162 163 164.. c:function:: PyObject* PyErr_SetFromErrnoWithFilenameObject(PyObject *type, PyObject *filenameObject) 165 166 Similar to :c:func:`PyErr_SetFromErrno`, with the additional behavior that if 167 *filenameObject* is not ``NULL``, it is passed to the constructor of *type* as 168 a third parameter. In the case of :exc:`OSError` exception, 169 this is used to define the :attr:`filename` attribute of the 170 exception instance. 171 172 173.. c:function:: PyObject* PyErr_SetFromErrnoWithFilenameObjects(PyObject *type, PyObject *filenameObject, PyObject *filenameObject2) 174 175 Similar to :c:func:`PyErr_SetFromErrnoWithFilenameObject`, but takes a second 176 filename object, for raising errors when a function that takes two filenames 177 fails. 178 179 .. versionadded:: 3.4 180 181 182.. c:function:: PyObject* PyErr_SetFromErrnoWithFilename(PyObject *type, const char *filename) 183 184 Similar to :c:func:`PyErr_SetFromErrnoWithFilenameObject`, but the filename 185 is given as a C string. *filename* is decoded from the filesystem encoding 186 (:func:`os.fsdecode`). 187 188 189.. c:function:: PyObject* PyErr_SetFromWindowsErr(int ierr) 190 191 This is a convenience function to raise :exc:`WindowsError`. If called with 192 *ierr* of :c:data:`0`, the error code returned by a call to :c:func:`GetLastError` 193 is used instead. It calls the Win32 function :c:func:`FormatMessage` to retrieve 194 the Windows description of error code given by *ierr* or :c:func:`GetLastError`, 195 then it constructs a tuple object whose first item is the *ierr* value and whose 196 second item is the corresponding error message (gotten from 197 :c:func:`FormatMessage`), and then calls ``PyErr_SetObject(PyExc_WindowsError, 198 object)``. This function always returns ``NULL``. 199 200 .. availability:: Windows. 201 202 203.. c:function:: PyObject* PyErr_SetExcFromWindowsErr(PyObject *type, int ierr) 204 205 Similar to :c:func:`PyErr_SetFromWindowsErr`, with an additional parameter 206 specifying the exception type to be raised. 207 208 .. availability:: Windows. 209 210 211.. c:function:: PyObject* PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename) 212 213 Similar to :c:func:`PyErr_SetFromWindowsErrWithFilenameObject`, but the 214 filename is given as a C string. *filename* is decoded from the filesystem 215 encoding (:func:`os.fsdecode`). 216 217 .. availability:: Windows. 218 219 220.. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilenameObject(PyObject *type, int ierr, PyObject *filename) 221 222 Similar to :c:func:`PyErr_SetFromWindowsErrWithFilenameObject`, with an 223 additional parameter specifying the exception type to be raised. 224 225 .. availability:: Windows. 226 227 228.. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilenameObjects(PyObject *type, int ierr, PyObject *filename, PyObject *filename2) 229 230 Similar to :c:func:`PyErr_SetExcFromWindowsErrWithFilenameObject`, 231 but accepts a second filename object. 232 233 .. availability:: Windows. 234 235 .. versionadded:: 3.4 236 237 238.. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, const char *filename) 239 240 Similar to :c:func:`PyErr_SetFromWindowsErrWithFilename`, with an additional 241 parameter specifying the exception type to be raised. 242 243 .. availability:: Windows. 244 245 246.. c:function:: PyObject* PyErr_SetImportError(PyObject *msg, PyObject *name, PyObject *path) 247 248 This is a convenience function to raise :exc:`ImportError`. *msg* will be 249 set as the exception's message string. *name* and *path*, both of which can 250 be ``NULL``, will be set as the :exc:`ImportError`'s respective ``name`` 251 and ``path`` attributes. 252 253 .. versionadded:: 3.3 254 255 256.. c:function:: void PyErr_SyntaxLocationObject(PyObject *filename, int lineno, int col_offset) 257 258 Set file, line, and offset information for the current exception. If the 259 current exception is not a :exc:`SyntaxError`, then it sets additional 260 attributes, which make the exception printing subsystem think the exception 261 is a :exc:`SyntaxError`. 262 263 .. versionadded:: 3.4 264 265 266.. c:function:: void PyErr_SyntaxLocationEx(const char *filename, int lineno, int col_offset) 267 268 Like :c:func:`PyErr_SyntaxLocationObject`, but *filename* is a byte string 269 decoded from the filesystem encoding (:func:`os.fsdecode`). 270 271 .. versionadded:: 3.2 272 273 274.. c:function:: void PyErr_SyntaxLocation(const char *filename, int lineno) 275 276 Like :c:func:`PyErr_SyntaxLocationEx`, but the col_offset parameter is 277 omitted. 278 279 280.. c:function:: void PyErr_BadInternalCall() 281 282 This is a shorthand for ``PyErr_SetString(PyExc_SystemError, message)``, 283 where *message* indicates that an internal operation (e.g. a Python/C API 284 function) was invoked with an illegal argument. It is mostly for internal 285 use. 286 287 288Issuing warnings 289================ 290 291Use these functions to issue warnings from C code. They mirror similar 292functions exported by the Python :mod:`warnings` module. They normally 293print a warning message to *sys.stderr*; however, it is 294also possible that the user has specified that warnings are to be turned into 295errors, and in that case they will raise an exception. It is also possible that 296the functions raise an exception because of a problem with the warning machinery. 297The return value is ``0`` if no exception is raised, or ``-1`` if an exception 298is raised. (It is not possible to determine whether a warning message is 299actually printed, nor what the reason is for the exception; this is 300intentional.) If an exception is raised, the caller should do its normal 301exception handling (for example, :c:func:`Py_DECREF` owned references and return 302an error value). 303 304.. c:function:: int PyErr_WarnEx(PyObject *category, const char *message, Py_ssize_t stack_level) 305 306 Issue a warning message. The *category* argument is a warning category (see 307 below) or ``NULL``; the *message* argument is a UTF-8 encoded string. *stack_level* is a 308 positive number giving a number of stack frames; the warning will be issued from 309 the currently executing line of code in that stack frame. A *stack_level* of 1 310 is the function calling :c:func:`PyErr_WarnEx`, 2 is the function above that, 311 and so forth. 312 313 Warning categories must be subclasses of :c:data:`PyExc_Warning`; 314 :c:data:`PyExc_Warning` is a subclass of :c:data:`PyExc_Exception`; 315 the default warning category is :c:data:`PyExc_RuntimeWarning`. The standard 316 Python warning categories are available as global variables whose names are 317 enumerated at :ref:`standardwarningcategories`. 318 319 For information about warning control, see the documentation for the 320 :mod:`warnings` module and the :option:`-W` option in the command line 321 documentation. There is no C API for warning control. 322 323.. c:function:: PyObject* PyErr_SetImportErrorSubclass(PyObject *exception, PyObject *msg, PyObject *name, PyObject *path) 324 325 Much like :c:func:`PyErr_SetImportError` but this function allows for 326 specifying a subclass of :exc:`ImportError` to raise. 327 328 .. versionadded:: 3.6 329 330 331.. c:function:: int PyErr_WarnExplicitObject(PyObject *category, PyObject *message, PyObject *filename, int lineno, PyObject *module, PyObject *registry) 332 333 Issue a warning message with explicit control over all warning attributes. This 334 is a straightforward wrapper around the Python function 335 :func:`warnings.warn_explicit`, see there for more information. The *module* 336 and *registry* arguments may be set to ``NULL`` to get the default effect 337 described there. 338 339 .. versionadded:: 3.4 340 341 342.. c:function:: int PyErr_WarnExplicit(PyObject *category, const char *message, const char *filename, int lineno, const char *module, PyObject *registry) 343 344 Similar to :c:func:`PyErr_WarnExplicitObject` except that *message* and 345 *module* are UTF-8 encoded strings, and *filename* is decoded from the 346 filesystem encoding (:func:`os.fsdecode`). 347 348 349.. c:function:: int PyErr_WarnFormat(PyObject *category, Py_ssize_t stack_level, const char *format, ...) 350 351 Function similar to :c:func:`PyErr_WarnEx`, but use 352 :c:func:`PyUnicode_FromFormat` to format the warning message. *format* is 353 an ASCII-encoded string. 354 355 .. versionadded:: 3.2 356 357 358.. c:function:: int PyErr_ResourceWarning(PyObject *source, Py_ssize_t stack_level, const char *format, ...) 359 360 Function similar to :c:func:`PyErr_WarnFormat`, but *category* is 361 :exc:`ResourceWarning` and it passes *source* to :func:`warnings.WarningMessage`. 362 363 .. versionadded:: 3.6 364 365 366Querying the error indicator 367============================ 368 369.. c:function:: PyObject* PyErr_Occurred() 370 371 Test whether the error indicator is set. If set, return the exception *type* 372 (the first argument to the last call to one of the :c:func:`PyErr_Set\*` 373 functions or to :c:func:`PyErr_Restore`). If not set, return ``NULL``. You do not 374 own a reference to the return value, so you do not need to :c:func:`Py_DECREF` 375 it. 376 377 The caller must hold the GIL. 378 379 .. note:: 380 381 Do not compare the return value to a specific exception; use 382 :c:func:`PyErr_ExceptionMatches` instead, shown below. (The comparison could 383 easily fail since the exception may be an instance instead of a class, in the 384 case of a class exception, or it may be a subclass of the expected exception.) 385 386 387.. c:function:: int PyErr_ExceptionMatches(PyObject *exc) 388 389 Equivalent to ``PyErr_GivenExceptionMatches(PyErr_Occurred(), exc)``. This 390 should only be called when an exception is actually set; a memory access 391 violation will occur if no exception has been raised. 392 393 394.. c:function:: int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc) 395 396 Return true if the *given* exception matches the exception type in *exc*. If 397 *exc* is a class object, this also returns true when *given* is an instance 398 of a subclass. If *exc* is a tuple, all exception types in the tuple (and 399 recursively in subtuples) are searched for a match. 400 401 402.. c:function:: void PyErr_Fetch(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback) 403 404 Retrieve the error indicator into three variables whose addresses are passed. 405 If the error indicator is not set, set all three variables to ``NULL``. If it is 406 set, it will be cleared and you own a reference to each object retrieved. The 407 value and traceback object may be ``NULL`` even when the type object is not. 408 409 .. note:: 410 411 This function is normally only used by code that needs to catch exceptions or 412 by code that needs to save and restore the error indicator temporarily, e.g.:: 413 414 { 415 PyObject *type, *value, *traceback; 416 PyErr_Fetch(&type, &value, &traceback); 417 418 /* ... code that might produce other errors ... */ 419 420 PyErr_Restore(type, value, traceback); 421 } 422 423 424.. c:function:: void PyErr_Restore(PyObject *type, PyObject *value, PyObject *traceback) 425 426 Set the error indicator from the three objects. If the error indicator is 427 already set, it is cleared first. If the objects are ``NULL``, the error 428 indicator is cleared. Do not pass a ``NULL`` type and non-``NULL`` value or 429 traceback. The exception type should be a class. Do not pass an invalid 430 exception type or value. (Violating these rules will cause subtle problems 431 later.) This call takes away a reference to each object: you must own a 432 reference to each object before the call and after the call you no longer own 433 these references. (If you don't understand this, don't use this function. I 434 warned you.) 435 436 .. note:: 437 438 This function is normally only used by code that needs to save and restore the 439 error indicator temporarily. Use :c:func:`PyErr_Fetch` to save the current 440 error indicator. 441 442 443.. c:function:: void PyErr_NormalizeException(PyObject**exc, PyObject**val, PyObject**tb) 444 445 Under certain circumstances, the values returned by :c:func:`PyErr_Fetch` below 446 can be "unnormalized", meaning that ``*exc`` is a class object but ``*val`` is 447 not an instance of the same class. This function can be used to instantiate 448 the class in that case. If the values are already normalized, nothing happens. 449 The delayed normalization is implemented to improve performance. 450 451 .. note:: 452 453 This function *does not* implicitly set the ``__traceback__`` 454 attribute on the exception value. If setting the traceback 455 appropriately is desired, the following additional snippet is needed:: 456 457 if (tb != NULL) { 458 PyException_SetTraceback(val, tb); 459 } 460 461 462.. c:function:: void PyErr_GetExcInfo(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback) 463 464 Retrieve the exception info, as known from ``sys.exc_info()``. This refers 465 to an exception that was *already caught*, not to an exception that was 466 freshly raised. Returns new references for the three objects, any of which 467 may be ``NULL``. Does not modify the exception info state. 468 469 .. note:: 470 471 This function is not normally used by code that wants to handle exceptions. 472 Rather, it can be used when code needs to save and restore the exception 473 state temporarily. Use :c:func:`PyErr_SetExcInfo` to restore or clear the 474 exception state. 475 476 .. versionadded:: 3.3 477 478 479.. c:function:: void PyErr_SetExcInfo(PyObject *type, PyObject *value, PyObject *traceback) 480 481 Set the exception info, as known from ``sys.exc_info()``. This refers 482 to an exception that was *already caught*, not to an exception that was 483 freshly raised. This function steals the references of the arguments. 484 To clear the exception state, pass ``NULL`` for all three arguments. 485 For general rules about the three arguments, see :c:func:`PyErr_Restore`. 486 487 .. note:: 488 489 This function is not normally used by code that wants to handle exceptions. 490 Rather, it can be used when code needs to save and restore the exception 491 state temporarily. Use :c:func:`PyErr_GetExcInfo` to read the exception 492 state. 493 494 .. versionadded:: 3.3 495 496 497Signal Handling 498=============== 499 500 501.. c:function:: int PyErr_CheckSignals() 502 503 .. index:: 504 module: signal 505 single: SIGINT 506 single: KeyboardInterrupt (built-in exception) 507 508 This function interacts with Python's signal handling. It checks whether a 509 signal has been sent to the processes and if so, invokes the corresponding 510 signal handler. If the :mod:`signal` module is supported, this can invoke a 511 signal handler written in Python. In all cases, the default effect for 512 :const:`SIGINT` is to raise the :exc:`KeyboardInterrupt` exception. If an 513 exception is raised the error indicator is set and the function returns ``-1``; 514 otherwise the function returns ``0``. The error indicator may or may not be 515 cleared if it was previously set. 516 517 518.. c:function:: void PyErr_SetInterrupt() 519 520 .. index:: 521 single: SIGINT 522 single: KeyboardInterrupt (built-in exception) 523 524 Simulate the effect of a :const:`SIGINT` signal arriving. The next time 525 :c:func:`PyErr_CheckSignals` is called, the Python signal handler for 526 :const:`SIGINT` will be called. 527 528 If :const:`SIGINT` isn't handled by Python (it was set to 529 :data:`signal.SIG_DFL` or :data:`signal.SIG_IGN`), this function does 530 nothing. 531 532.. c:function:: int PySignal_SetWakeupFd(int fd) 533 534 This utility function specifies a file descriptor to which the signal number 535 is written as a single byte whenever a signal is received. *fd* must be 536 non-blocking. It returns the previous such file descriptor. 537 538 The value ``-1`` disables the feature; this is the initial state. 539 This is equivalent to :func:`signal.set_wakeup_fd` in Python, but without any 540 error checking. *fd* should be a valid file descriptor. The function should 541 only be called from the main thread. 542 543 .. versionchanged:: 3.5 544 On Windows, the function now also supports socket handles. 545 546 547Exception Classes 548================= 549 550.. c:function:: PyObject* PyErr_NewException(const char *name, PyObject *base, PyObject *dict) 551 552 This utility function creates and returns a new exception class. The *name* 553 argument must be the name of the new exception, a C string of the form 554 ``module.classname``. The *base* and *dict* arguments are normally ``NULL``. 555 This creates a class object derived from :exc:`Exception` (accessible in C as 556 :c:data:`PyExc_Exception`). 557 558 The :attr:`__module__` attribute of the new class is set to the first part (up 559 to the last dot) of the *name* argument, and the class name is set to the last 560 part (after the last dot). The *base* argument can be used to specify alternate 561 base classes; it can either be only one class or a tuple of classes. The *dict* 562 argument can be used to specify a dictionary of class variables and methods. 563 564 565.. c:function:: PyObject* PyErr_NewExceptionWithDoc(const char *name, const char *doc, PyObject *base, PyObject *dict) 566 567 Same as :c:func:`PyErr_NewException`, except that the new exception class can 568 easily be given a docstring: If *doc* is non-``NULL``, it will be used as the 569 docstring for the exception class. 570 571 .. versionadded:: 3.2 572 573 574Exception Objects 575================= 576 577.. c:function:: PyObject* PyException_GetTraceback(PyObject *ex) 578 579 Return the traceback associated with the exception as a new reference, as 580 accessible from Python through :attr:`__traceback__`. If there is no 581 traceback associated, this returns ``NULL``. 582 583 584.. c:function:: int PyException_SetTraceback(PyObject *ex, PyObject *tb) 585 586 Set the traceback associated with the exception to *tb*. Use ``Py_None`` to 587 clear it. 588 589 590.. c:function:: PyObject* PyException_GetContext(PyObject *ex) 591 592 Return the context (another exception instance during whose handling *ex* was 593 raised) associated with the exception as a new reference, as accessible from 594 Python through :attr:`__context__`. If there is no context associated, this 595 returns ``NULL``. 596 597 598.. c:function:: void PyException_SetContext(PyObject *ex, PyObject *ctx) 599 600 Set the context associated with the exception to *ctx*. Use ``NULL`` to clear 601 it. There is no type check to make sure that *ctx* is an exception instance. 602 This steals a reference to *ctx*. 603 604 605.. c:function:: PyObject* PyException_GetCause(PyObject *ex) 606 607 Return the cause (either an exception instance, or :const:`None`, 608 set by ``raise ... from ...``) associated with the exception as a new 609 reference, as accessible from Python through :attr:`__cause__`. 610 611 612.. c:function:: void PyException_SetCause(PyObject *ex, PyObject *cause) 613 614 Set the cause associated with the exception to *cause*. Use ``NULL`` to clear 615 it. There is no type check to make sure that *cause* is either an exception 616 instance or :const:`None`. This steals a reference to *cause*. 617 618 :attr:`__suppress_context__` is implicitly set to ``True`` by this function. 619 620 621.. _unicodeexceptions: 622 623Unicode Exception Objects 624========================= 625 626The following functions are used to create and modify Unicode exceptions from C. 627 628.. 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) 629 630 Create a :class:`UnicodeDecodeError` object with the attributes *encoding*, 631 *object*, *length*, *start*, *end* and *reason*. *encoding* and *reason* are 632 UTF-8 encoded strings. 633 634.. 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) 635 636 Create a :class:`UnicodeEncodeError` object with the attributes *encoding*, 637 *object*, *length*, *start*, *end* and *reason*. *encoding* and *reason* are 638 UTF-8 encoded strings. 639 640 .. deprecated:: 3.3 3.11 641 642 ``Py_UNICODE`` is deprecated since Python 3.3. Please migrate to 643 ``PyObject_CallFunction(PyExc_UnicodeEncodeError, "sOnns", ...)``. 644 645.. c:function:: PyObject* PyUnicodeTranslateError_Create(const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason) 646 647 Create a :class:`UnicodeTranslateError` object with the attributes *object*, 648 *length*, *start*, *end* and *reason*. *reason* is a UTF-8 encoded string. 649 650 .. deprecated:: 3.3 3.11 651 652 ``Py_UNICODE`` is deprecated since Python 3.3. Please migrate to 653 ``PyObject_CallFunction(PyExc_UnicodeTranslateError, "Onns", ...)``. 654 655.. c:function:: PyObject* PyUnicodeDecodeError_GetEncoding(PyObject *exc) 656 PyObject* PyUnicodeEncodeError_GetEncoding(PyObject *exc) 657 658 Return the *encoding* attribute of the given exception object. 659 660.. c:function:: PyObject* PyUnicodeDecodeError_GetObject(PyObject *exc) 661 PyObject* PyUnicodeEncodeError_GetObject(PyObject *exc) 662 PyObject* PyUnicodeTranslateError_GetObject(PyObject *exc) 663 664 Return the *object* attribute of the given exception object. 665 666.. c:function:: int PyUnicodeDecodeError_GetStart(PyObject *exc, Py_ssize_t *start) 667 int PyUnicodeEncodeError_GetStart(PyObject *exc, Py_ssize_t *start) 668 int PyUnicodeTranslateError_GetStart(PyObject *exc, Py_ssize_t *start) 669 670 Get the *start* attribute of the given exception object and place it into 671 *\*start*. *start* must not be ``NULL``. Return ``0`` on success, ``-1`` on 672 failure. 673 674.. c:function:: int PyUnicodeDecodeError_SetStart(PyObject *exc, Py_ssize_t start) 675 int PyUnicodeEncodeError_SetStart(PyObject *exc, Py_ssize_t start) 676 int PyUnicodeTranslateError_SetStart(PyObject *exc, Py_ssize_t start) 677 678 Set the *start* attribute of the given exception object to *start*. Return 679 ``0`` on success, ``-1`` on failure. 680 681.. c:function:: int PyUnicodeDecodeError_GetEnd(PyObject *exc, Py_ssize_t *end) 682 int PyUnicodeEncodeError_GetEnd(PyObject *exc, Py_ssize_t *end) 683 int PyUnicodeTranslateError_GetEnd(PyObject *exc, Py_ssize_t *end) 684 685 Get the *end* attribute of the given exception object and place it into 686 *\*end*. *end* must not be ``NULL``. Return ``0`` on success, ``-1`` on 687 failure. 688 689.. c:function:: int PyUnicodeDecodeError_SetEnd(PyObject *exc, Py_ssize_t end) 690 int PyUnicodeEncodeError_SetEnd(PyObject *exc, Py_ssize_t end) 691 int PyUnicodeTranslateError_SetEnd(PyObject *exc, Py_ssize_t end) 692 693 Set the *end* attribute of the given exception object to *end*. Return ``0`` 694 on success, ``-1`` on failure. 695 696.. c:function:: PyObject* PyUnicodeDecodeError_GetReason(PyObject *exc) 697 PyObject* PyUnicodeEncodeError_GetReason(PyObject *exc) 698 PyObject* PyUnicodeTranslateError_GetReason(PyObject *exc) 699 700 Return the *reason* attribute of the given exception object. 701 702.. c:function:: int PyUnicodeDecodeError_SetReason(PyObject *exc, const char *reason) 703 int PyUnicodeEncodeError_SetReason(PyObject *exc, const char *reason) 704 int PyUnicodeTranslateError_SetReason(PyObject *exc, const char *reason) 705 706 Set the *reason* attribute of the given exception object to *reason*. Return 707 ``0`` on success, ``-1`` on failure. 708 709 710.. _recursion: 711 712Recursion Control 713================= 714 715These two functions provide a way to perform safe recursive calls at the C 716level, both in the core and in extension modules. They are needed if the 717recursive code does not necessarily invoke Python code (which tracks its 718recursion depth automatically). 719They are also not needed for *tp_call* implementations 720because the :ref:`call protocol <call>` takes care of recursion handling. 721 722.. c:function:: int Py_EnterRecursiveCall(const char *where) 723 724 Marks a point where a recursive C-level call is about to be performed. 725 726 If :const:`USE_STACKCHECK` is defined, this function checks if the OS 727 stack overflowed using :c:func:`PyOS_CheckStack`. In this is the case, it 728 sets a :exc:`MemoryError` and returns a nonzero value. 729 730 The function then checks if the recursion limit is reached. If this is the 731 case, a :exc:`RecursionError` is set and a nonzero value is returned. 732 Otherwise, zero is returned. 733 734 *where* should be a UTF-8 encoded string such as ``" in instance check"`` to 735 be concatenated to the :exc:`RecursionError` message caused by the recursion 736 depth limit. 737 738 .. versionchanged:: 3.9 739 This function is now also available in the limited API. 740 741.. c:function:: void Py_LeaveRecursiveCall(void) 742 743 Ends a :c:func:`Py_EnterRecursiveCall`. Must be called once for each 744 *successful* invocation of :c:func:`Py_EnterRecursiveCall`. 745 746 .. versionchanged:: 3.9 747 This function is now also available in the limited API. 748 749Properly implementing :c:member:`~PyTypeObject.tp_repr` for container types requires 750special recursion handling. In addition to protecting the stack, 751:c:member:`~PyTypeObject.tp_repr` also needs to track objects to prevent cycles. The 752following two functions facilitate this functionality. Effectively, 753these are the C equivalent to :func:`reprlib.recursive_repr`. 754 755.. c:function:: int Py_ReprEnter(PyObject *object) 756 757 Called at the beginning of the :c:member:`~PyTypeObject.tp_repr` implementation to 758 detect cycles. 759 760 If the object has already been processed, the function returns a 761 positive integer. In that case the :c:member:`~PyTypeObject.tp_repr` implementation 762 should return a string object indicating a cycle. As examples, 763 :class:`dict` objects return ``{...}`` and :class:`list` objects 764 return ``[...]``. 765 766 The function will return a negative integer if the recursion limit 767 is reached. In that case the :c:member:`~PyTypeObject.tp_repr` implementation should 768 typically return ``NULL``. 769 770 Otherwise, the function returns zero and the :c:member:`~PyTypeObject.tp_repr` 771 implementation can continue normally. 772 773.. c:function:: void Py_ReprLeave(PyObject *object) 774 775 Ends a :c:func:`Py_ReprEnter`. Must be called once for each 776 invocation of :c:func:`Py_ReprEnter` that returns zero. 777 778 779.. _standardexceptions: 780 781Standard Exceptions 782=================== 783 784All standard Python exceptions are available as global variables whose names are 785``PyExc_`` followed by the Python exception name. These have the type 786:c:type:`PyObject*`; they are all class objects. For completeness, here are all 787the variables: 788 789.. index:: 790 single: PyExc_BaseException 791 single: PyExc_Exception 792 single: PyExc_ArithmeticError 793 single: PyExc_AssertionError 794 single: PyExc_AttributeError 795 single: PyExc_BlockingIOError 796 single: PyExc_BrokenPipeError 797 single: PyExc_BufferError 798 single: PyExc_ChildProcessError 799 single: PyExc_ConnectionAbortedError 800 single: PyExc_ConnectionError 801 single: PyExc_ConnectionRefusedError 802 single: PyExc_ConnectionResetError 803 single: PyExc_EOFError 804 single: PyExc_FileExistsError 805 single: PyExc_FileNotFoundError 806 single: PyExc_FloatingPointError 807 single: PyExc_GeneratorExit 808 single: PyExc_ImportError 809 single: PyExc_IndentationError 810 single: PyExc_IndexError 811 single: PyExc_InterruptedError 812 single: PyExc_IsADirectoryError 813 single: PyExc_KeyError 814 single: PyExc_KeyboardInterrupt 815 single: PyExc_LookupError 816 single: PyExc_MemoryError 817 single: PyExc_ModuleNotFoundError 818 single: PyExc_NameError 819 single: PyExc_NotADirectoryError 820 single: PyExc_NotImplementedError 821 single: PyExc_OSError 822 single: PyExc_OverflowError 823 single: PyExc_PermissionError 824 single: PyExc_ProcessLookupError 825 single: PyExc_RecursionError 826 single: PyExc_ReferenceError 827 single: PyExc_RuntimeError 828 single: PyExc_StopAsyncIteration 829 single: PyExc_StopIteration 830 single: PyExc_SyntaxError 831 single: PyExc_SystemError 832 single: PyExc_SystemExit 833 single: PyExc_TabError 834 single: PyExc_TimeoutError 835 single: PyExc_TypeError 836 single: PyExc_UnboundLocalError 837 single: PyExc_UnicodeDecodeError 838 single: PyExc_UnicodeEncodeError 839 single: PyExc_UnicodeError 840 single: PyExc_UnicodeTranslateError 841 single: PyExc_ValueError 842 single: PyExc_ZeroDivisionError 843 844+-----------------------------------------+---------------------------------+----------+ 845| C Name | Python Name | Notes | 846+=========================================+=================================+==========+ 847| :c:data:`PyExc_BaseException` | :exc:`BaseException` | \(1) | 848+-----------------------------------------+---------------------------------+----------+ 849| :c:data:`PyExc_Exception` | :exc:`Exception` | \(1) | 850+-----------------------------------------+---------------------------------+----------+ 851| :c:data:`PyExc_ArithmeticError` | :exc:`ArithmeticError` | \(1) | 852+-----------------------------------------+---------------------------------+----------+ 853| :c:data:`PyExc_AssertionError` | :exc:`AssertionError` | | 854+-----------------------------------------+---------------------------------+----------+ 855| :c:data:`PyExc_AttributeError` | :exc:`AttributeError` | | 856+-----------------------------------------+---------------------------------+----------+ 857| :c:data:`PyExc_BlockingIOError` | :exc:`BlockingIOError` | | 858+-----------------------------------------+---------------------------------+----------+ 859| :c:data:`PyExc_BrokenPipeError` | :exc:`BrokenPipeError` | | 860+-----------------------------------------+---------------------------------+----------+ 861| :c:data:`PyExc_BufferError` | :exc:`BufferError` | | 862+-----------------------------------------+---------------------------------+----------+ 863| :c:data:`PyExc_ChildProcessError` | :exc:`ChildProcessError` | | 864+-----------------------------------------+---------------------------------+----------+ 865| :c:data:`PyExc_ConnectionAbortedError` | :exc:`ConnectionAbortedError` | | 866+-----------------------------------------+---------------------------------+----------+ 867| :c:data:`PyExc_ConnectionError` | :exc:`ConnectionError` | | 868+-----------------------------------------+---------------------------------+----------+ 869| :c:data:`PyExc_ConnectionRefusedError` | :exc:`ConnectionRefusedError` | | 870+-----------------------------------------+---------------------------------+----------+ 871| :c:data:`PyExc_ConnectionResetError` | :exc:`ConnectionResetError` | | 872+-----------------------------------------+---------------------------------+----------+ 873| :c:data:`PyExc_EOFError` | :exc:`EOFError` | | 874+-----------------------------------------+---------------------------------+----------+ 875| :c:data:`PyExc_FileExistsError` | :exc:`FileExistsError` | | 876+-----------------------------------------+---------------------------------+----------+ 877| :c:data:`PyExc_FileNotFoundError` | :exc:`FileNotFoundError` | | 878+-----------------------------------------+---------------------------------+----------+ 879| :c:data:`PyExc_FloatingPointError` | :exc:`FloatingPointError` | | 880+-----------------------------------------+---------------------------------+----------+ 881| :c:data:`PyExc_GeneratorExit` | :exc:`GeneratorExit` | | 882+-----------------------------------------+---------------------------------+----------+ 883| :c:data:`PyExc_ImportError` | :exc:`ImportError` | | 884+-----------------------------------------+---------------------------------+----------+ 885| :c:data:`PyExc_IndentationError` | :exc:`IndentationError` | | 886+-----------------------------------------+---------------------------------+----------+ 887| :c:data:`PyExc_IndexError` | :exc:`IndexError` | | 888+-----------------------------------------+---------------------------------+----------+ 889| :c:data:`PyExc_InterruptedError` | :exc:`InterruptedError` | | 890+-----------------------------------------+---------------------------------+----------+ 891| :c:data:`PyExc_IsADirectoryError` | :exc:`IsADirectoryError` | | 892+-----------------------------------------+---------------------------------+----------+ 893| :c:data:`PyExc_KeyError` | :exc:`KeyError` | | 894+-----------------------------------------+---------------------------------+----------+ 895| :c:data:`PyExc_KeyboardInterrupt` | :exc:`KeyboardInterrupt` | | 896+-----------------------------------------+---------------------------------+----------+ 897| :c:data:`PyExc_LookupError` | :exc:`LookupError` | \(1) | 898+-----------------------------------------+---------------------------------+----------+ 899| :c:data:`PyExc_MemoryError` | :exc:`MemoryError` | | 900+-----------------------------------------+---------------------------------+----------+ 901| :c:data:`PyExc_ModuleNotFoundError` | :exc:`ModuleNotFoundError` | | 902+-----------------------------------------+---------------------------------+----------+ 903| :c:data:`PyExc_NameError` | :exc:`NameError` | | 904+-----------------------------------------+---------------------------------+----------+ 905| :c:data:`PyExc_NotADirectoryError` | :exc:`NotADirectoryError` | | 906+-----------------------------------------+---------------------------------+----------+ 907| :c:data:`PyExc_NotImplementedError` | :exc:`NotImplementedError` | | 908+-----------------------------------------+---------------------------------+----------+ 909| :c:data:`PyExc_OSError` | :exc:`OSError` | \(1) | 910+-----------------------------------------+---------------------------------+----------+ 911| :c:data:`PyExc_OverflowError` | :exc:`OverflowError` | | 912+-----------------------------------------+---------------------------------+----------+ 913| :c:data:`PyExc_PermissionError` | :exc:`PermissionError` | | 914+-----------------------------------------+---------------------------------+----------+ 915| :c:data:`PyExc_ProcessLookupError` | :exc:`ProcessLookupError` | | 916+-----------------------------------------+---------------------------------+----------+ 917| :c:data:`PyExc_RecursionError` | :exc:`RecursionError` | | 918+-----------------------------------------+---------------------------------+----------+ 919| :c:data:`PyExc_ReferenceError` | :exc:`ReferenceError` | \(2) | 920+-----------------------------------------+---------------------------------+----------+ 921| :c:data:`PyExc_RuntimeError` | :exc:`RuntimeError` | | 922+-----------------------------------------+---------------------------------+----------+ 923| :c:data:`PyExc_StopAsyncIteration` | :exc:`StopAsyncIteration` | | 924+-----------------------------------------+---------------------------------+----------+ 925| :c:data:`PyExc_StopIteration` | :exc:`StopIteration` | | 926+-----------------------------------------+---------------------------------+----------+ 927| :c:data:`PyExc_SyntaxError` | :exc:`SyntaxError` | | 928+-----------------------------------------+---------------------------------+----------+ 929| :c:data:`PyExc_SystemError` | :exc:`SystemError` | | 930+-----------------------------------------+---------------------------------+----------+ 931| :c:data:`PyExc_SystemExit` | :exc:`SystemExit` | | 932+-----------------------------------------+---------------------------------+----------+ 933| :c:data:`PyExc_TabError` | :exc:`TabError` | | 934+-----------------------------------------+---------------------------------+----------+ 935| :c:data:`PyExc_TimeoutError` | :exc:`TimeoutError` | | 936+-----------------------------------------+---------------------------------+----------+ 937| :c:data:`PyExc_TypeError` | :exc:`TypeError` | | 938+-----------------------------------------+---------------------------------+----------+ 939| :c:data:`PyExc_UnboundLocalError` | :exc:`UnboundLocalError` | | 940+-----------------------------------------+---------------------------------+----------+ 941| :c:data:`PyExc_UnicodeDecodeError` | :exc:`UnicodeDecodeError` | | 942+-----------------------------------------+---------------------------------+----------+ 943| :c:data:`PyExc_UnicodeEncodeError` | :exc:`UnicodeEncodeError` | | 944+-----------------------------------------+---------------------------------+----------+ 945| :c:data:`PyExc_UnicodeError` | :exc:`UnicodeError` | | 946+-----------------------------------------+---------------------------------+----------+ 947| :c:data:`PyExc_UnicodeTranslateError` | :exc:`UnicodeTranslateError` | | 948+-----------------------------------------+---------------------------------+----------+ 949| :c:data:`PyExc_ValueError` | :exc:`ValueError` | | 950+-----------------------------------------+---------------------------------+----------+ 951| :c:data:`PyExc_ZeroDivisionError` | :exc:`ZeroDivisionError` | | 952+-----------------------------------------+---------------------------------+----------+ 953 954.. versionadded:: 3.3 955 :c:data:`PyExc_BlockingIOError`, :c:data:`PyExc_BrokenPipeError`, 956 :c:data:`PyExc_ChildProcessError`, :c:data:`PyExc_ConnectionError`, 957 :c:data:`PyExc_ConnectionAbortedError`, :c:data:`PyExc_ConnectionRefusedError`, 958 :c:data:`PyExc_ConnectionResetError`, :c:data:`PyExc_FileExistsError`, 959 :c:data:`PyExc_FileNotFoundError`, :c:data:`PyExc_InterruptedError`, 960 :c:data:`PyExc_IsADirectoryError`, :c:data:`PyExc_NotADirectoryError`, 961 :c:data:`PyExc_PermissionError`, :c:data:`PyExc_ProcessLookupError` 962 and :c:data:`PyExc_TimeoutError` were introduced following :pep:`3151`. 963 964.. versionadded:: 3.5 965 :c:data:`PyExc_StopAsyncIteration` and :c:data:`PyExc_RecursionError`. 966 967.. versionadded:: 3.6 968 :c:data:`PyExc_ModuleNotFoundError`. 969 970These are compatibility aliases to :c:data:`PyExc_OSError`: 971 972.. index:: 973 single: PyExc_EnvironmentError 974 single: PyExc_IOError 975 single: PyExc_WindowsError 976 977+-------------------------------------+----------+ 978| C Name | Notes | 979+=====================================+==========+ 980| :c:data:`PyExc_EnvironmentError` | | 981+-------------------------------------+----------+ 982| :c:data:`PyExc_IOError` | | 983+-------------------------------------+----------+ 984| :c:data:`PyExc_WindowsError` | \(3) | 985+-------------------------------------+----------+ 986 987.. versionchanged:: 3.3 988 These aliases used to be separate exception types. 989 990Notes: 991 992(1) 993 This is a base class for other standard exceptions. 994 995(2) 996 Only defined on Windows; protect code that uses this by testing that the 997 preprocessor macro ``MS_WINDOWS`` is defined. 998 999.. _standardwarningcategories: 1000 1001Standard Warning Categories 1002=========================== 1003 1004All standard Python warning categories are available as global variables whose 1005names are ``PyExc_`` followed by the Python exception name. These have the type 1006:c:type:`PyObject*`; they are all class objects. For completeness, here are all 1007the variables: 1008 1009.. index:: 1010 single: PyExc_Warning 1011 single: PyExc_BytesWarning 1012 single: PyExc_DeprecationWarning 1013 single: PyExc_FutureWarning 1014 single: PyExc_ImportWarning 1015 single: PyExc_PendingDeprecationWarning 1016 single: PyExc_ResourceWarning 1017 single: PyExc_RuntimeWarning 1018 single: PyExc_SyntaxWarning 1019 single: PyExc_UnicodeWarning 1020 single: PyExc_UserWarning 1021 1022+------------------------------------------+---------------------------------+----------+ 1023| C Name | Python Name | Notes | 1024+==========================================+=================================+==========+ 1025| :c:data:`PyExc_Warning` | :exc:`Warning` | \(1) | 1026+------------------------------------------+---------------------------------+----------+ 1027| :c:data:`PyExc_BytesWarning` | :exc:`BytesWarning` | | 1028+------------------------------------------+---------------------------------+----------+ 1029| :c:data:`PyExc_DeprecationWarning` | :exc:`DeprecationWarning` | | 1030+------------------------------------------+---------------------------------+----------+ 1031| :c:data:`PyExc_FutureWarning` | :exc:`FutureWarning` | | 1032+------------------------------------------+---------------------------------+----------+ 1033| :c:data:`PyExc_ImportWarning` | :exc:`ImportWarning` | | 1034+------------------------------------------+---------------------------------+----------+ 1035| :c:data:`PyExc_PendingDeprecationWarning`| :exc:`PendingDeprecationWarning`| | 1036+------------------------------------------+---------------------------------+----------+ 1037| :c:data:`PyExc_ResourceWarning` | :exc:`ResourceWarning` | | 1038+------------------------------------------+---------------------------------+----------+ 1039| :c:data:`PyExc_RuntimeWarning` | :exc:`RuntimeWarning` | | 1040+------------------------------------------+---------------------------------+----------+ 1041| :c:data:`PyExc_SyntaxWarning` | :exc:`SyntaxWarning` | | 1042+------------------------------------------+---------------------------------+----------+ 1043| :c:data:`PyExc_UnicodeWarning` | :exc:`UnicodeWarning` | | 1044+------------------------------------------+---------------------------------+----------+ 1045| :c:data:`PyExc_UserWarning` | :exc:`UserWarning` | | 1046+------------------------------------------+---------------------------------+----------+ 1047 1048.. versionadded:: 3.2 1049 :c:data:`PyExc_ResourceWarning`. 1050 1051Notes: 1052 1053(1) 1054 This is a base class for other standard warning categories. 1055