# 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.