Objetos función
***************

Hay algunas funciones específicas para las funciones de Python.

type PyFunctionObject

   La estructura C utilizada para las funciones.

PyTypeObject PyFunction_Type

   Esta es una instancia de "PyTypeObject" y representa el tipo
   función de Python. Está expuesto a los programadores de Python como
   "types.FunctionType".

int PyFunction_Check(PyObject *o)

   Retorna verdadero si *o* es un objeto función (tiene tipo
   "PyFunction_Type"). El parámetro no debe ser "NULL". Esta función
   siempre finaliza con éxito.

PyObject *PyFunction_New(PyObject *code, PyObject *globals)
    *Return value: New reference.*

   Retorna un nuevo objeto función asociado con el objeto código
   *code*. *globals* debe ser un diccionario con las variables
   globales accesibles para la función.

   El docstring y el nombre de la función se obtienen del objeto
   código. "__module__" se obtiene de *globals*. Los argumentos por
   defecto, anotaciones y clausura se establecen en "NULL".
   "__qualname__" se establece en el mismo valor que el campo
   "co_qualname" del objeto código.

PyObject *PyFunction_NewWithQualName(PyObject *code, PyObject *globals, PyObject *qualname)
    *Return value: New reference.*

   Como "PyFunction_New()", pero también permite configurar el
   atributo "__qualname__" del objeto función. *qualname* debe ser un
   objeto unicode o "NULL"; si es "NULL", el atributo "__qualname__"
   se establece en el mismo valor que el campo "co_qualname" del
   objeto código.

   Added in version 3.3.

PyObject *PyFunction_GetCode(PyObject *op)
    *Return value: Borrowed reference.*

   Retorna el objeto código asociado con el objeto función *op*.

PyObject *PyFunction_GetGlobals(PyObject *op)
    *Return value: Borrowed reference.*

   Retorna el diccionario global asociado con el objeto función *op*.

PyObject *PyFunction_GetModule(PyObject *op)
    *Return value: Borrowed reference.*

   Retorna una *referencia prestada* al atributo "__module__" del
   objeto función *op*. Puede ser *NULL*.

   Esto es normalmente una "cadena de caracteres" que contiene el
   nombre del módulo, pero se puede establecer en cualquier otro
   objeto mediante código Python.

PyObject *PyFunction_GetDefaults(PyObject *op)
    *Return value: Borrowed reference.*

   Retorna los valores predeterminados del argumento del objeto
   función *op*. Esto puede ser una tupla de argumentos o "NULL".

int PyFunction_SetDefaults(PyObject *op, PyObject *defaults)

   Establece los valores predeterminados del argumento para el objeto
   función *op*. *defaults* deben ser "Py_None" o una tupla.

   Lanza "SystemError" y retorna "-1" en caso de error.

void PyFunction_SetVectorcall(PyFunctionObject *func, vectorcallfunc vectorcall)

   Establece el campo vectorcall de un objeto función dado *func*.

   Advertencia: ¡las extensiones que usan esta API deben preservar el
   comportamiento de la función vectorcall inalterada (por defecto)!

   Added in version 3.12.

PyObject *PyFunction_GetKwDefaults(PyObject *op)
    *Return value: Borrowed reference.*

   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)
    *Return value: Borrowed reference.*

   Retorna el cierre asociado con el objeto función *op*. Esto puede
   ser "NULL" o una tupla de objetos celda.

int PyFunction_SetClosure(PyObject *op, PyObject *closure)

   Establece el cierre asociado con el objeto función *op*. *cierre*
   debe ser "Py_None" o una tupla de objetos celda.

   Lanza "SystemError" y retorna "-1" en caso de error.

PyObject *PyFunction_GetAnnotations(PyObject *op)
    *Return value: Borrowed reference.*

   Retorna las anotaciones del objeto función *op*. Este puede ser un
   diccionario mutable o "NULL".

int PyFunction_SetAnnotations(PyObject *op, PyObject *annotations)

   Establece las anotaciones para el objeto función *op*.
   *annotations* debe ser un diccionario o "Py_None".

   Lanza "SystemError" y retorna "-1" en caso de error.

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)
    *Return value: Borrowed reference.*

   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)

   Registra *callback* como un observador de función para el
   intérprete actual. Retorna un ID que puede pasarse a
   "PyFunction_ClearWatcher()". En caso de error (por ejemplo, no hay
   más IDs de observador disponibles), retorna "-1" y establece una
   excepción.

   Added in version 3.12.

int PyFunction_ClearWatcher(int watcher_id)

   Limpia el observador identificado por *watcher_id* previamente
   retornado de "PyFunction_AddWatcher()" para el intérprete actual.
   Retorna "0" en caso de éxito, o "-1" y establece una excepción en
   caso de error (por ejemplo, si el *watcher_id* dado nunca fue
   registrado).

   Added in 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"

   Added in version 3.12:

   * "PyFunction_PYFUNC_EVENT_MODIFY_QUALNAME"

   Added in version 3.15.

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

   Tipo de una función callback de observador de función.

   Si *event* es "PyFunction_EVENT_CREATE" o
   "PyFunction_EVENT_DESTROY" entonces *new_value* será "NULL". De lo
   contrario, *new_value* mantendrá una *referencia prestada* al nuevo
   valor que está a punto de almacenarse en *func* para el atributo
   que se está modificando.

   El callback puede inspeccionar pero no debe modificar *func*;
   hacerlo podría tener efectos impredecibles, incluyendo recursión
   infinita.

   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.

   Si el callback establece una excepción, debe retornar "-1"; esta
   excepción se imprimirá como una excepción no lanzable usando
   "PyErr_WriteUnraisable()". De lo contrario debe retornar "0".

   Puede haber ya una excepción pendiente establecida al entrar al
   callback. En este caso, el callback debe retornar "0" con la misma
   excepción aún establecida. Esto significa que el callback no puede
   llamar a ninguna otra API que pueda establecer una excepción a
   menos que guarde y borre el estado de la excepción primero, y lo
   restaure antes de retornar.

   Added in version 3.12.
