Conteo de referencias
*********************

Las funciones y macros de esta sección se utilizan para administrar
conteos de referencia de objetos en Python.

Py_ssize_t Py_REFCNT(PyObject *o)

   Obtiene el recuento de referencias para el objeto de Python *o*.

   Ten cuenta que el valor devuelto puede que no reflejar cuantas
   referencias al objecto existen realmente. Por ejemplo, algunos
   objetos son *immortal* y tienen un refcount muy alto que no refleja
   el número real de referencias. Por lo tanto, no confíes en que el
   valor devuelto sea preciso, salvo cuando sea 0 o 1.

   Usa la función "Py_SET_REFCNT()" para establecer la cuenta de
   referencias de un objeto.

   Distinto en la versión 3.10: "Py_REFCNT()" se convierte en una
   función estática en línea.

   Distinto en la versión 3.11: El tipo de parámetro ya no es const
   PyObject*.

void Py_SET_REFCNT(PyObject *o, Py_ssize_t refcnt)

   Establece la cuenta de referencias del objeto *o* al valor
   *refcnt*.

   En compilación de Python con Free Threading, si *refcnt* es mas
   mayor que "UINT32_MAX", el objeto se convierte en *immortal*.

   Esta función no afecta a los objetos *immortal*.

   Added in version 3.9.

   Distinto en la versión 3.12: Los objetos inmortales no se
   modifican.

void Py_INCREF(PyObject *o)

   Indica tomar una nueva *strong reference* al objeto *o*, lo que
   indica que está en uso y no debe ser destruido.

   Esta función no afecta a los objetos *immortal*.

   Esta función se usa generalmente para convertir un *borrowed
   reference* en un *strong reference* en su lugar. La función
   "Py_NewRef()" se puede utilizar para crear un nuevo *strong
   reference*.

   Cuando se termine de usar el objeto, se libera llamando a
   "Py_DECREF()".

   El objeto no debe ser "NULL"; si no está seguro de que no sea
   "NULL", use "Py_XINCREF()".

   No esperes que esta función modifique realmente *o* de ninguna
   manera. Al menos para **algunos objetos**, esta función no tiene
   ningún efecto.

   Distinto en la versión 3.12: Los objetos inmortales no se
   modifican.

void Py_XINCREF(PyObject *o)

   Similar a "Py_INCREF()", pero el objeto *o* puede ser "NULL", en
   cuyo caso esto no tiene efecto.

   Ver también "Py_XNewRef()".

PyObject *Py_NewRef(PyObject *o)
    * Part of the Stable ABI since version 3.10.*

   Crea una nueva *strong reference* a un objeto: llama a
   "Py_INCREF()" sobre *o* y devuelve el objeto *o*.

   Cuando la *strong reference* ya no sea necesaria, se debe llamar a
   "Py_DECREF()" para disminuir el recuento de referencias del objeto.

   El objeto *o* no debe ser "NULL"; use "Py_XNewRef()" si *o* puede
   ser "NULL".

   Por ejemplo:

      Py_INCREF(obj);
      self->attr = obj;

   puede ser escrito como:

      self->attr = Py_NewRef(obj);

   Ver también "Py_INCREF()".

   Added in version 3.10.

PyObject *Py_XNewRef(PyObject *o)
    * Part of the Stable ABI since version 3.10.*

   Similar a "Py_NewRef()", pero el objeto *o* puede ser NULL.

   Si el objeto *o* es "NULL", la función solo retorna "NULL".

   Added in version 3.10.

void Py_DECREF(PyObject *o)

   Libera una *strong reference* al objeto *o*, indicando que la
   referencia ya no se usa.

   Esta función no afecta a los objetos *immortal*.

   Una vez que la última *strong reference* sea liberada (por ejemplo,
   cuando la cuenta de referencias del objeto llegue a 0), se invoca
   la función de desasignación del tipo de objeto (la cual no debe ser
   "NULL").

   Esta función se usa generalmente para eliminar un *strong
   reference* antes de salir de su alcance.

   El objeto no debe ser "NULL"; si no está seguro de que no sea
   "NULL", use "Py_XINCREF()".

   No esperes que esta función modifique realmente *o* de ninguna
   manera. Al menos para **algunos objetos**, esta función no tiene
   ningún efecto.

   Advertencia:

     La función de desasignación puede hacer que se invoque un código
     arbitrario de Python (por ejemplo, cuando se desasigna una
     instancia de clase con el método "__del__()"). Mientras las
     excepciones en dicho código no sean propagadas, el código
     ejecutado tendrá acceso libre a todas las variables globales de
     Python. Esto significa que cualquier objeto al que se pueda
     acceder desde una variable global debería estar en un estado
     coherente antes de invocar a "Py_DECREF()". Por ejemplo, el
     código para eliminar un objeto de una lista debe copiar una
     referencia al objeto eliminado en una variable temporal,
     actualizar la estructura de datos de la lista y luego llamar a
     "Py_DECREF()" para la variable temporal.

   Distinto en la versión 3.12: Los objetos inmortales no se
   modifican.

void Py_XDECREF(PyObject *o)

   Similar a "Py_DECREF()", pero el objeto *o* puede ser "NULL", en
   cuyo caso esto no tendría efecto alguno. El mismo aviso de
   "Py_DECREF()" aplica aquí también.

void Py_CLEAR(PyObject *o)

   Libera una *strong reference* del objeto *o*. El objeto puede ser
   "NULL", en cuyo caso el macro no tiene efecto; de lo contrario, el
   efecto es el mismo que el de "Py_DECREF()", excepto que el
   argumento también se establece en "NULL". La advertencia de
   "Py_DECREF()" no se aplica en este caso, ya que el macro usa
   cuidadosamente una variable temporal y asigna "NULL" al argumento
   antes de liberar la referencia.

   Es buena idea usar este macro al liberar una referencia de un
   objeto que podría ser recorrido durante la recolección de basura.

   Distinto en la versión 3.12: Ahora, el macro argumento solo se
   evalúa una vez. Si el argumento tiene efectos secundarios, estos ya
   no se duplican.

void Py_IncRef(PyObject *o)
    * Part of the Stable ABI.*

   Indica la toma de una nueva *strong reference* al objeto *o*. Es
   una versión en forma de función de "Py_XINCREF()". Puede utilizarse
   para la integración dinámica de Python en tiempo de ejecución.

void Py_DecRef(PyObject *o)
    * Part of the Stable ABI.*

   Libera una *strong reference* al objeto *o*. Una versión en forma
   de función de "Py_XDECREF()". Puede utilizarse para la integración
   dinámica de Python en tiempo de ejecución.

Py_SETREF(dst, src)

   Un macro que libera de forma segura un *strong reference* al objeto
   *dst* y establece *dst* al valor *src*.

   Como en el caso de "Py_CLEAR()", el código "obvio" puede ser
   mortal:

      Py_DECREF(dst);
      dst = src;

   La forma segura es:

      Py_SETREF(dst, src);

   That arranges to set *dst* to *src* *before* releasing the
   reference to the old value of *dst*, so that any code triggered as
   a side-effect of *dst* getting torn down no longer believes *dst*
   points to a valid object.

   Added in version 3.6.

   Distinto en la versión 3.12: Los macro argumentos ahora solo se
   evalúan una vez. Si algún argumento tiene efectos secundarios,
   estos ya no se duplican.

Py_XSETREF(dst, src)

   Un variante del macro "Py_SETREF" que usa "Py_XDECREF()" en lugar
   de "Py_DECREF()".

   Added in version 3.6.

   Distinto en la versión 3.12: Los macro argumentos ahora solo se
   evalúan una vez. Si algún argumento tiene efectos secundarios,
   estos ya no se duplican.
