Mercurial > cpython-lru_cache-weakref

annotate Doc/c-api/function.rst @ 87690:66c1c9f32567 default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add use_weakref option to functools.lru_cache The use_weakref option makes lru_cache create weak references to the function arguments when creating the cache key, which prevents them from staying in the memory forever even after all other references to them are gone. This is a proof of concept for http://bugs.python.org/issue19859
author Radomir Dopieralski <devel@sheep.art.pl>
date Tue, 03 Dec 2013 16:02:48 +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.