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?
New API functions can return:
-1is returned if and only if an exception was raised, and non-negative values signal an absence of exception.Negative values other than(edit: they are, for hashes -- see below)-1are never returned.NULLis returned if and only if an exception was raised.PyStatusfor pre-initialization functions.)The return values need to be documented.
Some existing functions don't follow this convention.
If
NULLor a negative number are valid outputs, the function needs to reserve the return value for signaling errors, and take an extra*resultargument that it fills.XXX: Is
*resultset on failure?"Errors" that you expect to be common, where you want to avoid the overhead of creating an exception object (like the
AttributeErrorfrom a getattr), aren't treated as failures. In these cases, return0for the expected "error", and 1 for complete success.XXX: is
*resultset in this case?