It would be nice to have an obvious/simple way to document C exceptions
(especially when using the autoexception feature from Sphinx).

Something along:

PyObject *PyErr_Create(char *name, const char *doc)
    Creates and returns a new exception object.
    This behaves like PyErr_Create2() with base set to NULL.

PyObject *PyErr_Create2(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 Exception
(accessible in C as PyExc_Exception).

for py3k the signatures would be:
PyObject *PyErr_Create(const char *name, const char *doc)
PyObject *PyErr_Create2(const char *name, const char *doc, PyObject *base)

Internally, these functions would pass a dict to PyErr_NewException with
the key '__doc__' set to doc.

If there is support for this, I can provide patches for trunk and py3k.

First attempt at implementing this.
Diff is against trunk.

The same against py3k

Sounds like a useful new API. Two comments:

* The version without *base* is not needed.  Passing an explicit NULL
for *base* is easy enough.
* The name "PyErr_Create" is needlessly different from
"PyErr_NewException".  Something like "PyErr_NewExceptionWithDoc" is better.

Even though I don't fully agree with your comments here is a second
attempt addressing them, against trunk.

For the record, I think that the signature difference is enough to
warrant a name that is a clear cut from PyErr_NewException.
And in the spirit of the Py_InitModule and PyModule_Create families of
function I thought the most common/simple form should stand out from the
more complete one.

But, hey, I'm happy if this gets in (in any form :).

Same as previous against py3k

Is there any chance that this will make it in?

Since it's a new CAPI I think it should probably be discussed briefly on
python-dev.

> Since it's a new CAPI I think it should probably be discussed briefly on
> python-dev.

So do I.

Also, what about tests?

Funnily, I already did ask on python-dev, and only got one (+1) answer
from Brett.  I was going to add it some time when I have more cycles for
Python.

Yes, I'd say that counts as a brief discussion :)

One nitpick: Python/errors.c uses tabs for indentation, your patch
should as well.

patch against trunk:
- fix tabs issue (I hope)
- add test

The same with a simpler test.
I leave it up to you guys to choose which one is the best.

Thanks for the patch! I rewrote the C function a bit to also take a dict
argument, and added a test for that.  Committed in r77088.  Will merge
to py3k.

> Thanks for the patch! I rewrote the C function a bit to also take a dict
> argument, and added a test for that.  Committed in r77088.  Will merge
> to py3k.

Great!
Thanks to all for the help!

lekma, this patch is now listed in the 2.7 "what's new" document as
contributed by "the lekma user", please tell us if you want your name there.

> lekma, this patch is now listed in the 2.7 "what's new" document as
> contributed by "the lekma user", please tell us if you want your name
> there.

Nope, that's ok (it's perfect).