Return value conventions

[encukou]

New API functions can return:

• An integral value, where -1 is returned if and only if an exception was raised, and non-negative values signal an absence of exception. Negative values other than -1 are never returned. (edit: they are, for hashes -- see below)
• A pointer, where NULL is returned if and only if an exception was raised.
• (Or PyStatus for pre-initialization functions.)

The return values need to be documented.
Some existing functions don't follow this convention.

If NULL or a negative number are valid outputs, the function needs to reserve the return value for signaling errors, and take an extra *result argument that it fills.

XXX: Is *result set on failure?

"Errors" that you expect to be common, where you want to avoid the overhead of creating an exception object (like the AttributeError from a getattr), aren't treated as failures. In these cases, return 0 for the expected "error", and 1 for complete success.
XXX: is *result set in this case?

[gvanrossum]

@encukou Can you edit this a bit? It looks like some kind of copy/paste error.

Also, I would avoid the loaded term "success", at least for int-returning functions -- for cases like PyDict_GetItemRef(), users might not consider 0 to be a success, but it's not an error. Maybe we can say "absence of exception"?

We might also want to call out that there are families of existing APIs that return 0 for success and 1 for error (following shell conventions), and others that return 0 for error and 1 for success. So we will have to continue documenting the return value in each case. (Less so for functions that return NULL for some success cases -- those are rather exceptional and unless explicitly documented, a NULL always means an error occurred.)

[encukou]

Edited, thanks.

IMO, we should always document return values -- at least have a summary with a link. Not everyone reads the section that applies to all of the API.

[gvanrossum]

XXX: Is *result set on failure?
[...]
XXX: is *result set in this case?

I vote for always setting the result to something, and document this. If the result is an object, in the error case the result should be NULL. If the result is something else, hopefully there's some useful "neutral" value (e.g. 0 or -1 for integers).

[erlend-aasland]

I vote for always setting the result to something, and document this.

See also https://github.com/python/devguide/pull/1128/files

[encukou]

That's better API.
I don't think we can count on core devs always remembering to do it though – we'll probably need some kind of mandatory checklist for new API...

[vstinner]

See also capi-workgroup/problems#1 "Ambiguous return values".

[vstinner]

See also python/devguide#1129 "Improve C API guidelines for return values".

[vstinner]

See also python/devguide#1125 "C API: Add guidelines for C APIs with output params".