Objets fonction
***************

Certaines fonctions sont spécifiques aux fonctions Python.

type PyFunctionObject

   La structure C utilisée pour les fonctions.

PyTypeObject PyFunction_Type

   C'est une instance de "PyTypeObject" et représente le type fonction
   en Python. Il est exposé aux développeurs comme
   "types.FunctionType".

int PyFunction_Check(PyObject *o)

   Renvoie vrai si *o* est un objet de type fonction (a comme type
   "PyFunction_Type"). Le paramètre ne doit pas être "NULL". Cette
   fonction réussit toujours.

PyObject *PyFunction_New(PyObject *code, PyObject *globals)
    *Valeur de retour : nouvelle référence.*

   Renvoie une nouvelle fonction associée avec l'objet *code*.
   *globals* doit être un dictionnaire avec les variables globales
   accessibles à la fonction.

   The function's docstring and name are retrieved from the code
   object. "__module__" is retrieved from *globals*. The argument
   defaults, annotations and closure are set to "NULL". "__qualname__"
   is set to the same value as the code object's "co_qualname" field.

PyObject *PyFunction_NewWithQualName(PyObject *code, PyObject *globals, PyObject *qualname)
    *Valeur de retour : nouvelle référence.*

   As "PyFunction_New()", but also allows setting the function
   object's "__qualname__" attribute. *qualname* should be a unicode
   object or "NULL"; if "NULL", the "__qualname__" attribute is set to
   the same value as the code object's "co_qualname" field.

   Ajouté dans la version 3.3.

PyObject *PyFunction_GetCode(PyObject *op)
    *Valeur de retour : référence empruntée.*

   Renvoie l'objet code associé avec l'objet de la fonction *op*.

PyObject *PyFunction_GetGlobals(PyObject *op)
    *Valeur de retour : référence empruntée.*

   Renvoie le dictionnaire global associé avec l'objet de la fonction
   *op*.

PyObject *PyFunction_GetModule(PyObject *op)
    *Valeur de retour : référence empruntée.*

   Return a *borrowed reference* to the "__module__" attribute of the
   function object *op*. It can be *NULL*.

   This is normally a "string" containing the module name, but can be
   set to any other object by Python code.

PyObject *PyFunction_GetDefaults(PyObject *op)
    *Valeur de retour : référence empruntée.*

   Renvoie les valeurs par défaut de l'argument de l'objet de la
   fonction *op*. Cela peut être un tuple d'arguments ou "NULL".

int PyFunction_SetDefaults(PyObject *op, PyObject *defaults)

   Définir les valeurs par défaut de l'argument pour l'objet de la
   fonction *op*. *defaults* doit être "Py_None" ou un tuple.

   Lève "SystemError" et renvoie "-1" en cas de d'échec.

void PyFunction_SetVectorcall(PyFunctionObject *func, vectorcallfunc vectorcall)

   Set the vectorcall field of a given function object *func*.

   Warning: extensions using this API must preserve the behavior of
   the unaltered (default) vectorcall function!

   Ajouté dans la version 3.12.

PyObject *PyFunction_GetKwDefaults(PyObject *op)
    *Valeur de retour : référence empruntée.*

   Return the keyword-only argument default values of the function
   object *op*. This can be a dictionary of arguments or "NULL".

int PyFunction_SetKwDefaults(PyObject *op, PyObject *defaults)

   Set the keyword-only argument default values of the function object
   *op*. *defaults* must be a dictionary of keyword-only arguments or
   "Py_None".

   This function returns "0" on success, and returns "-1" with an
   exception set on failure.

PyObject *PyFunction_GetClosure(PyObject *op)
    *Valeur de retour : référence empruntée.*

   Renvoie la fermeture associée avec l'objet de la fonction *op*.
   Cela peut être "NULL" ou un tuple d'objets cellule.

int PyFunction_SetClosure(PyObject *op, PyObject *closure)

   Définir la fermeture associée avec l'objet de la fonction *op*.
   *closure* doit être "Py_None" ou un tuple d'objets cellule.

   Lève "SystemError" et renvoie "-1" en cas de d'échec.

PyObject *PyFunction_GetAnnotations(PyObject *op)
    *Valeur de retour : référence empruntée.*

   Renvoie les annotations de l'objet de la fonction *op*. Cela peut
   être un dictionnaire mutable ou "NULL".

int PyFunction_SetAnnotations(PyObject *op, PyObject *annotations)

   Définir les annotations pour l'objet de la fonction *op*.
   *annotations* doit être un dictionnaire ou "Py_None".

   Lève "SystemError" et renvoie "-1" en cas de d'échec.

PyObject *PyFunction_GET_CODE(PyObject *op)
PyObject *PyFunction_GET_GLOBALS(PyObject *op)
PyObject *PyFunction_GET_MODULE(PyObject *op)
PyObject *PyFunction_GET_DEFAULTS(PyObject *op)
PyObject *PyFunction_GET_KW_DEFAULTS(PyObject *op)
PyObject *PyFunction_GET_CLOSURE(PyObject *op)
PyObject *PyFunction_GET_ANNOTATIONS(PyObject *op)
    *Valeur de retour : référence empruntée.*

   These functions are similar to their "PyFunction_Get*"
   counterparts, but do not do type checking. Passing anything other
   than an instance of "PyFunction_Type" is undefined behavior.

int PyFunction_AddWatcher(PyFunction_WatchCallback callback)

   Register *callback* as a function watcher for the current
   interpreter. Return an ID which may be passed to
   "PyFunction_ClearWatcher()". In case of error (e.g. no more watcher
   IDs available), return "-1" and set an exception.

   Ajouté dans la version 3.12.

int PyFunction_ClearWatcher(int watcher_id)

   Clear watcher identified by *watcher_id* previously returned from
   "PyFunction_AddWatcher()" for the current interpreter. Return "0"
   on success, or "-1" and set an exception on error (e.g.  if the
   given *watcher_id* was never registered.)

   Ajouté dans la version 3.12.

type PyFunction_WatchEvent

      Enumeration of possible function watcher events:

      * "PyFunction_EVENT_CREATE"

      * "PyFunction_EVENT_DESTROY"

      * "PyFunction_EVENT_MODIFY_CODE"

      * "PyFunction_EVENT_MODIFY_DEFAULTS"

      * "PyFunction_EVENT_MODIFY_KWDEFAULTS"

   Ajouté dans la version 3.12:

   * "PyFunction_PYFUNC_EVENT_MODIFY_QUALNAME"

   Ajouté dans la version 3.15.

typedef int (*PyFunction_WatchCallback)(PyFunction_WatchEvent event, PyFunctionObject *func, PyObject *new_value)

   Type of a function watcher callback function.

   If *event* is "PyFunction_EVENT_CREATE" or
   "PyFunction_EVENT_DESTROY" then *new_value* will be "NULL".
   Otherwise, *new_value* will hold a *borrowed reference* to the new
   value that is about to be stored in *func* for the attribute that
   is being modified.

   The callback may inspect but must not modify *func*; doing so could
   have unpredictable effects, including infinite recursion.

   If *event* is "PyFunction_EVENT_CREATE", then the callback is
   invoked after *func* has been fully initialized. Otherwise, the
   callback is invoked before the modification to *func* takes place,
   so the prior state of *func* can be inspected. The runtime is
   permitted to optimize away the creation of function objects when
   possible. In such cases no event will be emitted. Although this
   creates the possibility of an observable difference of runtime
   behavior depending on optimization decisions, it does not change
   the semantics of the Python code being executed.

   If *event* is "PyFunction_EVENT_DESTROY", taking a reference in the
   callback to the about-to-be-destroyed function will resurrect it,
   preventing it from being freed at this time. When the resurrected
   object is destroyed later, any watcher callbacks active at that
   time will be called again.

   If the callback sets an exception, it must return "-1"; this
   exception will be printed as an unraisable exception using
   "PyErr_WriteUnraisable()". Otherwise it should return "0".

   There may already be a pending exception set on entry to the
   callback. In this case, the callback should return "0" with the
   same exception still set. This means the callback may not call any
   other API that can set an exception unless it saves and clears the
   exception state first, and restores it before returning.

   Ajouté dans la version 3.12.
