[issue10058] C-API Intro should be more explicit about error return codes

[Nikolaus Rath]

Nikolaus Rath <Nikolaus at rath.org> added the comment:

Georg, this is an important piece of information, but I think it is not yet clearly stated in the documentation. Here is what  http://docs.python.org/c-api/intro.html says about return codes:

"In general, when a function encounters an error, it sets an exception, discards any object references that it owns, and returns an error indicator — usually NULL or -1. A few functions return a Boolean true/false result, with false indicating an error. Very few functions return no explicit error indicator or have an ambiguous return value, and require explicit testing for errors with PyErr_Occurred()."

If this is meant to say that a function returns *only* -1 or NULL in case of an error, *unless documented otherwise* I suggest that the wording be changed to reflect that. Maybe like this:

"In general, when a function encounters an error, it sets an exception, discards any object references that it owns, and returns either NULL or -1 (depending on what is compatible with the function's type). If a functions documentation does not say otherwise, the function can be assumed to follow this convention. Nevertheless, a few functions return a Boolean true/false result, with false indicating an error, and very few functions return no explicit error indicator or have an ambiguous return value, and require explicit testing for errors with PyErr_Occurred()."



Wouldn't that be a reasonable change?

----------
title: Unclear PyString_AsStringAndSize return value -> C-API Intro should be more explicit about error return codes

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue10058>
_______________________________________