[Python-checkins] cpython: Reorganize C API docs of the exception API

Tue Sep 30 21:56:22 CEST 2014

https://hg.python.org/cpython/rev/0c126a29d1f9
changeset: 92679:0c126a29d1f9
user: Antoine Pitrou <solipsis at pitrou.net>
date: Tue Sep 30 21:56:10 2014 +0200
summary:
 Reorganize C API docs of the exception API
files:
 Doc/c-api/exceptions.rst | 654 ++++++++++++++------------
 1 files changed, 347 insertions(+), 307 deletions(-)

diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst
--- a/Doc/c-api/exceptions.rst
+++ b/Doc/c-api/exceptions.rst
@@ -9,13 +9,19 @@
 
 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 Unix :c:data:`errno` variable:
+exception handling. It works somewhat like the POSIX :c:data:`errno` variable:
 there is a global indicator (per thread) of the last error that occurred. Most
-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).
+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).
 
 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
@@ -27,12 +33,21 @@
 propagated, additional calls into the Python/C API may not behave as intended
 and may fail in mysterious ways.
 
-The error indicator consists of three Python objects corresponding to the result
-of ``sys.exc_info()``. API functions exist to interact with the error indicator
-in various ways. There is a separate error indicator for each thread.
+.. 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).
 
-.. XXX Order of these should be more thoughtful.
- Either alphabetical or some kind of structure.
+
+Printing and clearing
+=====================
+
+
+.. c:function:: void PyErr_Clear()
+
+ Clear the error indicator. If the error indicator is not set, there is no
+ effect.
 
 
 .. c:function:: void PyErr_PrintEx(int set_sys_last_vars)
@@ -51,6 +66,277 @@
 Alias for ``PyErr_PrintEx(1)``.
 
 
+.. c:function:: void PyErr_WriteUnraisable(PyObject *obj)
+
+ 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.
+
+ The function is called with a single argument *obj* that identifies the context
+ in which the unraisable exception occurred. The repr of *obj* will be printed in
+ the warning message.
+
+
+Raising exceptions
+==================
+
+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.
+
+
+.. c:function:: void PyErr_SetString(PyObject *type, const char *message)
+
+ 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``'.
+
+
+.. c:function:: void PyErr_SetObject(PyObject *type, PyObject *value)
+
+ This function is similar to :c:func:`PyErr_SetString` but lets you specify an
+ arbitrary Python object for the "value" of the exception.
+
+
+.. c:function:: PyObject* PyErr_Format(PyObject *exception, const char *format, ...)
+
+ 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 `va_list` argument rather
+ than a variable number of arguments.
+
+ .. versionadded:: 3.5
+
+
+.. c:function:: void PyErr_SetNone(PyObject *type)
+
+ This is a shorthand for ``PyErr_SetObject(type, Py_None)``.
+
+
+.. c:function:: int PyErr_BadArgument()
+
+ This is a shorthand for ``PyErr_SetString(PyExc_TypeError, message)``, where
+ *message* indicates that a built-in operation was invoked with an illegal
+ argument. It is mostly for internal use.
+
+
+.. c:function:: PyObject* PyErr_NoMemory()
+
+ 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.
+
+
+.. c:function:: PyObject* PyErr_SetFromErrno(PyObject *type)
+
+ .. index:: single: strerror()
+
+ This is a convenience function to raise an exception when a C library function
+ has returned an error and set the C variable :c:data:`errno`. It constructs a
+ tuple object whose first item is the integer :c:data:`errno` value and whose
+ second item is the corresponding error message (gotten from :c:func:`strerror`),
+ 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
+ function around a system call can write ``return PyErr_SetFromErrno(type);``
+ when the system call returns an error.
+
+
+.. 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
+ 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`).
+
+
+.. c:function:: PyObject* PyErr_SetFromWindowsErr(int ierr)
+
+ This is a convenience function to raise :exc:`WindowsError`. If called with
+ *ierr* of :c:data:`0`, the error code returned by a call to :c:func:`GetLastError`
+ is used instead. It calls the Win32 function :c:func:`FormatMessage` to retrieve
+ the Windows description of error code given by *ierr* or :c:func:`GetLastError`,
+ 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.
+
+
+.. 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. 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.
+
+
+.. 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.
+
+
+.. 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
+
+
+.. 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`.
+
+ .. versionadded:: 3.4
+
+
+.. c:function:: void PyErr_SyntaxLocationEx(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(char *filename, int lineno)
+
+ Like :c:func:`PyErr_SyntaxLocationEx`, but the col_offset parameter is
+ omitted.
+
+
+.. c:function:: void PyErr_BadInternalCall()
+
+ This is a shorthand for ``PyErr_SetString(PyExc_SystemError, message)``,
+ where *message* indicates that an internal operation (e.g. a Python/C API
+ function) was invoked with an illegal argument. It is mostly for internal
+ 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, char *message, int stack_level)
+
+ Issue a warning message. The *category* argument is a warning category (see
+ below) or *NULL*; the *message* argument is an UTF-8 encoded string. *stack_level* 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
+ is the function calling :c:func:`PyErr_WarnEx`, 2 is the function above that,
+ and so forth.
+
+ Warning categories must be subclasses of :c:data:`Warning`; the default warning
+ category is :c:data:`RuntimeWarning`. The standard Python warning categories are
+ available as global variables whose names are ``PyExc_`` followed by the Python
+ exception name. These have the type :c:type:`PyObject\*`; they are all class
+ objects. Their names are :c:data:`PyExc_Warning`, :c:data:`PyExc_UserWarning`,
+ :c:data:`PyExc_UnicodeWarning`, :c:data:`PyExc_DeprecationWarning`,
+ :c:data:`PyExc_SyntaxWarning`, :c:data:`PyExc_RuntimeWarning`, and
+ :c:data:`PyExc_FutureWarning`. :c:data:`PyExc_Warning` is a subclass of
+ :c:data:`PyExc_Exception`; the other warning categories are subclasses of
+ :c:data:`PyExc_Warning`.
+
+ For information about warning control, see the documentation for the
+ :mod:`warnings` module and the :option:`-W` option in the command line
+ documentation. There is no C API for warning control.
+
+
+.. c:function:: int PyErr_WarnExplicitObject(PyObject *category, PyObject *message, PyObject *filename, int lineno, PyObject *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
+ 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
+
+
+Querying the error indicator
+============================
+
 .. c:function:: PyObject* PyErr_Occurred()
 
 Test whether the error indicator is set. If set, return the exception *type*
@@ -76,12 +362,53 @@
 
 .. c:function:: int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc)
 
- Return true if the *given* exception matches the exception in *exc*. If
+ 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 exceptions in the tuple (and
+ 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
@@ -101,48 +428,10 @@
 }
 
 
-.. 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_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
+ 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.
 
@@ -159,7 +448,7 @@
 .. 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
+ 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`.
@@ -174,248 +463,8 @@
 .. versionadded:: 3.3
 
 
-.. c:function:: void PyErr_SetString(PyObject *type, const char *message)
-
- 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``'.
-
-
-.. c:function:: void PyErr_SetObject(PyObject *type, PyObject *value)
-
- This function is similar to :c:func:`PyErr_SetString` but lets you specify an
- arbitrary Python object for the "value" of the exception.
-
-
-.. c:function:: PyObject* PyErr_Format(PyObject *exception, const char *format, ...)
-
- 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 `va_list` argument rather
- than a variable number of arguments.
-
- .. versionadded:: 3.5
-
-
-.. c:function:: void PyErr_SetNone(PyObject *type)
-
- This is a shorthand for ``PyErr_SetObject(type, Py_None)``.
-
-
-.. c:function:: int PyErr_BadArgument()
-
- This is a shorthand for ``PyErr_SetString(PyExc_TypeError, message)``, where
- *message* indicates that a built-in operation was invoked with an illegal
- argument. It is mostly for internal use.
-
-
-.. c:function:: PyObject* PyErr_NoMemory()
-
- 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.
-
-
-.. c:function:: PyObject* PyErr_SetFromErrno(PyObject *type)
-
- .. index:: single: strerror()
-
- This is a convenience function to raise an exception when a C library function
- has returned an error and set the C variable :c:data:`errno`. It constructs a
- tuple object whose first item is the integer :c:data:`errno` value and whose
- second item is the corresponding error message (gotten from :c:func:`strerror`),
- 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
- function around a system call can write ``return PyErr_SetFromErrno(type);``
- when the system call returns an error.
-
-
-.. 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
- 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`).
-
-
-.. c:function:: PyObject* PyErr_SetFromWindowsErr(int ierr)
-
- This is a convenience function to raise :exc:`WindowsError`. If called with
- *ierr* of :c:data:`0`, the error code returned by a call to :c:func:`GetLastError`
- is used instead. It calls the Win32 function :c:func:`FormatMessage` to retrieve
- the Windows description of error code given by *ierr* or :c:func:`GetLastError`,
- 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.
-
-
-.. 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. 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.
-
-
-.. 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.
-
-
-.. 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
-
-
-.. 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`.
-
- .. versionadded:: 3.4
-
-
-.. c:function:: void PyErr_SyntaxLocationEx(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(char *filename, int lineno)
-
- Like :c:func:`PyErr_SyntaxLocationEx`, but the col_offset parameter is
- omitted.
-
-
-.. c:function:: void PyErr_BadInternalCall()
-
- This is a shorthand for ``PyErr_SetString(PyExc_SystemError, message)``,
- where *message* indicates that an internal operation (e.g. a Python/C API
- function) was invoked with an illegal argument. It is mostly for internal
- use.
-
-
-.. c:function:: int PyErr_WarnEx(PyObject *category, char *message, int stack_level)
-
- Issue a warning message. The *category* argument is a warning category (see
- below) or *NULL*; the *message* argument is an UTF-8 encoded string. *stack_level* 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
- 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:`Warning`; the default warning
- category is :c:data:`RuntimeWarning`. The standard Python warning categories are
- available as global variables whose names are ``PyExc_`` followed by the Python
- exception name. These have the type :c:type:`PyObject\*`; they are all class
- objects. Their names are :c:data:`PyExc_Warning`, :c:data:`PyExc_UserWarning`,
- :c:data:`PyExc_UnicodeWarning`, :c:data:`PyExc_DeprecationWarning`,
- :c:data:`PyExc_SyntaxWarning`, :c:data:`PyExc_RuntimeWarning`, and
- :c:data:`PyExc_FutureWarning`. :c:data:`PyExc_Warning` is a subclass of
- :c:data:`PyExc_Exception`; the other warning categories are subclasses of
- :c:data:`PyExc_Warning`.
-
- For information about warning control, see the documentation for the
- :mod:`warnings` module and the :option:`-W` option in the command line
- documentation. There is no C API for warning control.
-
-
-.. c:function:: int PyErr_WarnExplicitObject(PyObject *category, PyObject *message, PyObject *filename, int lineno, PyObject *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
- 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
+Signal Handling
+===============
 
 
 .. c:function:: int PyErr_CheckSignals()
@@ -464,6 +513,9 @@
 On Windows, the function now also supports socket handles.
 
 
+Exception Classes
+=================
+
 .. c:function:: PyObject* PyErr_NewException(char *name, PyObject *base, PyObject *dict)
 
 This utility function creates and returns a new exception class. The *name*
@@ -488,18 +540,6 @@
 .. versionadded:: 3.2
 
 
-.. c:function:: void PyErr_WriteUnraisable(PyObject *obj)
-
- 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.
-
- The function is called with a single argument *obj* that identifies the context
- in which the unraisable exception occurred. The repr of *obj* will be printed in
- the warning message.
-
-
 Exception Objects
 =================
 
-- 
Repository URL: https://hg.python.org/cpython
