Reference Counting
******************

Les macros dans cette section permettent de gérer le compteur de
références des objets 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.

   Cette fonction est souvent utilisée pour convertir une *référence
   empruntée* en une *référence forte* *sur place*. La fonction
   "Py_NewRef()" peut être utilisée pour créer une nouvelle *référence
   forte*.

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

   L'objet ne doit pas être "NULL", la fonction "Py_XINCREF()" doit
   être utilisée s'il est possible qu'il soit "NULL".

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

void Py_XINCREF(PyObject *o)

   Similar to "Py_INCREF()", but the object *o* can be "NULL", in
   which case this has no effect.

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

   L'objet *o* ne doit pas être "NULL" et la fonction "Py_XNewRef()"
   doit être utilisée si *o* peut être "NULL".

   Par exemple :

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

   peut s'écrire :

      self->attr = Py_NewRef(obj);

   Voir aussi "Py_INCREF()".

   Nouveau dans la version 3.10.

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

   Semblable à "Py_NewRef()" mais l'objet *o* peut être "NULL".

   Cette fonction renvoie "NULL" si l'objet *o* est "NULL".

   Nouveau dans la version 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.

   Cette fonction est généralement utilisée pour supprimer une
   *référence forte* avant qu'elle ne soit plus accessible.

   L'objet en argument ne doit pas être "NULL". "Py_XDECREF()" doit
   être utilisée si l'objet peut être "NULL".

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

   Avertissement:

     La fonction de dés-allocation peut invoquer du code Python
     arbitraire (par exemple quand une instance d'une classe avec une
     méthode "__del__()" est supprimée). Le code exécuté a accès à
     toutes les variables Python globales mais les exceptions lors de
     l'exécution de ce code ne sont pas propagées. Tous les objets qui
     peuvent être atteints à partir d'une variable globale doivent
     être dans un état cohérent avant d'appeler "Py_DECREF()". Par
     exemple le code pour supprimer un élément d'une liste doit copier
     une référence à l'objet dans une variable temporaire, mettre à
     jour la liste, et enfin appeler "Py_DECREF()" avec la variable
     temporaire.

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.

Les fonctions ou macros suivantes doivent être uniquement utilisées au
sein de l'interpréteur et ne font pas partie de l'API publique :
"_Py_Dealloc()", "_Py_ForgetReference()", "_Py_NewReference()", ainsi
que la variable globale "_Py_RefTotal".
