Debian Codegraph @

Doc/c-api/function.rst

raw
1 .. highlight:: c
2
3 .. _function-objects:
4
5 Function Objects
6 ----------------
7
8 .. index:: pair: object; function
9
10 There are a few functions specific to Python functions.
11
12
13 .. c:type:: PyFunctionObject
14
15 The C structure used for functions.
16
17
18 .. c:var:: PyTypeObject PyFunction_Type
19
20 .. index:: single: MethodType (in module types)
21
22 This is an instance of :c:type:`PyTypeObject` and represents the Python function
23 type. It is exposed to Python programmers as ``types.FunctionType``.
24
25
26 .. c:function:: int PyFunction_Check(PyObject *o)
27
28 Return true if *o* is a function object (has type :c:data:`PyFunction_Type`).
29 The parameter must not be ``NULL``. This function always succeeds.
30
31
32 .. c:function:: PyObject* PyFunction_New(PyObject *code, PyObject *globals)
33
34 Return a new function object associated with the code object *code*. *globals*
35 must be a dictionary with the global variables accessible to the function.
36
37 The function's docstring and name are retrieved from the code object.
38 :attr:`~function.__module__`
39 is retrieved from *globals*. The argument defaults, annotations and closure are
40 set to ``NULL``. :attr:`~function.__qualname__` is set to the same value as
41 the code object's :attr:`~codeobject.co_qualname` field.
42
43
44 .. c:function:: PyObject* PyFunction_NewWithQualName(PyObject *code, PyObject *globals, PyObject *qualname)
45
46 As :c:func:`PyFunction_New`, but also allows setting the function object's
47 :attr:`~function.__qualname__` attribute.
48 *qualname* should be a unicode object or ``NULL``;
49 if ``NULL``, the :attr:`!__qualname__` attribute is set to the same value as
50 the code object's :attr:`~codeobject.co_qualname` field.
51
52 .. versionadded:: 3.3
53
54
55 .. c:function:: PyObject* PyFunction_GetCode(PyObject *op)
56
57 Return the code object associated with the function object *op*.
58
59
60 .. c:function:: PyObject* PyFunction_GetGlobals(PyObject *op)
61
62 Return the globals dictionary associated with the function object *op*.
63
64
65 .. c:function:: PyObject* PyFunction_GetModule(PyObject *op)
66
67 Return a :term:`borrowed reference` to the :attr:`~function.__module__`
68 attribute of the :ref:`function object <user-defined-funcs>` *op*.
69 It can be *NULL*.
70
71 This is normally a :class:`string <str>` containing the module name,
72 but can be set to any other object by Python code.
73
74
75 .. c:function:: PyObject* PyFunction_GetDefaults(PyObject *op)
76
77 Return the argument default values of the function object *op*. This can be a
78 tuple of arguments or ``NULL``.
79
80
81 .. c:function:: int PyFunction_SetDefaults(PyObject *op, PyObject *defaults)
82
83 Set the argument default values for the function object *op*. *defaults* must be
84 ``Py_None`` or a tuple.
85
86 Raises :exc:`SystemError` and returns ``-1`` on failure.
87
88
89 .. c:function:: void PyFunction_SetVectorcall(PyFunctionObject *func, vectorcallfunc vectorcall)
90
91 Set the vectorcall field of a given function object *func*.
92
93 Warning: extensions using this API must preserve the behavior
94 of the unaltered (default) vectorcall function!
95
96 .. versionadded:: 3.12
97
98
99 .. c:function:: PyObject* PyFunction_GetKwDefaults(PyObject *op)
100
101 Return the keyword-only argument default values of the function object *op*. This can be a
102 dictionary of arguments or ``NULL``.
103
104
105 .. c:function:: int PyFunction_SetKwDefaults(PyObject *op, PyObject *defaults)
106
107 Set the keyword-only argument default values of the function object *op*.
108 *defaults* must be a dictionary of keyword-only arguments or ``Py_None``.
109
110 This function returns ``0`` on success, and returns ``-1`` with an exception
111 set on failure.
112
113
114 .. c:function:: PyObject* PyFunction_GetClosure(PyObject *op)
115
116 Return the closure associated with the function object *op*. This can be ``NULL``
117 or a tuple of cell objects.
118
119
120 .. c:function:: int PyFunction_SetClosure(PyObject *op, PyObject *closure)
121
122 Set the closure associated with the function object *op*. *closure* must be
123 ``Py_None`` or a tuple of cell objects.
124
125 Raises :exc:`SystemError` and returns ``-1`` on failure.
126
127
128 .. c:function:: PyObject *PyFunction_GetAnnotations(PyObject *op)
129
130 Return the annotations of the function object *op*. This can be a
131 mutable dictionary or ``NULL``.
132
133
134 .. c:function:: int PyFunction_SetAnnotations(PyObject *op, PyObject *annotations)
135
136 Set the annotations for the function object *op*. *annotations*
137 must be a dictionary or ``Py_None``.
138
139 Raises :exc:`SystemError` and returns ``-1`` on failure.
140
141
142 .. c:function:: PyObject *PyFunction_GET_CODE(PyObject *op)
143 PyObject *PyFunction_GET_GLOBALS(PyObject *op)
144 PyObject *PyFunction_GET_MODULE(PyObject *op)
145 PyObject *PyFunction_GET_DEFAULTS(PyObject *op)
146 PyObject *PyFunction_GET_KW_DEFAULTS(PyObject *op)
147 PyObject *PyFunction_GET_CLOSURE(PyObject *op)
148 PyObject *PyFunction_GET_ANNOTATIONS(PyObject *op)
149
150 These functions are similar to their ``PyFunction_Get*`` counterparts, but
151 do not do type checking. Passing anything other than an instance of
152 :c:data:`PyFunction_Type` is undefined behavior.
153
154
155 .. c:function:: int PyFunction_AddWatcher(PyFunction_WatchCallback callback)
156
157 Register *callback* as a function watcher for the current interpreter.
158 Return an ID which may be passed to :c:func:`PyFunction_ClearWatcher`.
159 In case of error (e.g. no more watcher IDs available),
160 return ``-1`` and set an exception.
161
162 .. versionadded:: 3.12
163
164
165 .. c:function:: int PyFunction_ClearWatcher(int watcher_id)
166
167 Clear watcher identified by *watcher_id* previously returned from
168 :c:func:`PyFunction_AddWatcher` for the current interpreter.
169 Return ``0`` on success, or ``-1`` and set an exception on error
170 (e.g. if the given *watcher_id* was never registered.)
171
172 .. versionadded:: 3.12
173
174
175 .. c:type:: PyFunction_WatchEvent
176
177 Enumeration of possible function watcher events:
178
179 - ``PyFunction_EVENT_CREATE``
180 - ``PyFunction_EVENT_DESTROY``
181 - ``PyFunction_EVENT_MODIFY_CODE``
182 - ``PyFunction_EVENT_MODIFY_DEFAULTS``
183 - ``PyFunction_EVENT_MODIFY_KWDEFAULTS``
184
185 .. versionadded:: 3.12
186
187
188 .. c:type:: int (*PyFunction_WatchCallback)(PyFunction_WatchEvent event, PyFunctionObject *func, PyObject *new_value)
189
190 Type of a function watcher callback function.
191
192 If *event* is ``PyFunction_EVENT_CREATE`` or ``PyFunction_EVENT_DESTROY``
193 then *new_value* will be ``NULL``. Otherwise, *new_value* will hold a
194 :term:`borrowed reference` to the new value that is about to be stored in
195 *func* for the attribute that is being modified.
196
197 The callback may inspect but must not modify *func*; doing so could have
198 unpredictable effects, including infinite recursion.
199
200 If *event* is ``PyFunction_EVENT_CREATE``, then the callback is invoked
201 after *func* has been fully initialized. Otherwise, the callback is invoked
202 before the modification to *func* takes place, so the prior state of *func*
203 can be inspected. The runtime is permitted to optimize away the creation of
204 function objects when possible. In such cases no event will be emitted.
205 Although this creates the possibility of an observable difference of
206 runtime behavior depending on optimization decisions, it does not change
207 the semantics of the Python code being executed.
208
209 If *event* is ``PyFunction_EVENT_DESTROY``, Taking a reference in the
210 callback to the about-to-be-destroyed function will resurrect it, preventing
211 it from being freed at this time. When the resurrected object is destroyed
212 later, any watcher callbacks active at that time will be called again.
213
214 If the callback sets an exception, it must return ``-1``; this exception will
215 be printed as an unraisable exception using :c:func:`PyErr_WriteUnraisable`.
216 Otherwise it should return ``0``.
217
218 There may already be a pending exception set on entry to the callback. In
219 this case, the callback should return ``0`` with the same exception still
220 set. This means the callback may not call any other API that can set an
221 exception unless it saves and clears the exception state first, and restores
222 it before returning.
223
224 .. versionadded:: 3.12