Mercurial > cpython-lru_cache-weakref

annotate Doc/c-api/function.rst @ 74006:88198b93ff2f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Issue #13560: Add PyUnicode_EncodeLocale() * Use PyUnicode_EncodeLocale() in time.strftime() if wcsftime() is not available * Document my last changes in Misc/NEWS
author Victor Stinner <victor.stinner@haypocalc.com>
date Sat, 17 Dec 2011 04:13:41 +0100
parents e1dbc72bd97f
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
1 .. highlightlang:: c
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
2
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
3 .. _function-objects:
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
4
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
5 Function Objects
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
6 ----------------
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
7
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
8 .. index:: object: function
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
9
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
10 There are a few functions specific to Python functions.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
11
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
12
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 48466
diff changeset
13 .. c:type:: PyFunctionObject
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
14
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
15 The C structure used for functions.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
16
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
17
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 48466
diff changeset
18 .. c:var:: PyTypeObject PyFunction_Type
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
19
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
20 .. index:: single: MethodType (in module types)
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
21
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 48466
diff changeset
22 This is an instance of :c:type:`PyTypeObject` and represents the Python function
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
23 type. It is exposed to Python programmers as ``types.FunctionType``.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
24
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
25
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 48466
diff changeset
26 .. c:function:: int PyFunction_Check(PyObject *o)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
27
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 48466
diff changeset
28 Return true if *o* is a function object (has type :c:data:`PyFunction_Type`).
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
29 The parameter must not be *NULL*.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
30
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
31
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 48466
diff changeset
32 .. c:function:: PyObject* PyFunction_New(PyObject *code, PyObject *globals)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
33
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
34 Return a new function object associated with the code object *code*. *globals*
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
35 must be a dictionary with the global variables accessible to the function.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
36
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
37 The function's docstring, name and *__module__* are retrieved from the code
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
38 object, the argument defaults and closure are set to *NULL*.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
39
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
40
73738
e1dbc72bd97f PEP 3155 / issue #13448: Qualified name for classes and functions.
Antoine Pitrou <solipsis@pitrou.net>
parents: 65137
diff changeset
41 .. c:function:: PyObject* PyFunction_NewWithQualName(PyObject *code, PyObject *globals, PyObject *qualname)
e1dbc72bd97f PEP 3155 / issue #13448: Qualified name for classes and functions.
Antoine Pitrou <solipsis@pitrou.net>
parents: 65137
diff changeset
42
e1dbc72bd97f PEP 3155 / issue #13448: Qualified name for classes and functions.
Antoine Pitrou <solipsis@pitrou.net>
parents: 65137
diff changeset
43 As :c:func:`PyFunction_New`, but also allows to set the function object's
e1dbc72bd97f PEP 3155 / issue #13448: Qualified name for classes and functions.
Antoine Pitrou <solipsis@pitrou.net>
parents: 65137
diff changeset
44 ``__qualname__`` attribute. *qualname* should be a unicode object or NULL;
e1dbc72bd97f PEP 3155 / issue #13448: Qualified name for classes and functions.
Antoine Pitrou <solipsis@pitrou.net>
parents: 65137
diff changeset
45 if NULL, the ``__qualname__`` attribute is set to the same value as its
e1dbc72bd97f PEP 3155 / issue #13448: Qualified name for classes and functions.
Antoine Pitrou <solipsis@pitrou.net>
parents: 65137
diff changeset
46 ``__name__`` attribute.
e1dbc72bd97f PEP 3155 / issue #13448: Qualified name for classes and functions.
Antoine Pitrou <solipsis@pitrou.net>
parents: 65137
diff changeset
47
e1dbc72bd97f PEP 3155 / issue #13448: Qualified name for classes and functions.
Antoine Pitrou <solipsis@pitrou.net>
parents: 65137
diff changeset
48 .. versionadded:: 3.3
e1dbc72bd97f PEP 3155 / issue #13448: Qualified name for classes and functions.
Antoine Pitrou <solipsis@pitrou.net>
parents: 65137
diff changeset
49
e1dbc72bd97f PEP 3155 / issue #13448: Qualified name for classes and functions.
Antoine Pitrou <solipsis@pitrou.net>
parents: 65137
diff changeset
50
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 48466
diff changeset
51 .. c:function:: PyObject* PyFunction_GetCode(PyObject *op)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
52
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
53 Return the code object associated with the function object *op*.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
54
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
55
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 48466
diff changeset
56 .. c:function:: PyObject* PyFunction_GetGlobals(PyObject *op)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
57
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
58 Return the globals dictionary associated with the function object *op*.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
59
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
60
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 48466
diff changeset
61 .. c:function:: PyObject* PyFunction_GetModule(PyObject *op)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
62
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
63 Return the *__module__* attribute of the function object *op*. This is normally
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
64 a string containing the module name, but can be set to any other object by
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
65 Python code.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
66
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
67
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 48466
diff changeset
68 .. c:function:: PyObject* PyFunction_GetDefaults(PyObject *op)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
69
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
70 Return the argument default values of the function object *op*. This can be a
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
71 tuple of arguments or *NULL*.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
72
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
73
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 48466
diff changeset
74 .. c:function:: int PyFunction_SetDefaults(PyObject *op, PyObject *defaults)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
75
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
76 Set the argument default values for the function object *op*. *defaults* must be
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
77 *Py_None* or a tuple.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
78
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
79 Raises :exc:`SystemError` and returns ``-1`` on failure.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
80
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
81
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 48466
diff changeset
82 .. c:function:: PyObject* PyFunction_GetClosure(PyObject *op)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
83
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
84 Return the closure associated with the function object *op*. This can be *NULL*
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
85 or a tuple of cell objects.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
86
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
87
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 48466
diff changeset
88 .. c:function:: int PyFunction_SetClosure(PyObject *op, PyObject *closure)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
89
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
90 Set the closure associated with the function object *op*. *closure* must be
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
91 *Py_None* or a tuple of cell objects.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
92
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
93 Raises :exc:`SystemError` and returns ``-1`` on failure.
48465
be3d3106da6f Added documentation for PyFunction_GetAnnotations() and
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 44812
diff changeset
94
be3d3106da6f Added documentation for PyFunction_GetAnnotations() and
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 44812
diff changeset
95
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 48466
diff changeset
96 .. c:function:: PyObject *PyFunction_GetAnnotations(PyObject *op)
48465
be3d3106da6f Added documentation for PyFunction_GetAnnotations() and
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 44812
diff changeset
97
be3d3106da6f Added documentation for PyFunction_GetAnnotations() and
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 44812
diff changeset
98 Return the annotations of the function object *op*. This can be a
be3d3106da6f Added documentation for PyFunction_GetAnnotations() and
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 44812
diff changeset
99 mutable dictionary or *NULL*.
be3d3106da6f Added documentation for PyFunction_GetAnnotations() and
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 44812
diff changeset
100
be3d3106da6f Added documentation for PyFunction_GetAnnotations() and
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 44812
diff changeset
101
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 48466
diff changeset
102 .. c:function:: int PyFunction_SetAnnotations(PyObject *op, PyObject *annotations)
48465
be3d3106da6f Added documentation for PyFunction_GetAnnotations() and
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 44812
diff changeset
103
be3d3106da6f Added documentation for PyFunction_GetAnnotations() and
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 44812
diff changeset
104 Set the annotations for the function object *op*. *annotations*
be3d3106da6f Added documentation for PyFunction_GetAnnotations() and
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 44812
diff changeset
105 must be a dictionary or *Py_None*.
48466
afdd64edf189 Mention the behaviour of PyFunction_SetAnnotations() on error.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 48465
diff changeset
106
afdd64edf189 Mention the behaviour of PyFunction_SetAnnotations() on error.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 48465
diff changeset
107 Raises :exc:`SystemError` and returns ``-1`` on failure.