Index: Python/errors.c =================================================================== --- Python/errors.c (revision 75227) +++ Python/errors.c (working copy) @@ -692,7 +692,31 @@ Py_XDECREF(modulename); return result; } + +/* Create and document an exception */ +PyObject * +PyErr_NewExceptionWithDoc(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 75227) +++ Include/pyerrors.h (working copy) @@ -212,6 +212,8 @@ /* Function to create a new exception */ PyAPI_FUNC(PyObject *) PyErr_NewException(const char *name, PyObject *base, PyObject *dict); +PyAPI_FUNC(PyObject *) PyErr_NewExceptionWithDoc(const char *name, const char *doc, + PyObject *base); PyAPI_FUNC(void) PyErr_WriteUnraisable(PyObject *); /* In sigcheck.c or signalmodule.c */ Index: Doc/c-api/exceptions.rst =================================================================== --- Doc/c-api/exceptions.rst (revision 75227) +++ Doc/c-api/exceptions.rst (working copy) @@ -373,7 +373,7 @@ only be called from the main thread. -.. cfunction:: PyObject* PyErr_NewException(char *name, PyObject *base, PyObject *dict) +.. cfunction:: PyObject* PyErr_NewException(const char *name, PyObject *base, PyObject *dict) This utility function creates and returns a new exception object. The *name* argument must be the name of the new exception, a C string of the form @@ -386,8 +386,20 @@ 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_NewExceptionWithDoc(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 about *name* and *base*. + .. 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 75227) +++ Doc/data/refcounts.dat (working copy) @@ -280,6 +280,11 @@ PyErr_NewException:char*:name:: PyErr_NewException:PyObject*:base:0: PyErr_NewException:PyObject*:dict:0: + +PyErr_NewExceptionWithDoc:PyObject*::+1: +PyErr_NewExceptionWithDoc:char*:name:: +PyErr_NewExceptionWithDoc:char*:doc:: +PyErr_NewExceptionWithDoc:PyObject*:base:0: PyErr_NoMemory:PyObject*::null: