Objetos de referência fraca
***************************

O Python oferece suporte a *referências fracas* como objetos de
primeira classe. Existem dois tipos de objetos específicos que
implementam diretamente referências fracas. O primeiro é um objeto de
referência simples, e o segundo atua como um intermediário ao objeto
original tanto quanto ele pode.

int PyWeakref_Check(PyObject *ob)

   Retorna não zero se *ob* for um objeto referência ou um objeto
   intermediário. Esta função sempre tem sucesso.

int PyWeakref_CheckRef(PyObject *ob)

   Retorna não zero se *ob* for um objeto referência. Esta função
   sempre tem sucesso.

int PyWeakref_CheckProxy(PyObject *ob)

   Retorna não zero se *ob* for um objeto intermediário. Esta função
   sempre tem sucesso.

PyObject *PyWeakref_NewRef(PyObject *ob, PyObject *callback)
    *Retorna valor: Nova referência.** Parte da ABI Estável.*

   Retorna um objeto de referência fraco para o objeto *ob*. Isso
   sempre retornará uma nova referência, mas não é garantido para
   criar um novo objeto; um objeto de referência existente pode ser
   retornado. O segundo parâmetro, *callback*, pode ser um objeto
   chamável que recebe notificação quando *ob* for lixo coletado; ele
   deve aceitar um único parâmetro, que será o objeto de referência
   fraco propriamente dito. *callback* também pode ser "None" ou
   "NULL". Se *ob* não for um objeto fracamente referenciável, ou se
   *callback* não for um chamável, "None", ou "NULL", isso retornará
   "NULL" e levantará a "TypeError".

PyObject *PyWeakref_NewProxy(PyObject *ob, PyObject *callback)
    *Retorna valor: Nova referência.** Parte da ABI Estável.*

   Retorna um objeto de proxy de referência fraca para o objeto *ob*.
   Isso sempre retornará uma nova referência, mas não é garantido para
   criar um novo objeto; um objeto de proxy existente pode ser
   retornado. O segundo parâmetro, *callback*, pode ser um objeto
   chamável que recebe notificação quando *ob* for lixo coletado; ele
   deve aceitar um único parâmetro, que será o objeto de referência
   fraco propriamente dito. *callback* também pode ser "None" ou
   "NULL". Se *ob* não for um objeto referência fraca, ou se
   *callback* não for um chamável, "None", ou "NULL", isso retornará
   "NULL" e levantará a "TypeError".

int PyWeakref_GetRef(PyObject *ref, PyObject **pobj)
    * Parte da ABI Estável desde a versão 3.13.*

   Obtém uma *referência forte* para o objeto referenciado a partir de
   uma referência fraca, *ref*, em **pobj*.

   * Em caso de sucesso, define **pobj* como uma nova *referência
     forte* para o objeto referenciado e retorna 1.

   * Se a referência estiver quebrada, define **pobj* como "NULL" e
     retorna 0.

   * Em caso de erro, levanta uma exceção e retorna -1.

   Adicionado na versão 3.13.

PyObject *PyWeakref_GetObject(PyObject *ref)
    *Retorna valor: Referência emprestada.** Parte da ABI Estável.*

   Retorna uma *referência emprestada* ao objeto referenciado a partir
   de uma referência fraca, *ref*. Se o referente não estiver mais em
   tempo real, retorna "Py_None".

   Nota:

     Esta função retorna uma *referência emprestada* para o objeto
     referenciado. Isso significa que você deve sempre chamar
     "Py_INCREF()" no objeto, exceto quando ele não puder ser
     destruído antes do último uso da referência emprestada.

   Descontinuado desde a versão 3.13, será removido na versão 3.15:
   Usa "PyWeakref_GetRef()".

PyObject *PyWeakref_GET_OBJECT(PyObject *ref)
    *Retorna valor: Referência emprestada.*

   Semelhante a "PyWeakref_GetObject()", mas não verifica erros.

   Descontinuado desde a versão 3.13, será removido na versão 3.15:
   Usa "PyWeakref_GetRef()".

void PyObject_ClearWeakRefs(PyObject *object)
    * Parte da ABI Estável.*

   Esta função é chamada pelo tratador "tp_dealloc" para limpar
   referências fracas.

   Isso itera pelas referências fracas para *object* e chama retornos
   de chamada para as referências que possuem um. Ele retorna quando
   todos os retornos de chamada foram tentados.

void PyUnstable_Object_ClearWeakRefsNoCallbacks(PyObject *object)

   *Esta é uma API Instável. Isso pode se alterado sem aviso em
   lançamentos menores.*

   Clears the weakrefs for *object* without calling the callbacks.

   This function is called by the "tp_dealloc" handler for types with
   finalizers (i.e., "__del__()").  The handler for those objects
   first calls "PyObject_ClearWeakRefs()" to clear weakrefs and call
   their callbacks, then the finalizer, and finally this function to
   clear any weakrefs that may have been created by the finalizer.

   In most circumstances, it's more appropriate to use
   "PyObject_ClearWeakRefs()" to clear weakrefs instead of this
   function.

   Adicionado na versão 3.13.
