Esta documentação é de uma versão antiga do Python que não é mais atualizada. Você deveria atualizar e ler a Documentação do Python para versão estável atual.

# Contagem de referências

As macros nesta seção são usadas para gerenciar contagens de referências de objetos Python.

void `Py_INCREF`(PyObject *o)

  Aumenta a contagem de referências para o objeto o. O objeto não deve ser `NULL`; se você não tem certeza de que não é `NULL`, use `Py_XINCREF()`.

void `Py_XINCREF`(PyObject *o)

  Aumenta a contagem de referências para o objeto o. O objeto pode ser `NULL`, caso em que a macro não tem efeito.

void `Py_DECREF`(PyObject *o)

  Diminui a contagem de referências para o objeto o. O objeto não deve ser `NULL`; se você não tem certeza de que não é `NULL`, use `Py_XDECREF()`. Se a contagem de referências chegar a zero, a função de desalocação do tipo de objeto (que não deve ser `NULL`) é chamada.

  Aviso

  A função de desalocação pode fazer com que o código Python arbitrário seja invocado (por exemplo, quando uma instância de classe com um método `__del__()` é desalocada). Embora as exceções em tal código não sejam propagadas, o código executado tem acesso livre a todas as variáveis globais do Python. Isso significa que qualquer objeto que é alcançável de uma variável global deve estar em um estado consistente antes de `Py_DECREF()` ser invocado. Por exemplo, o código para excluir um objeto de uma lista deve copiar uma referência ao objeto excluído em uma variável temporária, atualizar a estrutura de dados da lista e então chamar `Py_DECREF()` para a variável temporária.

void `Py_XDECREF`(PyObject *o)

  Diminui a contagem de referências para o objeto o. O objeto pode ser `NULL`, caso em que a macro não tem efeito; caso contrário, o efeito é o mesmo de `Py_DECREF()`, e o mesmo aviso se aplica.

void `Py_CLEAR`(PyObject *o)

  Diminui a contagem de referências para o objeto o. O objeto pode ser `NULL`, caso em que a macro não tem efeito; caso contrário, o efeito é o mesmo de `Py_DECREF()`, exceto que o argumento também é definido como `NULL`. O aviso para `Py_DECREF()` não se aplica em relação ao objeto passado porque a macro usa cuidadosamente uma variável temporária e define o argumento como `NULL` antes de diminuir sua contagem de referências.

  É uma boa ideia usar essa macro sempre que diminuir a contagem de referências de um objeto que pode ser percorrido durante a coleta de lixo.

As seguintes funções são para incorporação dinâmica de Python em tempo de execução: `Py_IncRef(PyObject *o)`, `Py_DecRef(PyObject *o)`. Elas são simplesmente versões de função exportadas de `Py_XINCREF()` e `Py_XDECREF()`, respectivamente.

As seguintes funções ou macros são apenas para uso dentro do núcleo do interpretador: `_Py_Dealloc()`, `_Py_ForgetReference()`, `_Py_NewReference()`, bem como a variável global `_Py_RefTotal`.