The standard convention in the Python C-API is that
functions do not steal references from input arguments (that are objects)
return values and output arguments (that are objects) own a reference
Most functions in the Python C-API follow this convention. However, there are some exceptions. I have come across the following:
Functions that steal a reference from an input argument
PyModule_AddObject
Functions with return values or output arguments that borrow a reference
PyErr_Occurred
PyTuple_GetItem
PyTuple_GETITEM
PyDict_GetItem
PyDict_GetItemString
PyDict_Next
Is there a comprehensive list of such functions anywhere? Such a list would be a useful reference when writing Python extension modules.
A text search in the Python 2.7.2 C-API docs for the words "steal" and "borrow" gave the following lists:
Functions that steal a reference from an input argument
Functions with return values or output arguments that borrow a reference
This thread on the Python-Dev strongly suggests that such a list does not exist. The thread also discusses what to do about it.