Mercurial > cpython-lru_cache-weakref

annotate Doc/c-api/object.rst @ 79675:c0a2294de787 2.7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Issue #16199: Backport 2to3 typo fix from 3.2.
author Chris Jerdonek <chris.jerdonek@gmail.com>
date Thu, 11 Oct 2012 16:15:46 -0700
parents 74ff71b2f53d
children 9b855a701e28
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
1 .. highlightlang:: c
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
2
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
3 .. _object:
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
4
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
5 Object Protocol
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
6 ===============
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
7
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
8
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
9 .. c:function:: int PyObject_Print(PyObject *o, FILE *fp, int flags)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
10
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
11 Print an object *o*, on file *fp*. Returns ``-1`` on error. The flags argument
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
12 is used to enable certain printing options. The only option currently supported
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
13 is :const:`Py_PRINT_RAW`; if given, the :func:`str` of the object is written
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
14 instead of the :func:`repr`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
15
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
16
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
17 .. c:function:: int PyObject_HasAttr(PyObject *o, PyObject *attr_name)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
18
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
19 Returns ``1`` if *o* has the attribute *attr_name*, and ``0`` otherwise. This
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
20 is equivalent to the Python expression ``hasattr(o, attr_name)``. This function
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
21 always succeeds.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
22
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
23
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
24 .. c:function:: int PyObject_HasAttrString(PyObject *o, const char *attr_name)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
25
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
26 Returns ``1`` if *o* has the attribute *attr_name*, and ``0`` otherwise. This
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
27 is equivalent to the Python expression ``hasattr(o, attr_name)``. This function
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
28 always succeeds.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
29
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
30
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
31 .. c:function:: PyObject* PyObject_GetAttr(PyObject *o, PyObject *attr_name)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
32
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
33 Retrieve an attribute named *attr_name* from object *o*. Returns the attribute
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
34 value on success, or *NULL* on failure. This is the equivalent of the Python
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
35 expression ``o.attr_name``.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
36
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
37
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
38 .. c:function:: PyObject* PyObject_GetAttrString(PyObject *o, const char *attr_name)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
39
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
40 Retrieve an attribute named *attr_name* from object *o*. Returns the attribute
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
41 value on success, or *NULL* on failure. This is the equivalent of the Python
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
42 expression ``o.attr_name``.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
43
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
44
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
45 .. c:function:: PyObject* PyObject_GenericGetAttr(PyObject *o, PyObject *name)
52898
fb2ea8bb3a33 Merged revisions 70642,70648,70656,70661,70765,70773,70789,70824-70825,70828,70830,70832,70836,70838,70842,70851,70855,70857-70858 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49355
diff changeset
46
fb2ea8bb3a33 Merged revisions 70642,70648,70656,70661,70765,70773,70789,70824-70825,70828,70830,70832,70836,70838,70842,70851,70855,70857-70858 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49355
diff changeset
47 Generic attribute getter function that is meant to be put into a type
fb2ea8bb3a33 Merged revisions 70642,70648,70656,70661,70765,70773,70789,70824-70825,70828,70830,70832,70836,70838,70842,70851,70855,70857-70858 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49355
diff changeset
48 object's ``tp_getattro`` slot. It looks for a descriptor in the dictionary
fb2ea8bb3a33 Merged revisions 70642,70648,70656,70661,70765,70773,70789,70824-70825,70828,70830,70832,70836,70838,70842,70851,70855,70857-70858 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49355
diff changeset
49 of classes in the object's MRO as well as an attribute in the object's
fb2ea8bb3a33 Merged revisions 70642,70648,70656,70661,70765,70773,70789,70824-70825,70828,70830,70832,70836,70838,70842,70851,70855,70857-70858 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49355
diff changeset
50 :attr:`__dict__` (if present). As outlined in :ref:`descriptors`, data
fb2ea8bb3a33 Merged revisions 70642,70648,70656,70661,70765,70773,70789,70824-70825,70828,70830,70832,70836,70838,70842,70851,70855,70857-70858 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49355
diff changeset
51 descriptors take preference over instance attributes, while non-data
fb2ea8bb3a33 Merged revisions 70642,70648,70656,70661,70765,70773,70789,70824-70825,70828,70830,70832,70836,70838,70842,70851,70855,70857-70858 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49355
diff changeset
52 descriptors don't. Otherwise, an :exc:`AttributeError` is raised.
fb2ea8bb3a33 Merged revisions 70642,70648,70656,70661,70765,70773,70789,70824-70825,70828,70830,70832,70836,70838,70842,70851,70855,70857-70858 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49355
diff changeset
53
fb2ea8bb3a33 Merged revisions 70642,70648,70656,70661,70765,70773,70789,70824-70825,70828,70830,70832,70836,70838,70842,70851,70855,70857-70858 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49355
diff changeset
54
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
55 .. c:function:: int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
56
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
57 Set the value of the attribute named *attr_name*, for object *o*, to the value
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
58 *v*. Returns ``-1`` on failure. This is the equivalent of the Python statement
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
59 ``o.attr_name = v``.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
60
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
61
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
62 .. c:function:: int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
63
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
64 Set the value of the attribute named *attr_name*, for object *o*, to the value
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
65 *v*. Returns ``-1`` on failure. This is the equivalent of the Python statement
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
66 ``o.attr_name = v``.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
67
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
68
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
69 .. c:function:: int PyObject_GenericSetAttr(PyObject *o, PyObject *name, PyObject *value)
52898
fb2ea8bb3a33 Merged revisions 70642,70648,70656,70661,70765,70773,70789,70824-70825,70828,70830,70832,70836,70838,70842,70851,70855,70857-70858 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49355
diff changeset
70
fb2ea8bb3a33 Merged revisions 70642,70648,70656,70661,70765,70773,70789,70824-70825,70828,70830,70832,70836,70838,70842,70851,70855,70857-70858 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49355
diff changeset
71 Generic attribute setter function that is meant to be put into a type
fb2ea8bb3a33 Merged revisions 70642,70648,70656,70661,70765,70773,70789,70824-70825,70828,70830,70832,70836,70838,70842,70851,70855,70857-70858 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49355
diff changeset
72 object's ``tp_setattro`` slot. It looks for a data descriptor in the
fb2ea8bb3a33 Merged revisions 70642,70648,70656,70661,70765,70773,70789,70824-70825,70828,70830,70832,70836,70838,70842,70851,70855,70857-70858 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49355
diff changeset
73 dictionary of classes in the object's MRO, and if found it takes preference
fb2ea8bb3a33 Merged revisions 70642,70648,70656,70661,70765,70773,70789,70824-70825,70828,70830,70832,70836,70838,70842,70851,70855,70857-70858 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49355
diff changeset
74 over setting the attribute in the instance dictionary. Otherwise, the
fb2ea8bb3a33 Merged revisions 70642,70648,70656,70661,70765,70773,70789,70824-70825,70828,70830,70832,70836,70838,70842,70851,70855,70857-70858 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49355
diff changeset
75 attribute is set in the object's :attr:`__dict__` (if present). Otherwise,
fb2ea8bb3a33 Merged revisions 70642,70648,70656,70661,70765,70773,70789,70824-70825,70828,70830,70832,70836,70838,70842,70851,70855,70857-70858 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49355
diff changeset
76 an :exc:`AttributeError` is raised and ``-1`` is returned.
fb2ea8bb3a33 Merged revisions 70642,70648,70656,70661,70765,70773,70789,70824-70825,70828,70830,70832,70836,70838,70842,70851,70855,70857-70858 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49355
diff changeset
77
fb2ea8bb3a33 Merged revisions 70642,70648,70656,70661,70765,70773,70789,70824-70825,70828,70830,70832,70836,70838,70842,70851,70855,70857-70858 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49355
diff changeset
78
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
79 .. c:function:: int PyObject_DelAttr(PyObject *o, PyObject *attr_name)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
80
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
81 Delete attribute named *attr_name*, for object *o*. Returns ``-1`` on failure.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
82 This is the equivalent of the Python statement ``del o.attr_name``.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
83
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
84
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
85 .. c:function:: int PyObject_DelAttrString(PyObject *o, const char *attr_name)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
86
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
87 Delete attribute named *attr_name*, for object *o*. Returns ``-1`` on failure.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
88 This is the equivalent of the Python statement ``del o.attr_name``.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
89
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
90
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
91 .. c:function:: PyObject* PyObject_RichCompare(PyObject *o1, PyObject *o2, int opid)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
92
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
93 Compare the values of *o1* and *o2* using the operation specified by *opid*,
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
94 which must be one of :const:`Py_LT`, :const:`Py_LE`, :const:`Py_EQ`,
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
95 :const:`Py_NE`, :const:`Py_GT`, or :const:`Py_GE`, corresponding to ``<``,
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
96 ``<=``, ``==``, ``!=``, ``>``, or ``>=`` respectively. This is the equivalent of
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
97 the Python expression ``o1 op o2``, where ``op`` is the operator corresponding
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
98 to *opid*. Returns the value of the comparison on success, or *NULL* on failure.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
99
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
100
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
101 .. c:function:: int PyObject_RichCompareBool(PyObject *o1, PyObject *o2, int opid)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
102
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
103 Compare the values of *o1* and *o2* using the operation specified by *opid*,
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
104 which must be one of :const:`Py_LT`, :const:`Py_LE`, :const:`Py_EQ`,
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
105 :const:`Py_NE`, :const:`Py_GT`, or :const:`Py_GE`, corresponding to ``<``,
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
106 ``<=``, ``==``, ``!=``, ``>``, or ``>=`` respectively. Returns ``-1`` on error,
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
107 ``0`` if the result is false, ``1`` otherwise. This is the equivalent of the
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
108 Python expression ``o1 op o2``, where ``op`` is the operator corresponding to
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
109 *opid*.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
110
69703
d27f95e3b52f Issue #10912: add clarification for PyObject_RichCompareBool comparing identical objects
Eli Bendersky <eliben@gmail.com>
parents: 53588
diff changeset
111 .. note::
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
112 If *o1* and *o2* are the same object, :c:func:`PyObject_RichCompareBool`
69703
d27f95e3b52f Issue #10912: add clarification for PyObject_RichCompareBool comparing identical objects
Eli Bendersky <eliben@gmail.com>
parents: 53588
diff changeset
113 will always return ``1`` for :const:`Py_EQ` and ``0`` for :const:`Py_NE`.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
114
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
115 .. c:function:: int PyObject_Cmp(PyObject *o1, PyObject *o2, int *result)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
116
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
117 .. index:: builtin: cmp
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
118
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
119 Compare the values of *o1* and *o2* using a routine provided by *o1*, if one
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
120 exists, otherwise with a routine provided by *o2*. The result of the comparison
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
121 is returned in *result*. Returns ``-1`` on failure. This is the equivalent of
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
122 the Python statement ``result = cmp(o1, o2)``.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
123
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
124
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
125 .. c:function:: int PyObject_Compare(PyObject *o1, PyObject *o2)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
126
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
127 .. index:: builtin: cmp
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
128
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
129 Compare the values of *o1* and *o2* using a routine provided by *o1*, if one
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
130 exists, otherwise with a routine provided by *o2*. Returns the result of the
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
131 comparison on success. On error, the value returned is undefined; use
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
132 :c:func:`PyErr_Occurred` to detect an error. This is equivalent to the Python
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
133 expression ``cmp(o1, o2)``.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
134
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
135
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
136 .. c:function:: PyObject* PyObject_Repr(PyObject *o)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
137
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
138 .. index:: builtin: repr
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
139
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
140 Compute a string representation of object *o*. Returns the string
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
141 representation on success, *NULL* on failure. This is the equivalent of the
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
142 Python expression ``repr(o)``. Called by the :func:`repr` built-in function and
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
143 by reverse quotes.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
144
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
145
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
146 .. c:function:: PyObject* PyObject_Str(PyObject *o)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
147
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
148 .. index:: builtin: str
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
149
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
150 Compute a string representation of object *o*. Returns the string
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
151 representation on success, *NULL* on failure. This is the equivalent of the
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
152 Python expression ``str(o)``. Called by the :func:`str` built-in function and
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
153 by the :keyword:`print` statement.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
154
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
155
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
156 .. c:function:: PyObject* PyObject_Bytes(PyObject *o)
48872
edd2ca894a67 sort of backport 66038 by aliasing PyObject_Bytes to PyObject_Str
Benjamin Peterson <benjamin@python.org>
parents: 48285
diff changeset
157
edd2ca894a67 sort of backport 66038 by aliasing PyObject_Bytes to PyObject_Str
Benjamin Peterson <benjamin@python.org>
parents: 48285
diff changeset
158 .. index:: builtin: bytes
edd2ca894a67 sort of backport 66038 by aliasing PyObject_Bytes to PyObject_Str
Benjamin Peterson <benjamin@python.org>
parents: 48285
diff changeset
159
edd2ca894a67 sort of backport 66038 by aliasing PyObject_Bytes to PyObject_Str
Benjamin Peterson <benjamin@python.org>
parents: 48285
diff changeset
160 Compute a bytes representation of object *o*. In 2.x, this is just a alias
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
161 for :c:func:`PyObject_Str`.
48872
edd2ca894a67 sort of backport 66038 by aliasing PyObject_Bytes to PyObject_Str
Benjamin Peterson <benjamin@python.org>
parents: 48285
diff changeset
162
edd2ca894a67 sort of backport 66038 by aliasing PyObject_Bytes to PyObject_Str
Benjamin Peterson <benjamin@python.org>
parents: 48285
diff changeset
163
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
164 .. c:function:: PyObject* PyObject_Unicode(PyObject *o)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
165
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
166 .. index:: builtin: unicode
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
167
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
168 Compute a Unicode string representation of object *o*. Returns the Unicode
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
169 string representation on success, *NULL* on failure. This is the equivalent of
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
170 the Python expression ``unicode(o)``. Called by the :func:`unicode` built-in
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
171 function.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
172
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
173
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
174 .. c:function:: int PyObject_IsInstance(PyObject *inst, PyObject *cls)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
175
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
176 Returns ``1`` if *inst* is an instance of the class *cls* or a subclass of
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
177 *cls*, or ``0`` if not. On error, returns ``-1`` and sets an exception. If
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
178 *cls* is a type object rather than a class object, :c:func:`PyObject_IsInstance`
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
179 returns ``1`` if *inst* is of type *cls*. If *cls* is a tuple, the check will
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
180 be done against every entry in *cls*. The result will be ``1`` when at least one
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
181 of the checks returns ``1``, otherwise it will be ``0``. If *inst* is not a
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
182 class instance and *cls* is neither a type object, nor a class object, nor a
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
183 tuple, *inst* must have a :attr:`__class__` attribute --- the class relationship
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
184 of the value of that attribute with *cls* will be used to determine the result
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
185 of this function.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
186
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
187 .. versionadded:: 2.1
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
188
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
189 .. versionchanged:: 2.2
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
190 Support for a tuple as the second argument added.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
191
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
192 Subclass determination is done in a fairly straightforward way, but includes a
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
193 wrinkle that implementors of extensions to the class system may want to be aware
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
194 of. If :class:`A` and :class:`B` are class objects, :class:`B` is a subclass of
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
195 :class:`A` if it inherits from :class:`A` either directly or indirectly. If
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
196 either is not a class object, a more general mechanism is used to determine the
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
197 class relationship of the two objects. When testing if *B* is a subclass of
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
198 *A*, if *A* is *B*, :c:func:`PyObject_IsSubclass` returns true. If *A* and *B*
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
199 are different objects, *B*'s :attr:`__bases__` attribute is searched in a
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
200 depth-first fashion for *A* --- the presence of the :attr:`__bases__` attribute
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
201 is considered sufficient for this determination.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
202
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
203
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
204 .. c:function:: int PyObject_IsSubclass(PyObject *derived, PyObject *cls)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
205
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
206 Returns ``1`` if the class *derived* is identical to or derived from the class
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
207 *cls*, otherwise returns ``0``. In case of an error, returns ``-1``. If *cls*
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
208 is a tuple, the check will be done against every entry in *cls*. The result will
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
209 be ``1`` when at least one of the checks returns ``1``, otherwise it will be
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
210 ``0``. If either *derived* or *cls* is not an actual class object (or tuple),
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
211 this function uses the generic algorithm described above.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
212
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
213 .. versionadded:: 2.1
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
214
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
215 .. versionchanged:: 2.3
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
216 Older versions of Python did not support a tuple as the second argument.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
217
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
218
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
219 .. c:function:: int PyCallable_Check(PyObject *o)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
220
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
221 Determine if the object *o* is callable. Return ``1`` if the object is callable
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
222 and ``0`` otherwise. This function always succeeds.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
223
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
224
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
225 .. c:function:: PyObject* PyObject_Call(PyObject *callable_object, PyObject *args, PyObject *kw)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
226
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
227 .. index:: builtin: apply
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
228
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
229 Call a callable Python object *callable_object*, with arguments given by the
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
230 tuple *args*, and named arguments given by the dictionary *kw*. If no named
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
231 arguments are needed, *kw* may be *NULL*. *args* must not be *NULL*, use an
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
232 empty tuple if no arguments are needed. Returns the result of the call on
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
233 success, or *NULL* on failure. This is the equivalent of the Python expression
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
234 ``apply(callable_object, args, kw)`` or ``callable_object(*args, **kw)``.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
235
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
236 .. versionadded:: 2.2
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
237
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
238
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
239 .. c:function:: PyObject* PyObject_CallObject(PyObject *callable_object, PyObject *args)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
240
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
241 .. index:: builtin: apply
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
242
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
243 Call a callable Python object *callable_object*, with arguments given by the
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
244 tuple *args*. If no arguments are needed, then *args* may be *NULL*. Returns
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
245 the result of the call on success, or *NULL* on failure. This is the equivalent
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
246 of the Python expression ``apply(callable_object, args)`` or
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
247 ``callable_object(*args)``.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
248
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
249
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
250 .. c:function:: PyObject* PyObject_CallFunction(PyObject *callable, char *format, ...)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
251
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
252 .. index:: builtin: apply
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
253
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
254 Call a callable Python object *callable*, with a variable number of C arguments.
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
255 The C arguments are described using a :c:func:`Py_BuildValue` style format
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
256 string. The format may be *NULL*, indicating that no arguments are provided.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
257 Returns the result of the call on success, or *NULL* on failure. This is the
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
258 equivalent of the Python expression ``apply(callable, args)`` or
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
259 ``callable(*args)``. Note that if you only pass :c:type:`PyObject \*` args,
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
260 :c:func:`PyObject_CallFunctionObjArgs` is a faster alternative.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
261
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
262
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
263 .. c:function:: PyObject* PyObject_CallMethod(PyObject *o, char *method, char *format, ...)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
264
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
265 Call the method named *method* of object *o* with a variable number of C
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
266 arguments. The C arguments are described by a :c:func:`Py_BuildValue` format
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
267 string that should produce a tuple. The format may be *NULL*, indicating that
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
268 no arguments are provided. Returns the result of the call on success, or *NULL*
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
269 on failure. This is the equivalent of the Python expression ``o.method(args)``.
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
270 Note that if you only pass :c:type:`PyObject \*` args,
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
271 :c:func:`PyObject_CallMethodObjArgs` is a faster alternative.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
272
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
273
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
274 .. c:function:: PyObject* PyObject_CallFunctionObjArgs(PyObject *callable, ..., NULL)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
275
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
276 Call a callable Python object *callable*, with a variable number of
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
277 :c:type:`PyObject\*` arguments. The arguments are provided as a variable number
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
278 of parameters followed by *NULL*. Returns the result of the call on success, or
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
279 *NULL* on failure.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
280
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
281 .. versionadded:: 2.2
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
282
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
283
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
284 .. c:function:: PyObject* PyObject_CallMethodObjArgs(PyObject *o, PyObject *name, ..., NULL)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
285
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
286 Calls a method of the object *o*, where the name of the method is given as a
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
287 Python string object in *name*. It is called with a variable number of
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
288 :c:type:`PyObject\*` arguments. The arguments are provided as a variable number
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
289 of parameters followed by *NULL*. Returns the result of the call on success, or
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
290 *NULL* on failure.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
291
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
292 .. versionadded:: 2.2
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
293
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
294
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
295 .. c:function:: long PyObject_Hash(PyObject *o)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
296
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
297 .. index:: builtin: hash
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
298
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
299 Compute and return the hash value of an object *o*. On failure, return ``-1``.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
300 This is the equivalent of the Python expression ``hash(o)``.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
301
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
302
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
303 .. c:function:: long PyObject_HashNotImplemented(PyObject *o)
48284
2254aa824d4d Issue 2235: document PyObject_HashNotImplemented
Nick Coghlan <ncoghlan@gmail.com>
parents: 44796
diff changeset
304
49355
6ceacd015d67 Markup fix
Andrew M. Kuchling <amk@amk.ca>
parents: 48872
diff changeset
305 Set a :exc:`TypeError` indicating that ``type(o)`` is not hashable and return ``-1``.
48284
2254aa824d4d Issue 2235: document PyObject_HashNotImplemented
Nick Coghlan <ncoghlan@gmail.com>
parents: 44796
diff changeset
306 This function receives special treatment when stored in a ``tp_hash`` slot,
48285
4207219acc7a Fix typo
Nick Coghlan <ncoghlan@gmail.com>
parents: 48284
diff changeset
307 allowing a type to explicitly indicate to the interpreter that it is not
48284
2254aa824d4d Issue 2235: document PyObject_HashNotImplemented
Nick Coghlan <ncoghlan@gmail.com>
parents: 44796
diff changeset
308 hashable.
2254aa824d4d Issue 2235: document PyObject_HashNotImplemented
Nick Coghlan <ncoghlan@gmail.com>
parents: 44796
diff changeset
309
2254aa824d4d Issue 2235: document PyObject_HashNotImplemented
Nick Coghlan <ncoghlan@gmail.com>
parents: 44796
diff changeset
310 .. versionadded:: 2.6
2254aa824d4d Issue 2235: document PyObject_HashNotImplemented
Nick Coghlan <ncoghlan@gmail.com>
parents: 44796
diff changeset
311
2254aa824d4d Issue 2235: document PyObject_HashNotImplemented
Nick Coghlan <ncoghlan@gmail.com>
parents: 44796
diff changeset
312
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
313 .. c:function:: int PyObject_IsTrue(PyObject *o)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
314
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
315 Returns ``1`` if the object *o* is considered to be true, and ``0`` otherwise.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
316 This is equivalent to the Python expression ``not not o``. On failure, return
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
317 ``-1``.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
318
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
319
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
320 .. c:function:: int PyObject_Not(PyObject *o)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
321
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
322 Returns ``0`` if the object *o* is considered to be true, and ``1`` otherwise.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
323 This is equivalent to the Python expression ``not o``. On failure, return
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
324 ``-1``.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
325
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
326
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
327 .. c:function:: PyObject* PyObject_Type(PyObject *o)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
328
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
329 .. index:: builtin: type
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
330
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
331 When *o* is non-*NULL*, returns a type object corresponding to the object type
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
332 of object *o*. On failure, raises :exc:`SystemError` and returns *NULL*. This
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
333 is equivalent to the Python expression ``type(o)``. This function increments the
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
334 reference count of the return value. There's really no reason to use this
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
335 function instead of the common expression ``o->ob_type``, which returns a
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
336 pointer of type :c:type:`PyTypeObject\*`, except when the incremented reference
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
337 count is needed.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
338
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
339
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
340 .. c:function:: int PyObject_TypeCheck(PyObject *o, PyTypeObject *type)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
341
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
342 Return true if the object *o* is of type *type* or a subtype of *type*. Both
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
343 parameters must be non-*NULL*.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
344
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
345 .. versionadded:: 2.2
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
346
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
347
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
348 .. c:function:: Py_ssize_t PyObject_Length(PyObject *o)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
349 Py_ssize_t PyObject_Size(PyObject *o)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
350
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
351 .. index:: builtin: len
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
352
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
353 Return the length of object *o*. If the object *o* provides either the sequence
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
354 and mapping protocols, the sequence length is returned. On error, ``-1`` is
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
355 returned. This is the equivalent to the Python expression ``len(o)``.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
356
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 52927
diff changeset
357 .. versionchanged:: 2.5
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
358 These functions returned an :c:type:`int` type. This might require
53588
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 52927
diff changeset
359 changes in your code for properly supporting 64-bit systems.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 52927
diff changeset
360
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
361
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
362 .. c:function:: PyObject* PyObject_GetItem(PyObject *o, PyObject *key)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
363
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
364 Return element of *o* corresponding to the object *key* or *NULL* on failure.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
365 This is the equivalent of the Python expression ``o[key]``.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
366
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
367
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
368 .. c:function:: int PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
369
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
370 Map the object *key* to the value *v*. Returns ``-1`` on failure. This is the
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
371 equivalent of the Python statement ``o[key] = v``.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
372
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
373
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
374 .. c:function:: int PyObject_DelItem(PyObject *o, PyObject *key)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
375
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
376 Delete the mapping for *key* from *o*. Returns ``-1`` on failure. This is the
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
377 equivalent of the Python statement ``del o[key]``.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
378
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
379
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
380 .. c:function:: int PyObject_AsFileDescriptor(PyObject *o)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
381
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
382 Derives a file descriptor from a Python object. If the object is an integer or
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
383 long integer, its value is returned. If not, the object's :meth:`fileno` method
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
384 is called if it exists; the method must return an integer or long integer, which
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
385 is returned as the file descriptor value. Returns ``-1`` on failure.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
386
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
387
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
388 .. c:function:: PyObject* PyObject_Dir(PyObject *o)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
389
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
390 This is equivalent to the Python expression ``dir(o)``, returning a (possibly
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
391 empty) list of strings appropriate for the object argument, or *NULL* if there
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
392 was an error. If the argument is *NULL*, this is like the Python ``dir()``,
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
393 returning the names of the current locals; in this case, if no execution frame
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
394 is active then *NULL* is returned but :c:func:`PyErr_Occurred` will return false.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
395
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
396
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 69704
diff changeset
397 .. c:function:: PyObject* PyObject_GetIter(PyObject *o)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
398
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
399 This is equivalent to the Python expression ``iter(o)``. It returns a new
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
400 iterator for the object argument, or the object itself if the object is already
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
401 an iterator. Raises :exc:`TypeError` and returns *NULL* if the object cannot be
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
402 iterated.