diff options
Diffstat (limited to 'Doc/c-api/exceptions.rst')
| -rw-r--r-- | Doc/c-api/exceptions.rst | 753 |
1 files changed, 217 insertions, 536 deletions
diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst index 2edcbf7..281e4c8 100644 --- a/Doc/c-api/exceptions.rst +++ b/Doc/c-api/exceptions.rst @@ -1,4 +1,4 @@ -.. highlight:: c +.. highlightlang:: c .. _exceptionhandling: @@ -9,19 +9,13 @@ Exception Handling The functions described in this chapter will let you handle and raise Python exceptions. It is important to understand some of the basics of Python -exception handling. It works somewhat like the POSIX :c:data:`errno` variable: +exception handling. It works somewhat like the Unix :c:data:`errno` variable: there is a global indicator (per thread) of the last error that occurred. Most -C API functions don't clear this on success, but will set it to indicate the -cause of the error on failure. Most C API functions also return an error -indicator, usually ``NULL`` if they are supposed to return a pointer, or ``-1`` -if they return an integer (exception: the :c:func:`PyArg_\*` functions -return ``1`` for success and ``0`` for failure). - -Concretely, the error indicator consists of three object pointers: the -exception's type, the exception's value, and the traceback object. Any -of those pointers can be ``NULL`` if non-set (although some combinations are -forbidden, for example you can't have a non-``NULL`` traceback if the exception -type is ``NULL``). +functions don't clear this on success, but will set it to indicate the cause of +the error on failure. Most functions also return an error indicator, usually +*NULL* if they are supposed to return a pointer, or ``-1`` if they return an +integer (exception: the :c:func:`PyArg_\*` functions return ``1`` for success and +``0`` for failure). When a function must fail because some function it called failed, it generally doesn't set the error indicator; the function it called already set it. It is @@ -33,28 +27,25 @@ the caller that an error has been set. If the error is not handled or carefully propagated, additional calls into the Python/C API may not behave as intended and may fail in mysterious ways. -.. note:: - The error indicator is **not** the result of :func:`sys.exc_info()`. - The former corresponds to an exception that is not yet caught (and is - therefore still propagating), while the latter returns an exception after - it is caught (and has therefore stopped propagating). - - -Printing and clearing -===================== - +.. index:: + single: exc_type (in module sys) + single: exc_value (in module sys) + single: exc_traceback (in module sys) -.. c:function:: void PyErr_Clear() +The error indicator consists of three Python objects corresponding to the +Python variables ``sys.exc_type``, ``sys.exc_value`` and ``sys.exc_traceback``. +API functions exist to interact with the error indicator in various ways. There +is a separate error indicator for each thread. - Clear the error indicator. If the error indicator is not set, there is no - effect. +.. XXX Order of these should be more thoughtful. + Either alphabetical or some kind of structure. .. c:function:: void PyErr_PrintEx(int set_sys_last_vars) Print a standard traceback to ``sys.stderr`` and clear the error indicator. - **Unless** the error is a ``SystemExit``, in that case no traceback is - printed and the Python process will exit with the error code specified by + **Unless** the error is a ``SystemExit``. In that case the no traceback + is printed and Python process will exit with the error code specified by the ``SystemExit`` instance. Call this function **only** when the error indicator is set. Otherwise it @@ -70,29 +61,82 @@ Printing and clearing Alias for ``PyErr_PrintEx(1)``. -.. c:function:: void PyErr_WriteUnraisable(PyObject *obj) +.. c:function:: PyObject* PyErr_Occurred() - Call :func:`sys.unraisablehook` using the current exception and *obj* - argument. + Test whether the error indicator is set. If set, return the exception *type* + (the first argument to the last call to one of the :c:func:`PyErr_Set\*` + functions or to :c:func:`PyErr_Restore`). If not set, return *NULL*. You do not + own a reference to the return value, so you do not need to :c:func:`Py_DECREF` + it. - This utility function prints a warning message to ``sys.stderr`` when an - exception has been set but it is impossible for the interpreter to actually - raise the exception. It is used, for example, when an exception occurs in an - :meth:`__del__` method. + .. note:: - The function is called with a single argument *obj* that identifies the context - in which the unraisable exception occurred. If possible, - the repr of *obj* will be printed in the warning message. + Do not compare the return value to a specific exception; use + :c:func:`PyErr_ExceptionMatches` instead, shown below. (The comparison could + easily fail since the exception may be an instance instead of a class, in the + case of a class exception, or it may be a subclass of the expected exception.) + + +.. c:function:: int PyErr_ExceptionMatches(PyObject *exc) - An exception must be set when calling this function. + Equivalent to ``PyErr_GivenExceptionMatches(PyErr_Occurred(), exc)``. This + should only be called when an exception is actually set; a memory access + violation will occur if no exception has been raised. -Raising exceptions -================== +.. c:function:: int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc) -These functions help you set the current thread's error indicator. -For convenience, some of these functions will always return a -``NULL`` pointer for use in a ``return`` statement. + Return true if the *given* exception matches the exception in *exc*. If + *exc* is a class object, this also returns true when *given* is an instance + of a subclass. If *exc* is a tuple, all exceptions in the tuple (and + recursively in subtuples) are searched for a match. + + +.. c:function:: void PyErr_NormalizeException(PyObject**exc, PyObject**val, PyObject**tb) + + Under certain circumstances, the values returned by :c:func:`PyErr_Fetch` below + can be "unnormalized", meaning that ``*exc`` is a class object but ``*val`` is + not an instance of the same class. This function can be used to instantiate + the class in that case. If the values are already normalized, nothing happens. + The delayed normalization is implemented to improve performance. + + +.. c:function:: void PyErr_Clear() + + Clear the error indicator. If the error indicator is not set, there is no + effect. + + +.. c:function:: void PyErr_Fetch(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback) + + Retrieve the error indicator into three variables whose addresses are passed. + If the error indicator is not set, set all three variables to *NULL*. If it is + set, it will be cleared and you own a reference to each object retrieved. The + value and traceback object may be *NULL* even when the type object is not. + + .. note:: + + This function is normally only used by code that needs to handle exceptions or + by code that needs to save and restore the error indicator temporarily. + + +.. c:function:: void PyErr_Restore(PyObject *type, PyObject *value, PyObject *traceback) + + Set the error indicator from the three objects. If the error indicator is + already set, it is cleared first. If the objects are *NULL*, the error + indicator is cleared. Do not pass a *NULL* type and non-*NULL* value or + traceback. The exception type should be a class. Do not pass an invalid + exception type or value. (Violating these rules will cause subtle problems + later.) This call takes away a reference to each object: you must own a + reference to each object before the call and after the call you no longer own + these references. (If you don't understand this, don't use this function. I + warned you.) + + .. note:: + + This function is normally only used by code that needs to save and restore the + error indicator temporarily; use :c:func:`PyErr_Fetch` to save the current + exception state. .. c:function:: void PyErr_SetString(PyObject *type, const char *message) @@ -100,7 +144,7 @@ For convenience, some of these functions will always return a This is the most common way to set the error indicator. The first argument specifies the exception type; it is normally one of the standard exceptions, e.g. :c:data:`PyExc_RuntimeError`. You need not increment its reference count. - The second argument is an error message; it is decoded from ``'utf-8``'. + The second argument is an error message; it is converted to a string object. .. c:function:: void PyErr_SetObject(PyObject *type, PyObject *value) @@ -111,19 +155,10 @@ For convenience, some of these functions will always return a .. c:function:: PyObject* PyErr_Format(PyObject *exception, const char *format, ...) - This function sets the error indicator and returns ``NULL``. *exception* + This function sets the error indicator and returns *NULL*. *exception* should be a Python exception class. The *format* and subsequent parameters help format the error message; they have the same meaning and - values as in :c:func:`PyUnicode_FromFormat`. *format* is an ASCII-encoded - string. - - -.. c:function:: PyObject* PyErr_FormatV(PyObject *exception, const char *format, va_list vargs) - - Same as :c:func:`PyErr_Format`, but taking a :c:type:`va_list` argument rather - than a variable number of arguments. - - .. versionadded:: 3.5 + values as in :c:func:`PyString_FromFormat`. .. c:function:: void PyErr_SetNone(PyObject *type) @@ -140,7 +175,7 @@ For convenience, some of these functions will always return a .. c:function:: PyObject* PyErr_NoMemory() - This is a shorthand for ``PyErr_SetNone(PyExc_MemoryError)``; it returns ``NULL`` + This is a shorthand for ``PyErr_SetNone(PyExc_MemoryError)``; it returns *NULL* so an object allocation function can write ``return PyErr_NoMemory();`` when it runs out of memory. @@ -156,7 +191,7 @@ For convenience, some of these functions will always return a and then calls ``PyErr_SetObject(type, object)``. On Unix, when the :c:data:`errno` value is :const:`EINTR`, indicating an interrupted system call, this calls :c:func:`PyErr_CheckSignals`, and if that set the error indicator, - leaves it set to that. The function always returns ``NULL``, so a wrapper + leaves it set to that. The function always returns *NULL*, so a wrapper function around a system call can write ``return PyErr_SetFromErrno(type);`` when the system call returns an error. @@ -164,26 +199,16 @@ For convenience, some of these functions will always return a .. c:function:: PyObject* PyErr_SetFromErrnoWithFilenameObject(PyObject *type, PyObject *filenameObject) Similar to :c:func:`PyErr_SetFromErrno`, with the additional behavior that if - *filenameObject* is not ``NULL``, it is passed to the constructor of *type* as - a third parameter. In the case of :exc:`OSError` exception, - this is used to define the :attr:`filename` attribute of the + *filenameObject* is not *NULL*, it is passed to the constructor of *type* as + a third parameter. In the case of exceptions such as :exc:`IOError` and + :exc:`OSError`, this is used to define the :attr:`filename` attribute of the exception instance. -.. c:function:: PyObject* PyErr_SetFromErrnoWithFilenameObjects(PyObject *type, PyObject *filenameObject, PyObject *filenameObject2) - - Similar to :c:func:`PyErr_SetFromErrnoWithFilenameObject`, but takes a second - filename object, for raising errors when a function that takes two filenames - fails. - - .. versionadded:: 3.4 - - .. c:function:: PyObject* PyErr_SetFromErrnoWithFilename(PyObject *type, const char *filename) Similar to :c:func:`PyErr_SetFromErrnoWithFilenameObject`, but the filename - is given as a C string. *filename* is decoded from the filesystem encoding - (:func:`os.fsdecode`). + is given as a C string. .. c:function:: PyObject* PyErr_SetFromWindowsErr(int ierr) @@ -195,86 +220,45 @@ For convenience, some of these functions will always return a then it constructs a tuple object whose first item is the *ierr* value and whose second item is the corresponding error message (gotten from :c:func:`FormatMessage`), and then calls ``PyErr_SetObject(PyExc_WindowsError, - object)``. This function always returns ``NULL``. - - .. availability:: Windows. + object)``. This function always returns *NULL*. Availability: Windows. .. c:function:: PyObject* PyErr_SetExcFromWindowsErr(PyObject *type, int ierr) Similar to :c:func:`PyErr_SetFromWindowsErr`, with an additional parameter - specifying the exception type to be raised. + specifying the exception type to be raised. Availability: Windows. + + .. versionadded:: 2.3 + - .. availability:: Windows. +.. c:function:: PyObject* PyErr_SetFromWindowsErrWithFilenameObject(int ierr, PyObject *filenameObject) + + Similar to :c:func:`PyErr_SetFromWindowsErr`, with the additional behavior that + if *filenameObject* is not *NULL*, it is passed to the constructor of + :exc:`WindowsError` as a third parameter. Availability: Windows. .. c:function:: PyObject* PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename) Similar to :c:func:`PyErr_SetFromWindowsErrWithFilenameObject`, but the - filename is given as a C string. *filename* is decoded from the filesystem - encoding (:func:`os.fsdecode`). - - .. availability:: Windows. + filename is given as a C string. Availability: Windows. .. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilenameObject(PyObject *type, int ierr, PyObject *filename) Similar to :c:func:`PyErr_SetFromWindowsErrWithFilenameObject`, with an additional parameter specifying the exception type to be raised. + Availability: Windows. - .. availability:: Windows. - - -.. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilenameObjects(PyObject *type, int ierr, PyObject *filename, PyObject *filename2) - - Similar to :c:func:`PyErr_SetExcFromWindowsErrWithFilenameObject`, - but accepts a second filename object. - - .. availability:: Windows. - - .. versionadded:: 3.4 + .. versionadded:: 2.3 .. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, const char *filename) Similar to :c:func:`PyErr_SetFromWindowsErrWithFilename`, with an additional - parameter specifying the exception type to be raised. - - .. availability:: Windows. - - -.. c:function:: PyObject* PyErr_SetImportError(PyObject *msg, PyObject *name, PyObject *path) - - This is a convenience function to raise :exc:`ImportError`. *msg* will be - set as the exception's message string. *name* and *path*, both of which can - be ``NULL``, will be set as the :exc:`ImportError`'s respective ``name`` - and ``path`` attributes. - - .. versionadded:: 3.3 - - -.. c:function:: void PyErr_SyntaxLocationObject(PyObject *filename, int lineno, int col_offset) - - Set file, line, and offset information for the current exception. If the - current exception is not a :exc:`SyntaxError`, then it sets additional - attributes, which make the exception printing subsystem think the exception - is a :exc:`SyntaxError`. + parameter specifying the exception type to be raised. Availability: Windows. - .. versionadded:: 3.4 - - -.. c:function:: void PyErr_SyntaxLocationEx(const char *filename, int lineno, int col_offset) - - Like :c:func:`PyErr_SyntaxLocationObject`, but *filename* is a byte string - decoded from the filesystem encoding (:func:`os.fsdecode`). - - .. versionadded:: 3.2 - - -.. c:function:: void PyErr_SyntaxLocation(const char *filename, int lineno) - - Like :c:func:`PyErr_SyntaxLocationEx`, but the col_offset parameter is - omitted. + .. versionadded:: 2.3 .. c:function:: void PyErr_BadInternalCall() @@ -285,31 +269,27 @@ For convenience, some of these functions will always return a use. -Issuing warnings -================ - -Use these functions to issue warnings from C code. They mirror similar -functions exported by the Python :mod:`warnings` module. They normally -print a warning message to *sys.stderr*; however, it is -also possible that the user has specified that warnings are to be turned into -errors, and in that case they will raise an exception. It is also possible that -the functions raise an exception because of a problem with the warning machinery. -The return value is ``0`` if no exception is raised, or ``-1`` if an exception -is raised. (It is not possible to determine whether a warning message is -actually printed, nor what the reason is for the exception; this is -intentional.) If an exception is raised, the caller should do its normal -exception handling (for example, :c:func:`Py_DECREF` owned references and return -an error value). - -.. c:function:: int PyErr_WarnEx(PyObject *category, const char *message, Py_ssize_t stack_level) +.. c:function:: int PyErr_WarnEx(PyObject *category, char *message, int stacklevel) Issue a warning message. The *category* argument is a warning category (see - below) or ``NULL``; the *message* argument is a UTF-8 encoded string. *stack_level* is a + below) or *NULL*; the *message* argument is a message string. *stacklevel* is a positive number giving a number of stack frames; the warning will be issued from - the currently executing line of code in that stack frame. A *stack_level* of 1 + the currently executing line of code in that stack frame. A *stacklevel* of 1 is the function calling :c:func:`PyErr_WarnEx`, 2 is the function above that, and so forth. + This function normally prints a warning message to *sys.stderr*; however, it is + also possible that the user has specified that warnings are to be turned into + errors, and in that case this will raise an exception. It is also possible that + the function raises an exception because of a problem with the warning machinery + (the implementation imports the :mod:`warnings` module to do the heavy lifting). + The return value is ``0`` if no exception is raised, or ``-1`` if an exception + is raised. (It is not possible to determine whether a warning message is + actually printed, nor what the reason is for the exception; this is + intentional.) If an exception is raised, the caller should do its normal + exception handling (for example, :c:func:`Py_DECREF` owned references and return + an error value). + Warning categories must be subclasses of :c:data:`PyExc_Warning`; :c:data:`PyExc_Warning` is a subclass of :c:data:`PyExc_Exception`; the default warning category is :c:data:`PyExc_RuntimeWarning`. The standard @@ -320,182 +300,32 @@ an error value). :mod:`warnings` module and the :option:`-W` option in the command line documentation. There is no C API for warning control. -.. c:function:: PyObject* PyErr_SetImportErrorSubclass(PyObject *exception, PyObject *msg, PyObject *name, PyObject *path) - Much like :c:func:`PyErr_SetImportError` but this function allows for - specifying a subclass of :exc:`ImportError` to raise. +.. c:function:: int PyErr_Warn(PyObject *category, char *message) - .. versionadded:: 3.6 + Issue a warning message. The *category* argument is a warning category (see + below) or *NULL*; the *message* argument is a message string. The warning will + appear to be issued from the function calling :c:func:`PyErr_Warn`, equivalent to + calling :c:func:`PyErr_WarnEx` with a *stacklevel* of 1. + Deprecated; use :c:func:`PyErr_WarnEx` instead. -.. c:function:: int PyErr_WarnExplicitObject(PyObject *category, PyObject *message, PyObject *filename, int lineno, PyObject *module, PyObject *registry) + +.. c:function:: int PyErr_WarnExplicit(PyObject *category, const char *message, const char *filename, int lineno, const char *module, PyObject *registry) Issue a warning message with explicit control over all warning attributes. This is a straightforward wrapper around the Python function :func:`warnings.warn_explicit`, see there for more information. The *module* - and *registry* arguments may be set to ``NULL`` to get the default effect + and *registry* arguments may be set to *NULL* to get the default effect described there. - .. versionadded:: 3.4 - - -.. c:function:: int PyErr_WarnExplicit(PyObject *category, const char *message, const char *filename, int lineno, const char *module, PyObject *registry) - - Similar to :c:func:`PyErr_WarnExplicitObject` except that *message* and - *module* are UTF-8 encoded strings, and *filename* is decoded from the - filesystem encoding (:func:`os.fsdecode`). - - -.. c:function:: int PyErr_WarnFormat(PyObject *category, Py_ssize_t stack_level, const char *format, ...) - - Function similar to :c:func:`PyErr_WarnEx`, but use - :c:func:`PyUnicode_FromFormat` to format the warning message. *format* is - an ASCII-encoded string. - - .. versionadded:: 3.2 - - -.. c:function:: int PyErr_ResourceWarning(PyObject *source, Py_ssize_t stack_level, const char *format, ...) - - Function similar to :c:func:`PyErr_WarnFormat`, but *category* is - :exc:`ResourceWarning` and pass *source* to :func:`warnings.WarningMessage`. - - .. versionadded:: 3.6 - - -Querying the error indicator -============================ -.. c:function:: PyObject* PyErr_Occurred() - - Test whether the error indicator is set. If set, return the exception *type* - (the first argument to the last call to one of the :c:func:`PyErr_Set\*` - functions or to :c:func:`PyErr_Restore`). If not set, return ``NULL``. You do not - own a reference to the return value, so you do not need to :c:func:`Py_DECREF` - it. - - The caller must hold the GIL. - - .. note:: +.. c:function:: int PyErr_WarnPy3k(char *message, int stacklevel) - Do not compare the return value to a specific exception; use - :c:func:`PyErr_ExceptionMatches` instead, shown below. (The comparison could - easily fail since the exception may be an instance instead of a class, in the - case of a class exception, or it may be a subclass of the expected exception.) + Issue a :exc:`DeprecationWarning` with the given *message* and *stacklevel* + if the :c:data:`Py_Py3kWarningFlag` flag is enabled. - -.. c:function:: int PyErr_ExceptionMatches(PyObject *exc) - - Equivalent to ``PyErr_GivenExceptionMatches(PyErr_Occurred(), exc)``. This - should only be called when an exception is actually set; a memory access - violation will occur if no exception has been raised. - - -.. c:function:: int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc) - - Return true if the *given* exception matches the exception type in *exc*. If - *exc* is a class object, this also returns true when *given* is an instance - of a subclass. If *exc* is a tuple, all exception types in the tuple (and - recursively in subtuples) are searched for a match. - - -.. c:function:: void PyErr_Fetch(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback) - - Retrieve the error indicator into three variables whose addresses are passed. - If the error indicator is not set, set all three variables to ``NULL``. If it is - set, it will be cleared and you own a reference to each object retrieved. The - value and traceback object may be ``NULL`` even when the type object is not. - - .. note:: - - This function is normally only used by code that needs to catch exceptions or - by code that needs to save and restore the error indicator temporarily, e.g.:: - - { - PyObject *type, *value, *traceback; - PyErr_Fetch(&type, &value, &traceback); - - /* ... code that might produce other errors ... */ - - PyErr_Restore(type, value, traceback); - } - - -.. c:function:: void PyErr_Restore(PyObject *type, PyObject *value, PyObject *traceback) - - Set the error indicator from the three objects. If the error indicator is - already set, it is cleared first. If the objects are ``NULL``, the error - indicator is cleared. Do not pass a ``NULL`` type and non-``NULL`` value or - traceback. The exception type should be a class. Do not pass an invalid - exception type or value. (Violating these rules will cause subtle problems - later.) This call takes away a reference to each object: you must own a - reference to each object before the call and after the call you no longer own - these references. (If you don't understand this, don't use this function. I - warned you.) - - .. note:: - - This function is normally only used by code that needs to save and restore the - error indicator temporarily. Use :c:func:`PyErr_Fetch` to save the current - error indicator. - - -.. c:function:: void PyErr_NormalizeException(PyObject**exc, PyObject**val, PyObject**tb) - - Under certain circumstances, the values returned by :c:func:`PyErr_Fetch` below - can be "unnormalized", meaning that ``*exc`` is a class object but ``*val`` is - not an instance of the same class. This function can be used to instantiate - the class in that case. If the values are already normalized, nothing happens. - The delayed normalization is implemented to improve performance. - - .. note:: - - This function *does not* implicitly set the ``__traceback__`` - attribute on the exception value. If setting the traceback - appropriately is desired, the following additional snippet is needed:: - - if (tb != NULL) { - PyException_SetTraceback(val, tb); - } - - -.. c:function:: void PyErr_GetExcInfo(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback) - - Retrieve the exception info, as known from ``sys.exc_info()``. This refers - to an exception that was *already caught*, not to an exception that was - freshly raised. Returns new references for the three objects, any of which - may be ``NULL``. Does not modify the exception info state. - - .. note:: - - This function is not normally used by code that wants to handle exceptions. - Rather, it can be used when code needs to save and restore the exception - state temporarily. Use :c:func:`PyErr_SetExcInfo` to restore or clear the - exception state. - - .. versionadded:: 3.3 - - -.. c:function:: void PyErr_SetExcInfo(PyObject *type, PyObject *value, PyObject *traceback) - - Set the exception info, as known from ``sys.exc_info()``. This refers - to an exception that was *already caught*, not to an exception that was - freshly raised. This function steals the references of the arguments. - To clear the exception state, pass ``NULL`` for all three arguments. - For general rules about the three arguments, see :c:func:`PyErr_Restore`. - - .. note:: - - This function is not normally used by code that wants to handle exceptions. - Rather, it can be used when code needs to save and restore the exception - state temporarily. Use :c:func:`PyErr_GetExcInfo` to read the exception - state. - - .. versionadded:: 3.3 - - -Signal Handling -=============== + .. versionadded:: 2.6 .. c:function:: int PyErr_CheckSignals() @@ -521,37 +351,31 @@ Signal Handling single: SIGINT single: KeyboardInterrupt (built-in exception) - Simulate the effect of a :const:`SIGINT` signal arriving. The next time - :c:func:`PyErr_CheckSignals` is called, the Python signal handler for - :const:`SIGINT` will be called. + This function simulates the effect of a :const:`SIGINT` signal arriving --- the + next time :c:func:`PyErr_CheckSignals` is called, :exc:`KeyboardInterrupt` will + be raised. It may be called without holding the interpreter lock. - If :const:`SIGINT` isn't handled by Python (it was set to - :data:`signal.SIG_DFL` or :data:`signal.SIG_IGN`), this function does - nothing. + .. % XXX This was described as obsolete, but is used in + .. % thread.interrupt_main() (used from IDLE), so it's still needed. -.. c:function:: int PySignal_SetWakeupFd(int fd) - This utility function specifies a file descriptor to which the signal number - is written as a single byte whenever a signal is received. *fd* must be - non-blocking. It returns the previous such file descriptor. +.. c:function:: int PySignal_SetWakeupFd(int fd) - The value ``-1`` disables the feature; this is the initial state. + This utility function specifies a file descriptor to which a ``'\0'`` byte will + be written whenever a signal is received. It returns the previous such file + descriptor. The value ``-1`` disables the feature; this is the initial state. This is equivalent to :func:`signal.set_wakeup_fd` in Python, but without any error checking. *fd* should be a valid file descriptor. The function should only be called from the main thread. - .. versionchanged:: 3.5 - On Windows, the function now also supports socket handles. + .. versionadded:: 2.6 -Exception Classes -================= - -.. c:function:: PyObject* PyErr_NewException(const char *name, PyObject *base, PyObject *dict) +.. c:function:: PyObject* PyErr_NewException(char *name, PyObject *base, PyObject *dict) This utility function creates and returns a new exception class. The *name* argument must be the name of the new exception, a C string of the form - ``module.classname``. The *base* and *dict* arguments are normally ``NULL``. + ``module.classname``. The *base* and *dict* arguments are normally *NULL*. This creates a class object derived from :exc:`Exception` (accessible in C as :c:data:`PyExc_Exception`). @@ -562,60 +386,25 @@ Exception Classes argument can be used to specify a dictionary of class variables and methods. -.. c:function:: PyObject* PyErr_NewExceptionWithDoc(const char *name, const char *doc, PyObject *base, PyObject *dict) +.. c:function:: PyObject* PyErr_NewExceptionWithDoc(char *name, char *doc, PyObject *base, PyObject *dict) Same as :c:func:`PyErr_NewException`, except that the new exception class can - easily be given a docstring: If *doc* is non-``NULL``, it will be used as the + easily be given a docstring: If *doc* is non-*NULL*, it will be used as the docstring for the exception class. - .. versionadded:: 3.2 - - -Exception Objects -================= - -.. c:function:: PyObject* PyException_GetTraceback(PyObject *ex) + .. versionadded:: 2.7 - Return the traceback associated with the exception as a new reference, as - accessible from Python through :attr:`__traceback__`. If there is no - traceback associated, this returns ``NULL``. +.. c:function:: void PyErr_WriteUnraisable(PyObject *obj) -.. c:function:: int PyException_SetTraceback(PyObject *ex, PyObject *tb) - - Set the traceback associated with the exception to *tb*. Use ``Py_None`` to - clear it. - - -.. c:function:: PyObject* PyException_GetContext(PyObject *ex) - - Return the context (another exception instance during whose handling *ex* was - raised) associated with the exception as a new reference, as accessible from - Python through :attr:`__context__`. If there is no context associated, this - returns ``NULL``. - - -.. c:function:: void PyException_SetContext(PyObject *ex, PyObject *ctx) - - Set the context associated with the exception to *ctx*. Use ``NULL`` to clear - it. There is no type check to make sure that *ctx* is an exception instance. - This steals a reference to *ctx*. - - -.. c:function:: PyObject* PyException_GetCause(PyObject *ex) - - Return the cause (either an exception instance, or :const:`None`, - set by ``raise ... from ...``) associated with the exception as a new - reference, as accessible from Python through :attr:`__cause__`. - - -.. c:function:: void PyException_SetCause(PyObject *ex, PyObject *cause) - - Set the cause associated with the exception to *cause*. Use ``NULL`` to clear - it. There is no type check to make sure that *cause* is either an exception - instance or :const:`None`. This steals a reference to *cause*. + This utility function prints a warning message to ``sys.stderr`` when an + exception has been set but it is impossible for the interpreter to actually + raise the exception. It is used, for example, when an exception occurs in an + :meth:`__del__` method. - :attr:`__suppress_context__` is implicitly set to ``True`` by this function. + The function is called with a single argument *obj* that identifies the context + in which the unraisable exception occurred. If possible, + the repr of *obj* will be printed in the warning message. .. _unicodeexceptions: @@ -628,77 +417,73 @@ The following functions are used to create and modify Unicode exceptions from C. .. 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) Create a :class:`UnicodeDecodeError` object with the attributes *encoding*, - *object*, *length*, *start*, *end* and *reason*. *encoding* and *reason* are - UTF-8 encoded strings. + *object*, *length*, *start*, *end* and *reason*. .. 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) Create a :class:`UnicodeEncodeError` object with the attributes *encoding*, - *object*, *length*, *start*, *end* and *reason*. *encoding* and *reason* are - UTF-8 encoded strings. + *object*, *length*, *start*, *end* and *reason*. .. c:function:: PyObject* PyUnicodeTranslateError_Create(const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason) Create a :class:`UnicodeTranslateError` object with the attributes *object*, - *length*, *start*, *end* and *reason*. *reason* is a UTF-8 encoded string. + *length*, *start*, *end* and *reason*. .. c:function:: PyObject* PyUnicodeDecodeError_GetEncoding(PyObject *exc) - PyObject* PyUnicodeEncodeError_GetEncoding(PyObject *exc) + PyObject* PyUnicodeEncodeError_GetEncoding(PyObject *exc) Return the *encoding* attribute of the given exception object. .. c:function:: PyObject* PyUnicodeDecodeError_GetObject(PyObject *exc) - PyObject* PyUnicodeEncodeError_GetObject(PyObject *exc) - PyObject* PyUnicodeTranslateError_GetObject(PyObject *exc) + PyObject* PyUnicodeEncodeError_GetObject(PyObject *exc) + PyObject* PyUnicodeTranslateError_GetObject(PyObject *exc) Return the *object* attribute of the given exception object. .. c:function:: int PyUnicodeDecodeError_GetStart(PyObject *exc, Py_ssize_t *start) - int PyUnicodeEncodeError_GetStart(PyObject *exc, Py_ssize_t *start) - int PyUnicodeTranslateError_GetStart(PyObject *exc, Py_ssize_t *start) + int PyUnicodeEncodeError_GetStart(PyObject *exc, Py_ssize_t *start) + int PyUnicodeTranslateError_GetStart(PyObject *exc, Py_ssize_t *start) Get the *start* attribute of the given exception object and place it into - *\*start*. *start* must not be ``NULL``. Return ``0`` on success, ``-1`` on + *\*start*. *start* must not be *NULL*. Return ``0`` on success, ``-1`` on failure. .. c:function:: int PyUnicodeDecodeError_SetStart(PyObject *exc, Py_ssize_t start) - int PyUnicodeEncodeError_SetStart(PyObject *exc, Py_ssize_t start) - int PyUnicodeTranslateError_SetStart(PyObject *exc, Py_ssize_t start) + int PyUnicodeEncodeError_SetStart(PyObject *exc, Py_ssize_t start) + int PyUnicodeTranslateError_SetStart(PyObject *exc, Py_ssize_t start) Set the *start* attribute of the given exception object to *start*. Return ``0`` on success, ``-1`` on failure. .. c:function:: int PyUnicodeDecodeError_GetEnd(PyObject *exc, Py_ssize_t *end) - int PyUnicodeEncodeError_GetEnd(PyObject *exc, Py_ssize_t *end) - int PyUnicodeTranslateError_GetEnd(PyObject *exc, Py_ssize_t *end) + int PyUnicodeEncodeError_GetEnd(PyObject *exc, Py_ssize_t *end) + int PyUnicodeTranslateError_GetEnd(PyObject *exc, Py_ssize_t *end) Get the *end* attribute of the given exception object and place it into - *\*end*. *end* must not be ``NULL``. Return ``0`` on success, ``-1`` on + *\*end*. *end* must not be *NULL*. Return ``0`` on success, ``-1`` on failure. .. c:function:: int PyUnicodeDecodeError_SetEnd(PyObject *exc, Py_ssize_t end) - int PyUnicodeEncodeError_SetEnd(PyObject *exc, Py_ssize_t end) - int PyUnicodeTranslateError_SetEnd(PyObject *exc, Py_ssize_t end) + int PyUnicodeEncodeError_SetEnd(PyObject *exc, Py_ssize_t end) + int PyUnicodeTranslateError_SetEnd(PyObject *exc, Py_ssize_t end) Set the *end* attribute of the given exception object to *end*. Return ``0`` on success, ``-1`` on failure. .. c:function:: PyObject* PyUnicodeDecodeError_GetReason(PyObject *exc) - PyObject* PyUnicodeEncodeError_GetReason(PyObject *exc) - PyObject* PyUnicodeTranslateError_GetReason(PyObject *exc) + PyObject* PyUnicodeEncodeError_GetReason(PyObject *exc) + PyObject* PyUnicodeTranslateError_GetReason(PyObject *exc) Return the *reason* attribute of the given exception object. .. c:function:: int PyUnicodeDecodeError_SetReason(PyObject *exc, const char *reason) - int PyUnicodeEncodeError_SetReason(PyObject *exc, const char *reason) - int PyUnicodeTranslateError_SetReason(PyObject *exc, const char *reason) + int PyUnicodeEncodeError_SetReason(PyObject *exc, const char *reason) + int PyUnicodeTranslateError_SetReason(PyObject *exc, const char *reason) Set the *reason* attribute of the given exception object to *reason*. Return ``0`` on success, ``-1`` on failure. -.. _recursion: - Recursion Control ================= @@ -706,8 +491,6 @@ These two functions provide a way to perform safe recursive calls at the C level, both in the core and in extension modules. They are needed if the recursive code does not necessarily invoke Python code (which tracks its recursion depth automatically). -They are also not needed for *tp_call* implementations -because the :ref:`call protocol <call>` takes care of recursion handling. .. c:function:: int Py_EnterRecursiveCall(const char *where) @@ -718,53 +501,18 @@ because the :ref:`call protocol <call>` takes care of recursion handling. sets a :exc:`MemoryError` and returns a nonzero value. The function then checks if the recursion limit is reached. If this is the - case, a :exc:`RecursionError` is set and a nonzero value is returned. + case, a :exc:`RuntimeError` is set and a nonzero value is returned. Otherwise, zero is returned. - *where* should be a UTF-8 encoded string such as ``" in instance check"`` to - be concatenated to the :exc:`RecursionError` message caused by the recursion - depth limit. - - .. versionchanged:: 3.9 - This function is now also available in the limited API. + *where* should be a string such as ``" in instance check"`` to be + concatenated to the :exc:`RuntimeError` message caused by the recursion depth + limit. -.. c:function:: void Py_LeaveRecursiveCall(void) +.. c:function:: void Py_LeaveRecursiveCall() Ends a :c:func:`Py_EnterRecursiveCall`. Must be called once for each *successful* invocation of :c:func:`Py_EnterRecursiveCall`. - .. versionchanged:: 3.9 - This function is now also available in the limited API. - -Properly implementing :c:member:`~PyTypeObject.tp_repr` for container types requires -special recursion handling. In addition to protecting the stack, -:c:member:`~PyTypeObject.tp_repr` also needs to track objects to prevent cycles. The -following two functions facilitate this functionality. Effectively, -these are the C equivalent to :func:`reprlib.recursive_repr`. - -.. c:function:: int Py_ReprEnter(PyObject *object) - - Called at the beginning of the :c:member:`~PyTypeObject.tp_repr` implementation to - detect cycles. - - If the object has already been processed, the function returns a - positive integer. In that case the :c:member:`~PyTypeObject.tp_repr` implementation - should return a string object indicating a cycle. As examples, - :class:`dict` objects return ``{...}`` and :class:`list` objects - return ``[...]``. - - The function will return a negative integer if the recursion limit - is reached. In that case the :c:member:`~PyTypeObject.tp_repr` implementation should - typically return ``NULL``. - - Otherwise, the function returns zero and the :c:member:`~PyTypeObject.tp_repr` - implementation can continue normally. - -.. c:function:: void Py_ReprLeave(PyObject *object) - - Ends a :c:func:`Py_ReprEnter`. Must be called once for each - invocation of :c:func:`Py_ReprEnter` that returns zero. - .. _standardexceptions: @@ -779,93 +527,66 @@ the variables: .. index:: single: PyExc_BaseException single: PyExc_Exception + single: PyExc_StandardError single: PyExc_ArithmeticError single: PyExc_AssertionError single: PyExc_AttributeError - single: PyExc_BlockingIOError - single: PyExc_BrokenPipeError single: PyExc_BufferError - single: PyExc_ChildProcessError - single: PyExc_ConnectionAbortedError - single: PyExc_ConnectionError - single: PyExc_ConnectionRefusedError - single: PyExc_ConnectionResetError + single: PyExc_EnvironmentError single: PyExc_EOFError - single: PyExc_FileExistsError - single: PyExc_FileNotFoundError single: PyExc_FloatingPointError single: PyExc_GeneratorExit single: PyExc_ImportError single: PyExc_IndentationError single: PyExc_IndexError - single: PyExc_InterruptedError - single: PyExc_IsADirectoryError + single: PyExc_IOError single: PyExc_KeyError single: PyExc_KeyboardInterrupt single: PyExc_LookupError single: PyExc_MemoryError - single: PyExc_ModuleNotFoundError single: PyExc_NameError - single: PyExc_NotADirectoryError single: PyExc_NotImplementedError single: PyExc_OSError single: PyExc_OverflowError - single: PyExc_PermissionError - single: PyExc_ProcessLookupError - single: PyExc_RecursionError single: PyExc_ReferenceError single: PyExc_RuntimeError - single: PyExc_StopAsyncIteration single: PyExc_StopIteration single: PyExc_SyntaxError single: PyExc_SystemError single: PyExc_SystemExit single: PyExc_TabError - single: PyExc_TimeoutError single: PyExc_TypeError single: PyExc_UnboundLocalError single: PyExc_UnicodeDecodeError single: PyExc_UnicodeEncodeError single: PyExc_UnicodeError single: PyExc_UnicodeTranslateError + single: PyExc_VMSError single: PyExc_ValueError + single: PyExc_WindowsError single: PyExc_ZeroDivisionError +-----------------------------------------+---------------------------------+----------+ | C Name | Python Name | Notes | +=========================================+=================================+==========+ -| :c:data:`PyExc_BaseException` | :exc:`BaseException` | \(1) | +| :c:data:`PyExc_BaseException` | :exc:`BaseException` | (1), (4) | +-----------------------------------------+---------------------------------+----------+ | :c:data:`PyExc_Exception` | :exc:`Exception` | \(1) | +-----------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_StandardError` | :exc:`StandardError` | \(1) | ++-----------------------------------------+---------------------------------+----------+ | :c:data:`PyExc_ArithmeticError` | :exc:`ArithmeticError` | \(1) | +-----------------------------------------+---------------------------------+----------+ | :c:data:`PyExc_AssertionError` | :exc:`AssertionError` | | +-----------------------------------------+---------------------------------+----------+ | :c:data:`PyExc_AttributeError` | :exc:`AttributeError` | | +-----------------------------------------+---------------------------------+----------+ -| :c:data:`PyExc_BlockingIOError` | :exc:`BlockingIOError` | | -+-----------------------------------------+---------------------------------+----------+ -| :c:data:`PyExc_BrokenPipeError` | :exc:`BrokenPipeError` | | -+-----------------------------------------+---------------------------------+----------+ | :c:data:`PyExc_BufferError` | :exc:`BufferError` | | +-----------------------------------------+---------------------------------+----------+ -| :c:data:`PyExc_ChildProcessError` | :exc:`ChildProcessError` | | -+-----------------------------------------+---------------------------------+----------+ -| :c:data:`PyExc_ConnectionAbortedError` | :exc:`ConnectionAbortedError` | | -+-----------------------------------------+---------------------------------+----------+ -| :c:data:`PyExc_ConnectionError` | :exc:`ConnectionError` | | -+-----------------------------------------+---------------------------------+----------+ -| :c:data:`PyExc_ConnectionRefusedError` | :exc:`ConnectionRefusedError` | | -+-----------------------------------------+---------------------------------+----------+ -| :c:data:`PyExc_ConnectionResetError` | :exc:`ConnectionResetError` | | +| :c:data:`PyExc_EnvironmentError` | :exc:`EnvironmentError` | \(1) | +-----------------------------------------+---------------------------------+----------+ | :c:data:`PyExc_EOFError` | :exc:`EOFError` | | +-----------------------------------------+---------------------------------+----------+ -| :c:data:`PyExc_FileExistsError` | :exc:`FileExistsError` | | -+-----------------------------------------+---------------------------------+----------+ -| :c:data:`PyExc_FileNotFoundError` | :exc:`FileNotFoundError` | | -+-----------------------------------------+---------------------------------+----------+ | :c:data:`PyExc_FloatingPointError` | :exc:`FloatingPointError` | | +-----------------------------------------+---------------------------------+----------+ | :c:data:`PyExc_GeneratorExit` | :exc:`GeneratorExit` | | @@ -876,9 +597,7 @@ the variables: +-----------------------------------------+---------------------------------+----------+ | :c:data:`PyExc_IndexError` | :exc:`IndexError` | | +-----------------------------------------+---------------------------------+----------+ -| :c:data:`PyExc_InterruptedError` | :exc:`InterruptedError` | | -+-----------------------------------------+---------------------------------+----------+ -| :c:data:`PyExc_IsADirectoryError` | :exc:`IsADirectoryError` | | +| :c:data:`PyExc_IOError` | :exc:`IOError` | | +-----------------------------------------+---------------------------------+----------+ | :c:data:`PyExc_KeyError` | :exc:`KeyError` | | +-----------------------------------------+---------------------------------+----------+ @@ -888,30 +607,18 @@ the variables: +-----------------------------------------+---------------------------------+----------+ | :c:data:`PyExc_MemoryError` | :exc:`MemoryError` | | +-----------------------------------------+---------------------------------+----------+ -| :c:data:`PyExc_ModuleNotFoundError` | :exc:`ModuleNotFoundError` | | -+-----------------------------------------+---------------------------------+----------+ | :c:data:`PyExc_NameError` | :exc:`NameError` | | +-----------------------------------------+---------------------------------+----------+ -| :c:data:`PyExc_NotADirectoryError` | :exc:`NotADirectoryError` | | -+-----------------------------------------+---------------------------------+----------+ | :c:data:`PyExc_NotImplementedError` | :exc:`NotImplementedError` | | +-----------------------------------------+---------------------------------+----------+ -| :c:data:`PyExc_OSError` | :exc:`OSError` | \(1) | +| :c:data:`PyExc_OSError` | :exc:`OSError` | | +-----------------------------------------+---------------------------------+----------+ | :c:data:`PyExc_OverflowError` | :exc:`OverflowError` | | +-----------------------------------------+---------------------------------+----------+ -| :c:data:`PyExc_PermissionError` | :exc:`PermissionError` | | -+-----------------------------------------+---------------------------------+----------+ -| :c:data:`PyExc_ProcessLookupError` | :exc:`ProcessLookupError` | | -+-----------------------------------------+---------------------------------+----------+ -| :c:data:`PyExc_RecursionError` | :exc:`RecursionError` | | -+-----------------------------------------+---------------------------------+----------+ | :c:data:`PyExc_ReferenceError` | :exc:`ReferenceError` | \(2) | +-----------------------------------------+---------------------------------+----------+ | :c:data:`PyExc_RuntimeError` | :exc:`RuntimeError` | | +-----------------------------------------+---------------------------------+----------+ -| :c:data:`PyExc_StopAsyncIteration` | :exc:`StopAsyncIteration` | | -+-----------------------------------------+---------------------------------+----------+ | :c:data:`PyExc_StopIteration` | :exc:`StopIteration` | | +-----------------------------------------+---------------------------------+----------+ | :c:data:`PyExc_SyntaxError` | :exc:`SyntaxError` | | @@ -922,8 +629,6 @@ the variables: +-----------------------------------------+---------------------------------+----------+ | :c:data:`PyExc_TabError` | :exc:`TabError` | | +-----------------------------------------+---------------------------------+----------+ -| :c:data:`PyExc_TimeoutError` | :exc:`TimeoutError` | | -+-----------------------------------------+---------------------------------+----------+ | :c:data:`PyExc_TypeError` | :exc:`TypeError` | | +-----------------------------------------+---------------------------------+----------+ | :c:data:`PyExc_UnboundLocalError` | :exc:`UnboundLocalError` | | @@ -936,47 +641,15 @@ the variables: +-----------------------------------------+---------------------------------+----------+ | :c:data:`PyExc_UnicodeTranslateError` | :exc:`UnicodeTranslateError` | | +-----------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_VMSError` | :exc:`VMSError` | \(5) | ++-----------------------------------------+---------------------------------+----------+ | :c:data:`PyExc_ValueError` | :exc:`ValueError` | | +-----------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_WindowsError` | :exc:`WindowsError` | \(3) | ++-----------------------------------------+---------------------------------+----------+ | :c:data:`PyExc_ZeroDivisionError` | :exc:`ZeroDivisionError` | | +-----------------------------------------+---------------------------------+----------+ -.. versionadded:: 3.3 - :c:data:`PyExc_BlockingIOError`, :c:data:`PyExc_BrokenPipeError`, - :c:data:`PyExc_ChildProcessError`, :c:data:`PyExc_ConnectionError`, - :c:data:`PyExc_ConnectionAbortedError`, :c:data:`PyExc_ConnectionRefusedError`, - :c:data:`PyExc_ConnectionResetError`, :c:data:`PyExc_FileExistsError`, - :c:data:`PyExc_FileNotFoundError`, :c:data:`PyExc_InterruptedError`, - :c:data:`PyExc_IsADirectoryError`, :c:data:`PyExc_NotADirectoryError`, - :c:data:`PyExc_PermissionError`, :c:data:`PyExc_ProcessLookupError` - and :c:data:`PyExc_TimeoutError` were introduced following :pep:`3151`. - -.. versionadded:: 3.5 - :c:data:`PyExc_StopAsyncIteration` and :c:data:`PyExc_RecursionError`. - -.. versionadded:: 3.6 - :c:data:`PyExc_ModuleNotFoundError`. - -These are compatibility aliases to :c:data:`PyExc_OSError`: - -.. index:: - single: PyExc_EnvironmentError - single: PyExc_IOError - single: PyExc_WindowsError - -+-------------------------------------+----------+ -| C Name | Notes | -+=====================================+==========+ -| :c:data:`PyExc_EnvironmentError` | | -+-------------------------------------+----------+ -| :c:data:`PyExc_IOError` | | -+-------------------------------------+----------+ -| :c:data:`PyExc_WindowsError` | \(3) | -+-------------------------------------+----------+ - -.. versionchanged:: 3.3 - These aliases used to be separate exception types. - Notes: (1) @@ -989,6 +662,13 @@ Notes: Only defined on Windows; protect code that uses this by testing that the preprocessor macro ``MS_WINDOWS`` is defined. +(4) + .. versionadded:: 2.5 + +(5) + Only defined on VMS; protect code that uses this by testing that the + preprocessor macro ``__VMS`` is defined. + .. _standardwarningcategories: Standard Warning Categories @@ -1006,7 +686,6 @@ the variables: single: PyExc_FutureWarning single: PyExc_ImportWarning single: PyExc_PendingDeprecationWarning - single: PyExc_ResourceWarning single: PyExc_RuntimeWarning single: PyExc_SyntaxWarning single: PyExc_UnicodeWarning @@ -1027,8 +706,6 @@ the variables: +------------------------------------------+---------------------------------+----------+ | :c:data:`PyExc_PendingDeprecationWarning`| :exc:`PendingDeprecationWarning`| | +------------------------------------------+---------------------------------+----------+ -| :c:data:`PyExc_ResourceWarning` | :exc:`ResourceWarning` | | -+------------------------------------------+---------------------------------+----------+ | :c:data:`PyExc_RuntimeWarning` | :exc:`RuntimeWarning` | | +------------------------------------------+---------------------------------+----------+ | :c:data:`PyExc_SyntaxWarning` | :exc:`SyntaxWarning` | | @@ -1038,10 +715,14 @@ the variables: | :c:data:`PyExc_UserWarning` | :exc:`UserWarning` | | +------------------------------------------+---------------------------------+----------+ -.. versionadded:: 3.2 - :c:data:`PyExc_ResourceWarning`. - Notes: (1) This is a base class for other standard warning categories. + +String Exceptions +================= + +.. versionchanged:: 2.6 + All exceptions to be raised or caught must be derived from :exc:`BaseException`. + Trying to raise a string exception now raises :exc:`TypeError`. |