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

antoine.pitrou python-checkins at python.org
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


More information about the Python-checkins mailing list