1.. highlight:: c
2
3.. _function-objects:
4
5Function Objects
6----------------
7
8.. index:: object: function
9
10There 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``.
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. *__module__*
38   is retrieved from *globals*. The argument defaults, annotations and closure are
39   set to ``NULL``. *__qualname__* is set to the same value as the function's name.
40
41
42.. c:function:: PyObject* PyFunction_NewWithQualName(PyObject *code, PyObject *globals, PyObject *qualname)
43
44   As :c:func:`PyFunction_New`, but also allows setting the function object's
45   ``__qualname__`` attribute.  *qualname* should be a unicode object or ``NULL``;
46   if ``NULL``, the ``__qualname__`` attribute is set to the same value as its
47   ``__name__`` attribute.
48
49   .. versionadded:: 3.3
50
51
52.. c:function:: PyObject* PyFunction_GetCode(PyObject *op)
53
54   Return the code object associated with the function object *op*.
55
56
57.. c:function:: PyObject* PyFunction_GetGlobals(PyObject *op)
58
59   Return the globals dictionary associated with the function object *op*.
60
61
62.. c:function:: PyObject* PyFunction_GetModule(PyObject *op)
63
64   Return the *__module__* attribute of the function object *op*. This is normally
65   a string containing the module name, but can be set to any other object by
66   Python code.
67
68
69.. c:function:: PyObject* PyFunction_GetDefaults(PyObject *op)
70
71   Return the argument default values of the function object *op*. This can be a
72   tuple of arguments or ``NULL``.
73
74
75.. c:function:: int PyFunction_SetDefaults(PyObject *op, PyObject *defaults)
76
77   Set the argument default values for the function object *op*. *defaults* must be
78   ``Py_None`` or a tuple.
79
80   Raises :exc:`SystemError` and returns ``-1`` on failure.
81
82
83.. c:function:: PyObject* PyFunction_GetClosure(PyObject *op)
84
85   Return the closure associated with the function object *op*. This can be ``NULL``
86   or a tuple of cell objects.
87
88
89.. c:function:: int PyFunction_SetClosure(PyObject *op, PyObject *closure)
90
91   Set the closure associated with the function object *op*. *closure* must be
92   ``Py_None`` or a tuple of cell objects.
93
94   Raises :exc:`SystemError` and returns ``-1`` on failure.
95
96
97.. c:function:: PyObject *PyFunction_GetAnnotations(PyObject *op)
98
99   Return the annotations of the function object *op*. This can be a
100   mutable dictionary or ``NULL``.
101
102
103.. c:function:: int PyFunction_SetAnnotations(PyObject *op, PyObject *annotations)
104
105   Set the annotations for the function object *op*. *annotations*
106   must be a dictionary or ``Py_None``.
107
108   Raises :exc:`SystemError` and returns ``-1`` on failure.
109