1.10.2 Reglas de propiedad

Siempre que se mete o saca una referencia a un objeto de una función, es parte de la especificación de la interfaz de la función si se transfiere la propiedad (en el sentido de posesión, no de característica) con la referencia o no.

La mayoría de las funciones que devuelven una referencia a un objeto traspasan la propiedad con la referencia. En particular, todas las funciones cuyo propósito es la creación de un nuevo objeto, por ejemplo PyInt_FromLong() y Py_BuildValue(), traspasan la propiedad al receptor. Aun en el caso en que, de hecho, el receptor no reciba una referencia a un objeto nuevo del todo, se recibe la propiedad. Por ejemplo, PyInt_FromLong() mantiene una caché de valores comunes y puede devolver una referencia a un elemento de la caché.

Muchas funciones que extraen objetos de otros objetos también traspasan la propiedad con la referencia, por ejemplo PyObject_GetAttrString(). La cosa no está tan clara aquí, sin embargo, pues algunas rutinas comunes no cumplen esto: PyTuple_GetItem(), PyList_GetItem(), PyDict_GetItem() y PyDict_GetItemString() devuelven referencias prestadas de la tupla, lista o diccionario.

La función PyImport_AddModule() también devuelve una referencia prestada, aunque haya generado el objeto devuelto: Esto es posible porque se almacena una referencia propia al objeto en sys.modules.

Al pasar una referencia a objeto a otra función, en general, la función toma prestada la referencia. Si necesita almacenarla, utilizará Py_INCREF() para hacerse propietario independiente. Hay exactamente dos importantes excepciones a esta regla: PyTuple_SetItem() y PyList_SetItem(). Estas funciones toman la propiedad del elemento que reciben ¡aunque fracasen! PyDict_SetItem() y similares, sin embargo, no adquieren la propiedad, son ``normales''.

Cuando se llama a una función de C desde Python, toma prestadas las referencias de sus argumentos del llamante. El llamante posee referencias a los objetos, por lo que la vida de la referencia prestada está garantizada hasta el retorno de la función. Sólo cuando una de estas referencias prestadas se deba almacenar o pasar a su vez se debe convertir en referencia propia llamando a Py_INCREF().

La referencia a objeto devuelta desde una función C llamada desde Python debe ser una referencia propia; se traspasa la propiedad de la función a su llamante.


Ver Sobre este documento... para obtener información sobre sugerencias.