Objetos de referencia débil
***************************

Python soporta *referencias débiles* como objetos de primera clase.
Hay dos tipos de objetos específicos que implementan directamente
referencias débiles. El primero es un objeto con referencia simple, y
el segundo actúa como un proxy del objeto original tanto como pueda.

int PyWeakref_Check(PyObject *ob)

   Retorna un valor distinto de cero si *ob* es una referencia o un
   objeto proxy. Esta función siempre finaliza con éxito.

int PyWeakref_CheckRef(PyObject *ob)

   Retorna un valor distinto de cero si *ob* es un objeto de
   referencia. Esta función siempre finaliza con éxito.

int PyWeakref_CheckProxy(PyObject *ob)

   Retorna un valor distinto de cero si *ob* es un objeto proxy. Esta
   función siempre finaliza con éxito.

PyObject *PyWeakref_NewRef(PyObject *ob, PyObject *callback)
    *Return value: New reference.** Part of the Stable ABI.*

   Retorna un objeto de referencia débil para el objeto *ob*. Esto
   siempre retornará una nueva referencia, pero no garantiza la
   creación de un objeto nuevo; un objeto de referencia ya existente
   puede ser retornado. El segundo parámetro, *callback*, puede ser un
   objeto invocable que recibe una notificación cuando *ob* es
   recolectado como basura; debe aceptar un solo parámetro, el cual
   será el mismo objeto de referencia débil. *callback* también puede
   ser "None" o "NULL". Si *ob* no es un objeto que puede ser referido
   de forma débil, o si *callback* no es invocable, "None", o "NULL",
   esto retornará "NULL" y lanzará un "TypeError".

PyObject *PyWeakref_NewProxy(PyObject *ob, PyObject *callback)
    *Return value: New reference.** Part of the Stable ABI.*

   Retorna un objeto proxy de referencia débil para el objeto *ob*.
   Esto siempre retornará una nueva referencia, pero no garantiza la
   creación de un objeto nuevo; un objeto proxy de referencia ya
   existente puede ser retornado. El segundo parámetro, *callback*,
   puede ser un objeto invocable que recibe una notificación cuando
   *ob* es recolectado como basura; debe aceptar un solo parámetro, el
   cual será el mismo objeto de referencia débil. *callback* también
   puede ser "None" o "NULL". Si *ob* no es un objeto que puede ser
   referido de forma débil, o si *callback* no es invocable, "None", o
   "NULL", esto retornará "NULL" y lanzará un "TypeError".

int PyWeakref_GetRef(PyObject *ref, PyObject **pobj)
    * Part of the Stable ABI since version 3.13.*

   Obtiene un *strong reference* al objeto referenciado desde una
   referencia débil, *ref*, en **pobj*.

   * En caso de éxito, asigna **pobj* en un nuevo *strong reference*
     al objeto referenciado y retorna 1.

   * Si la referencia está inactiva, asigna **pobj* a "NULL" y retorna
     0.

   * En caso de error, lanza una excepción y devuelve -1.

   Added in version 3.13.

PyObject *PyWeakref_GetObject(PyObject *ref)
    *Return value: Borrowed reference.** Part of the Stable ABI.*

   Retorna un *borrowed reference* del objeto referenciado desde una
   referencia débil, *ref*. Si el referente ya no está activo, retorna
   "Py_None".

   Nota:

     Esta función retorna una referencia *borrowed reference* al
     objeto referenciado. Esto significa que siempre debe llamar a
     "Py_INCREF()" sobre el objeto excepto cuando no pueda ser
     destruido antes del último uso de la referencia prestada.

   Deprecated since version 3.13, will be removed in version 3.15:
   Utiliza "PyWeakref_GetRef()" en su lugar.

PyObject *PyWeakref_GET_OBJECT(PyObject *ref)
    *Return value: Borrowed reference.*

   Similar a "PyWeakref_GetObject()", pero no realiza ninguna
   comprobación de errores.

   Deprecated since version 3.13, will be removed in version 3.15:
   Utiliza "PyWeakref_GetRef()" en su lugar.

int PyWeakref_IsDead(PyObject *ref)

   Test if the weak reference *ref* is dead. Returns 1 if the
   reference is dead, 0 if it is alive, and -1 with an error set if
   *ref* is not a weak reference object.

   Added in version 3.14.

void PyObject_ClearWeakRefs(PyObject *object)
    * Part of the Stable ABI.*

   Esta función es invocada por el gestor "tp_dealloc" para limpiar
   referencias débiles.

   Esto recorre las referencias débiles de *object* e invoca
   retrollamadas para aquellas referencias que tengan una. Retorna
   cuando se han intentado todas las retrollamadas.

void PyUnstable_Object_ClearWeakRefsNoCallbacks(PyObject *object)

   *This is Unstable API. It may change without warning in minor
   releases.*

   Borra las referencias débiles para *object* sin llamar a las
   retrollamadas.

   Esta función es invocada por el gestor "tp_dealloc" para tipos con
   finalizadores (i.e., "__del__()"). El gestor de esos objetos
   primero llama a "PyObject_ClearWeakRefs()" para borrar las
   referencias débiles y llamar a sus callbacks, luego al finalizador,
   y finalmente a esta función para borrar cualquier referencia débil
   que pueda haber sido creada por el finalizador.

   En la mayoría de los casos, es más apropiado utilizar
   "PyObject_ClearWeakRefs()" para borrar las referencias débiles en
   lugar de esta función.

   Added in version 3.13.
