This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: C/API - Document exceptions
Type: enhancement Stage: patch review
Components: Interpreter Core Versions: Python 3.2, Python 2.7
process
Status: closed Resolution: accepted
Dependencies: Superseder:
Assigned To: Nosy List: georg.brandl, lekma, pitrou, r.david.murray
Priority: normal Keywords: patch

Created on 2009-10-02 11:14 by lekma, last changed 2022-04-11 14:56 by admin. This issue is now closed.

Files
File name Uploaded Description Edit
issue7033_trunk.diff lekma, 2009-10-02 17:23
issue7033_py3k.diff lekma, 2009-10-02 17:24
issue7033_trunk_2.diff lekma, 2009-10-04 09:34
issue7033_py3k_2.diff lekma, 2009-10-04 09:36
issue7033_trunk_3.diff lekma, 2009-12-21 11:50
issue7033_trunk_3_alt_test.diff lekma, 2009-12-21 11:52
Messages (19)
msg93439 - (view) Author: (lekma) * Date: 2009-10-02 11:14
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.
msg93448 - (view) Author: (lekma) * Date: 2009-10-02 17:23
First attempt at implementing this.
Diff is against trunk.
msg93449 - (view) Author: (lekma) * Date: 2009-10-02 17:24
The same against py3k
msg93484 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2009-10-03 09:30
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.
msg93526 - (view) Author: (lekma) * Date: 2009-10-04 09:34
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 :).
msg93527 - (view) Author: (lekma) * Date: 2009-10-04 09:36
Same as previous against py3k
msg96667 - (view) Author: (lekma) * Date: 2009-12-20 09:21
Is there any chance that this will make it in?
msg96675 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2009-12-20 14:06
Since it's a new CAPI I think it should probably be discussed briefly on
python-dev.
msg96676 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2009-12-20 14:08
> Since it's a new CAPI I think it should probably be discussed briefly on
> python-dev.

So do I.
msg96677 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2009-12-20 14:09
Also, what about tests?
msg96679 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2009-12-20 14:13
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.
msg96680 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2009-12-20 14:14
Yes, I'd say that counts as a brief discussion :)
msg96682 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2009-12-20 14:23
One nitpick: Python/errors.c uses tabs for indentation, your patch
should as well.
msg96740 - (view) Author: (lekma) * Date: 2009-12-21 11:50
patch against trunk:
- fix tabs issue (I hope)
- add test
msg96741 - (view) Author: (lekma) * Date: 2009-12-21 11:52
The same with a simpler test.
I leave it up to you guys to choose which one is the best.
msg96943 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2009-12-28 08:36
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.
msg96946 - (view) Author: (lekma) * Date: 2009-12-28 14:08
> 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!
msg97009 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2009-12-29 21:41
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.
msg97022 - (view) Author: (lekma) * Date: 2009-12-30 07:26
> 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).
History
Date User Action Args
2022-04-11 14:56:53adminsetgithub: 51282
2009-12-30 07:26:45lekmasetmessages: + msg97022
2009-12-29 21:41:26georg.brandlsetmessages: + msg97009
2009-12-28 14:08:01lekmasetmessages: + msg96946
2009-12-28 08:36:09georg.brandlsetstatus: open -> closed
resolution: accepted
messages: + msg96943
2009-12-21 11:52:08lekmasetfiles: + issue7033_trunk_3_alt_test.diff

messages: + msg96741
2009-12-21 11:50:21lekmasetfiles: + issue7033_trunk_3.diff

messages: + msg96740
2009-12-20 14:23:21pitrousetmessages: + msg96682
2009-12-20 14:14:49r.david.murraysetmessages: + msg96680
2009-12-20 14:13:36georg.brandlsetmessages: + msg96679
2009-12-20 14:09:10r.david.murraysetmessages: + msg96677
2009-12-20 14:08:06pitrousetnosy: + pitrou
messages: + msg96676
2009-12-20 14:06:15r.david.murraysetpriority: normal

nosy: + r.david.murray
messages: + msg96675

stage: patch review
2009-12-20 09:21:52lekmasetmessages: + msg96667
2009-10-04 09:36:11lekmasetfiles: + issue7033_py3k_2.diff

messages: + msg93527
2009-10-04 09:34:54lekmasetfiles: + issue7033_trunk_2.diff

messages: + msg93526
2009-10-03 09:30:07georg.brandlsetnosy: + georg.brandl
messages: + msg93484
2009-10-02 17:24:26lekmasetfiles: + issue7033_py3k.diff

messages: + msg93449
2009-10-02 17:23:31lekmasetfiles: + issue7033_trunk.diff
keywords: + patch
messages: + msg93448
2009-10-02 11:14:29lekmacreate