Index: Python/errors.c =================================================================== --- Python/errors.c (revision 75186) +++ Python/errors.c (working copy) @@ -692,7 +692,31 @@ Py_XDECREF(modulename); return result; } + +/* Create and document an exception */ +PyObject * +PyErr_Create2(const char *name, const char *doc, PyObject *base) +{ + PyObject *dict = NULL; + PyObject *_doc; + if (doc != NULL) { + dict = PyDict_New(); + if (dict == NULL) { + return NULL; + } + _doc = PyUnicode_FromString(doc); + if (_doc == NULL || PyDict_SetItemString(dict, "__doc__", _doc) != 0) { + Py_XDECREF(_doc); + Py_DECREF(dict); + return NULL; + } + Py_DECREF(_doc); + } + + return PyErr_NewException(name, base, dict); +} + /* Call when an exception has occurred but there is no way for Python to handle it. Examples: exception in __del__ or during GC. */ void Index: Include/pyerrors.h =================================================================== --- Include/pyerrors.h (revision 75186) +++ Include/pyerrors.h (working copy) @@ -212,6 +212,9 @@ /* Function to create a new exception */ PyAPI_FUNC(PyObject *) PyErr_NewException(const char *name, PyObject *base, PyObject *dict); +PyAPI_FUNC(PyObject *) PyErr_Create2(const char *name, const char *doc, + PyObject *base); +#define PyErr_Create(name, doc) PyErr_Create2(name, doc, (PyObject *)NULL) PyAPI_FUNC(void) PyErr_WriteUnraisable(PyObject *); /* In sigcheck.c or signalmodule.c */ Index: Doc/c-api/exceptions.rst =================================================================== --- Doc/c-api/exceptions.rst (revision 75186) +++ Doc/c-api/exceptions.rst (working copy) @@ -386,8 +386,28 @@ part (after the last dot). The *base* argument can be used to specify alternate base classes; it can either be only one class or a tuple of classes. The *dict* argument can be used to specify a dictionary of class variables and methods. + + +.. cfunction:: PyObject* PyErr_Create(const char *name, const char *doc) + Creates and returns a new exception object. This behaves like + :cfunc:`PyErr_Create2` with *base* set to *NULL*. + .. versionadded:: 3.2 + + +.. cfunction:: PyObject* PyErr_Create2(const char *name, const char *doc, PyObject *base) + + Creates and returns a new exception object. The *name* argument must be the + name of the new exception, a C string of the form ``module.class``. If *doc* + is non-*NULL*, it will be used to define the docstring for the exception. + If *base* is NULL, it creates a class object derived from :exc:`Exception` + (accessible in C as :cdata:`PyExc_Exception`). See :cfunc:`PyErr_NewException` + for more information. + + .. versionadded:: 3.2 + + .. cfunction:: void PyErr_WriteUnraisable(PyObject *obj) This utility function prints a warning message to ``sys.stderr`` when an Index: Doc/data/refcounts.dat =================================================================== --- Doc/data/refcounts.dat (revision 75186) +++ Doc/data/refcounts.dat (working copy) @@ -263,7 +263,16 @@ PyErr_CheckSignals:int::: PyErr_Clear:void::: + +PyErr_Create:PyObject*::+1: +PyErr_Create:char*:name:: +PyErr_Create:char*:doc:: +PyErr_Create2:PyObject*::+1: +PyErr_Create2:char*:name:: +PyErr_Create2:char*:doc:: +PyErr_Create2:PyObject*:base:0: + PyErr_ExceptionMatches:int::: PyErr_ExceptionMatches:PyObject*:exc:0: