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, such as PyInt_FromLong() and
Py_BuildValue(), pass ownership to the receiver. Even if
the object is not actually new, you still receive ownership of a new
reference to that object. 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(),
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.