Function Objects¶

There are a few functions specific to Python functions.

typePyFunctionObject¶

The C structure used for functions.

PyTypeObjectPyFunction_Type¶

This is an instance ofPyTypeObject and represents the Python functiontype. It is exposed to Python programmers astypes.FunctionType.

intPyFunction_Check(PyObject*o)¶

Return true ifo is a function object (has typePyFunction_Type).The parameter must not beNULL. This function always succeeds.

PyObject*PyFunction_New(PyObject*code,PyObject*globals)¶

Return value: New reference.

Return a new function object associated with the code objectcode.globalsmust be a dictionary with the global variables accessible to the function.

The function’s docstring and name are retrieved from the code object.__module__is retrieved fromglobals. The argument defaults, annotations and closure areset toNULL.__qualname__ is set to the same value asthe code object’sco_qualname field.

PyObject*PyFunction_NewWithQualName(PyObject*code,PyObject*globals,PyObject*qualname)¶

Return value: New reference.

AsPyFunction_New(), but also allows setting the function object’s__qualname__ attribute.qualname should be a unicode object orNULL;ifNULL, the__qualname__ attribute is set to the same value asthe code object’sco_qualname field.

Added in version 3.3.

PyObject*PyFunction_GetCode(PyObject*op)¶

Return value: Borrowed reference.

Return the code object associated with the function objectop.

PyObject*PyFunction_GetGlobals(PyObject*op)¶

Return value: Borrowed reference.

Return the globals dictionary associated with the function objectop.

PyObject*PyFunction_GetModule(PyObject*op)¶

Return value: Borrowed reference.

Return aborrowed reference to the__module__attribute of thefunction objectop.It can beNULL.

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

PyObject*PyFunction_GetDefaults(PyObject*op)¶

Return value: Borrowed reference.

Return the argument default values of the function objectop. This can be atuple of arguments orNULL.

intPyFunction_SetDefaults(PyObject*op,PyObject*defaults)¶

Set the argument default values for the function objectop.defaults must bePy_None or a tuple.

RaisesSystemError and returns-1 on failure.

voidPyFunction_SetVectorcall(PyFunctionObject*func,vectorcallfuncvectorcall)¶

Set the vectorcall field of a given function objectfunc.

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

Added in version 3.12.

PyObject*PyFunction_GetKwDefaults(PyObject*op)¶

Return value: Borrowed reference.

Return the keyword-only argument default values of the function objectop. This can be adictionary of arguments orNULL.

PyObject*PyFunction_GetClosure(PyObject*op)¶

Return value: Borrowed reference.

Return the closure associated with the function objectop. This can beNULLor a tuple of cell objects.

intPyFunction_SetClosure(PyObject*op,PyObject*closure)¶

Set the closure associated with the function objectop.closure must bePy_None or a tuple of cell objects.

RaisesSystemError and returns-1 on failure.

PyObject*PyFunction_GetAnnotations(PyObject*op)¶

Return value: Borrowed reference.

Return the annotations of the function objectop. This can be amutable dictionary orNULL.

intPyFunction_SetAnnotations(PyObject*op,PyObject*annotations)¶

Set the annotations for the function objectop.annotationsmust be a dictionary orPy_None.

RaisesSystemError and returns-1 on failure.

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 theirPyFunction_Get* counterparts, butdo not do type checking. Passing anything other than an instance ofPyFunction_Type is undefined behavior.

intPyFunction_AddWatcher(PyFunction_WatchCallbackcallback)¶

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

Added in version 3.12.

intPyFunction_ClearWatcher(intwatcher_id)¶

Clear watcher identified bywatcher_id previously returned fromPyFunction_AddWatcher() for the current interpreter.Return0 on success, or-1 and set an exception on error(e.g. if the givenwatcher_id was never registered.)

Added in version 3.12.

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

typedefint(*PyFunction_WatchCallback)(PyFunction_WatchEventevent,PyFunctionObject*func,PyObject*new_value)¶

Type of a function watcher callback function.

Ifevent isPyFunction_EVENT_CREATE orPyFunction_EVENT_DESTROYthennew_value will beNULL. Otherwise,new_value will hold aborrowed reference to the new value that is about to be stored infunc for the attribute that is being modified.

The callback may inspect but must not modifyfunc; doing so could haveunpredictable effects, including infinite recursion.

Ifevent isPyFunction_EVENT_CREATE, then the callback is invokedafterfunc has been fully initialized. Otherwise, the callback is invokedbefore the modification tofunc takes place, so the prior state offunccan be inspected. The runtime is permitted to optimize away the creation offunction objects when possible. In such cases no event will be emitted.Although this creates the possibility of an observable difference ofruntime behavior depending on optimization decisions, it does not changethe semantics of the Python code being executed.

Ifevent isPyFunction_EVENT_DESTROY, Taking a reference in thecallback to the about-to-be-destroyed function will resurrect it, preventingit from being freed at this time. When the resurrected object is destroyedlater, any watcher callbacks active at that time will be called again.

If the callback sets an exception, it must return-1; this exception willbe printed as an unraisable exception usingPyErr_WriteUnraisable().Otherwise it should return0.

There may already be a pending exception set on entry to the callback. Inthis case, the callback should return0 with the same exception stillset. This means the callback may not call any other API that can set anexception unless it saves and clears the exception state first, and restoresit before returning.

Added in version 3.12.