Issuing warnings

Use these functions to issue warnings from C code. They mirror similar functions exported by the Python 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, Py_DECREF() owned references and return an error value).

int PyErr_WarnEx(PyObject category*, const char message, Py_ssize_t stack_level*)

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 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 PyErr_WarnEx(), 2 is the function above that, and so forth.

Warning categories must be subclasses of PyExc_Warning; PyExc_Warning is a subclass of PyExc_Exception; the default warning category is PyExc_RuntimeWarning. The standard Python warning categories are available as global variables whose names are enumerated at 标准警告类别.

For information about warning control, see the documentation for the warnings module and the -W option in the command line documentation. There is no C API for warning control.

PyObject* PyErr_SetImportErrorSubclass(PyObject exception*, PyObject msg, PyObject **name, PyObject *path)

Return value: Always NULL.

Much like PyErr_SetImportError() but this function allows for specifying a subclass of ImportError to raise.

3.6 新版功能.

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 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.

3.4 新版功能.

int PyErr_WarnExplicit(PyObject category*, const char message, const char **filename, int lineno, const char module*, PyObject registry*)

Similar to PyErr_WarnExplicitObject() except that message and module are UTF-8 encoded strings, and filename is decoded from the filesystem encoding (os.fsdecode()).

int PyErr_WarnFormat(PyObject category, Py_ssize_t stack_level*, const char format*, …)

Function similar to PyErr_WarnEx(), but use PyUnicode_FromFormat() to format the warning message. format is an ASCII-encoded string.

3.2 新版功能.

int PyErr_ResourceWarning(PyObject source, Py_ssize_t stack_level*, const char format*, …)

Function similar to PyErr_WarnFormat(), but category is ResourceWarning and it passes source to warnings.WarningMessage().

3.6 新版功能.