GNU Info

(python2.1-ext.info)Ownership Rules

---

Next: Thin Ice Prev: Reference Counting in Python Up: Reference Counts

---

Enter node , (file) or (file)node

Ownership Rules
---------------

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()',
`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.