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)

   Indicate taking a new *strong reference* to object *o*, indicating
   it is in use and should not be destroyed.

   Esta função é geralmente usada para transformar uma *referência
   emprestada* em uma *referência forte* local. A função "Py_NewRef()"
   pode ser usada para criar uma nova *referência forte*.

   When done using the object, release it by calling "Py_DECREF()".

   The object must not be "NULL"; if you aren't sure that it isn't
   "NULL", use "Py_XINCREF()".

   Do not expect this function to actually modify *o* in any way.

void Py_XINCREF(PyObject *o)

   Semelhante a "Py_INCREF()", mas o objeto *o* pode ser "NULL", caso
   em que isso não tem efeito.

   Veja também "Py_XNewRef()".

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

   Create a new *strong reference* to an object: call "Py_INCREF()" on
   *o* and return the object *o*.

   When the *strong reference* is no longer needed, "Py_DECREF()"
   should be called on it to release the reference.

   The object *o* must not be "NULL"; use "Py_XNewRef()" if *o* can be
   "NULL".

   Por exemplo:

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

   can be written as:

      self->attr = Py_NewRef(obj);

   See also "Py_INCREF()".

   Novo na versão 3.10.

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

   Semelhante a "Py_NewRef()", mas o objeto *o* pode ser NULL.

   Se o objeto *o* é "NULL", a função apenas retorna "NULL".

   Novo na versão 3.10.

void Py_DECREF(PyObject *o)

   Release a *strong reference* to object *o*, indicating the
   reference is no longer used.

   Once the last *strong reference* is released (i.e. the object's
   reference count reaches 0), the object's type's deallocation
   function (which must not be "NULL") is invoked.

   This function is usually used to delete a *strong reference* before
   exiting its scope.

   The object must not be "NULL"; if you aren't sure that it isn't
   "NULL", use "Py_XDECREF()".

   Do not expect this function to actually modify *o* in any way.

   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)

   Similar to "Py_DECREF()", but the object *o* can be "NULL", in
   which case this has no effect. The same warning from "Py_DECREF()"
   applies here as well.

void Py_CLEAR(PyObject *o)

   Release a *strong reference* for object *o*. The object may be
   "NULL", in which case the macro has no effect; otherwise the effect
   is the same as for "Py_DECREF()", except that the argument is also
   set to "NULL".  The warning for "Py_DECREF()" does not apply with
   respect to the object passed because the macro carefully uses a
   temporary variable and sets the argument to "NULL" before releasing
   the reference.

   It is a good idea to use this macro whenever releasing a reference
   to an object that might be traversed during garbage collection.

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

   Indicate taking a new *strong reference* to object *o*. A function
   version of "Py_XINCREF()". It can be used for runtime dynamic
   embedding of Python.

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

   Release a *strong reference* to object *o*. A function version of
   "Py_XDECREF()". It can be used for runtime dynamic embedding of
   Python.

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