classification
Title: C API PyArg_ParseTuple doc is innacurate
Type: enhancement Stage:
Components: C API, Documentation Versions: Python 3.3, Python 3.4, Python 3.5
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Banger, docs@python, josh.r
Priority: normal Keywords:

Created on 2014-05-14 14:33 by Banger, last changed 2020-06-25 09:40 by vstinner.

Messages (4)
msg218536 - (view) Author: Steve (Banger) Date: 2014-05-14 14:33
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.
msg218590 - (view) Author: Josh Rosenberg (josh.r) * (Python triager) Date: 2014-05-15 02:18
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).
msg218614 - (view) Author: Steve (Banger) Date: 2014-05-15 15:13
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.
msg218636 - (view) Author: Josh Rosenberg (josh.r) * (Python triager) Date: 2014-05-16 00:46
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.
History
Date User Action Args
2020-06-25 09:40:40vstinnersetcomponents: + C API
2014-05-16 00:46:32josh.rsetmessages: + msg218636
2014-05-15 15:13:47Bangersetmessages: + msg218614
2014-05-15 02:18:32josh.rsetnosy: + josh.r
messages: + msg218590
2014-05-14 14:33:43Bangercreate