Whenever an object reference is passed into or out of a function, it is part of the function's interface specification whether ownership is transferred with the reference or not.
Most functions that return a reference to an object pass on ownership
with the reference. In particular, all functions whose function it is
to create a new object, e.g. PyInt_FromLong() and
Py_BuildValue(), pass ownership to the receiver. Even if in
fact, in some cases, you don't receive a reference to a brand new
object, you still receive ownership of the reference. For instance,
PyInt_FromLong() maintains a cache of popular values and can
return a reference to a cached item.
Many functions that extract objects from other objects also transfer
ownership with the reference, for instance
PyObject_GetAttrString(). The picture is less clear, here,
however, since a few common routines are exceptions:
PyTuple_GetItem(), PyList_GetItem() and
PyDict_GetItem() (and PyDict_GetItemString()) all return
references that you borrow from the tuple, list or dictionary.
The function PyImport_AddModule() also returns a borrowed
reference, even though it may actually create the object it returns:
this is possible because an owned reference to the object is stored in
sys.modules.
When you pass an object reference into another function, in general,
the function borrows the reference from you -- if it needs to store
it, it will use Py_INCREF() to become an independent owner.
There are exactly two important exceptions to this rule:
PyTuple_SetItem() and PyList_SetItem(). These functions
take over ownership of the item passed to them -- even if they fail!
(Note that PyDict_SetItem() and friends don't take over
ownership -- they are ``normal''.)
When a C function is called from Python, it borrows references to its
arguments from the caller. The caller owns a reference to the object,
so the borrowed reference's lifetime is guaranteed until the function
returns. Only when such a borrowed reference must be stored or passed
on, it must be turned into an owned reference by calling
Py_INCREF().
The object reference returned from a C function that is called from Python must be an owned reference -- ownership is tranferred from the function to its caller.