[issue21508] C API PyArg_ParseTuple doc is innacurate
New submission from Steve:
PyArg_ParseTuple is defined as returning an "int", but the documentation talks about returning a true/false value, and failling on false. In addition to being inaccurate, considering that most other functions fail on !=0 ("true"), it can lead to confusion.
Doc: int PyArg_ParseTuple(PyObject *args, const char *format, ...) Parse the parameters of a function that takes only positional parameters into local variables. Returns true on success; on failure, it returns false and raises the appropriate exception.
---------- assignee: docs@python components: Documentation messages: 218536 nosy: Banger, docs@python priority: normal severity: normal status: open title: C API PyArg_ParseTuple doc is innacurate type: enhancement versions: Python 3.3, Python 3.4, Python 3.5
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue21508 _______________________________________
Josh Rosenberg added the comment:
You'd prefer it say it returns 1 on success and 0 on failure? Or non-zero on success, zero on failure?
Is true/false that bad? After all, C says 0 is false, all other integer values are true; phrasing it as zero vs. non-zero may be slightly more technically accurate, but it's also a bit less readable, while 1 vs. 0 constrains the implementation (so you couldn't introduce a third "success but with additional info" state, similar to the third possible return from a "O&" converter function).
---------- nosy: +josh.rosenberg
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue21508 _______________________________________
Steve added the comment:
I would prefer the function to return "bool". But what I prefer is irrelevant, what counts is accuracy and clarity. And to this end, the return type and the comment have to match.
For a int return value, the document should mention a condition relative to an integer value (e.g.: ==0, !=0, ==-1, <0, ==42, etc).
In this particular case, to minimize the changes, success should be defined as !=0 and failure ==0.
Although there is a bigger problem that I mentioned in that the Python C API uses two different return value standards: in most places, ==0 is success, in this case (and some other places) ==0 is a failure.
As for "implementation constraints" I don't see how making the documentation accurate affects that in any way. If ever the implementation is expanded, the documentation will need to change. The only alternative is to make the doc vague or simply wrong.
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue21508 _______________________________________
Josh Rosenberg added the comment:
Changing the docs isn't the main hurdle; the problem is that if we told people they could test == 1, rather than != 0, then new success return codes couldn't be added without a long period of warning.
I don't think the convention is consistently 0 means success BTW. Frankly, 0 means success is just confusing in general (since it reverses the normal C convention, even if it agrees with the errno convention).
bool is sadly out, since Python is forever stuck in 1990, and will never know the joys of C99.
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue21508 _______________________________________
Change by STINNER Victor vstinner@python.org:
---------- components: +C API
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue21508 _______________________________________
participants (3)
-
Josh Rosenberg -
Steve
-
STINNER Victor