Mercurial > cpython-lru_cache-weakref

annotate Doc/c-api/object.rst @ 78069:a8aa77458e12 3.2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add c_size_t and c_ssize_t to the ctypes summary table.
author Antoine Pitrou <solipsis@pitrou.net>
date Thu, 12 Jul 2012 20:31:50 +0200
parents 316a8f4d6617
children e88362fb4950
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 .. _object:
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 Object Protocol
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
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
9 .. c:function:: int PyObject_Print(PyObject *o, FILE *fp, int flags)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
10
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
11 Print an object *o*, on file *fp*. Returns ``-1`` on error. The flags argument
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
12 is used to enable certain printing options. The only option currently supported
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
13 is :const:`Py_PRINT_RAW`; if given, the :func:`str` of the object is written
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
14 instead of the :func:`repr`.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
15
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
16
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
17 .. c:function:: int PyObject_HasAttr(PyObject *o, PyObject *attr_name)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
18
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
19 Returns ``1`` if *o* has the attribute *attr_name*, and ``0`` otherwise. This
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
20 is equivalent to the Python expression ``hasattr(o, attr_name)``. This function
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
21 always succeeds.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
22
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
23
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
24 .. c:function:: int PyObject_HasAttrString(PyObject *o, const char *attr_name)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
25
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
26 Returns ``1`` if *o* has the attribute *attr_name*, and ``0`` otherwise. This
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
27 is equivalent to the Python expression ``hasattr(o, attr_name)``. This function
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
28 always succeeds.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
29
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
30
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
31 .. c:function:: PyObject* PyObject_GetAttr(PyObject *o, PyObject *attr_name)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
32
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
33 Retrieve an attribute named *attr_name* from object *o*. Returns the attribute
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
34 value on success, or *NULL* on failure. This is the equivalent of the Python
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
35 expression ``o.attr_name``.
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
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
38 .. c:function:: PyObject* PyObject_GetAttrString(PyObject *o, const char *attr_name)
44812
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 Retrieve an attribute named *attr_name* from object *o*. Returns the attribute
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
41 value on success, or *NULL* on failure. This is the equivalent of the Python
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
42 expression ``o.attr_name``.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
43
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
44
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
45 .. c:function:: PyObject* PyObject_GenericGetAttr(PyObject *o, PyObject *name)
52892
792bb885029f Merged revisions 70712,70714,70764-70765,70769-70771,70773,70776-70777,70788-70789,70824,70828,70832,70836,70842,70851,70855,70857,70866-70872,70883,70885,70893-70894,70896-70897,70903,70905-70907,70915,70927,70933,70951,70960,70962-70964,70998,71001,71006,71008,71010-71011,71019,71037,71056,71094,71101-71103,71106,71119,71123,71149-71150,71203,71212,71214-71217,71221,71240 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 51246
diff changeset
46
792bb885029f Merged revisions 70712,70714,70764-70765,70769-70771,70773,70776-70777,70788-70789,70824,70828,70832,70836,70842,70851,70855,70857,70866-70872,70883,70885,70893-70894,70896-70897,70903,70905-70907,70915,70927,70933,70951,70960,70962-70964,70998,71001,71006,71008,71010-71011,71019,71037,71056,71094,71101-71103,71106,71119,71123,71149-71150,71203,71212,71214-71217,71221,71240 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 51246
diff changeset
47 Generic attribute getter function that is meant to be put into a type
792bb885029f Merged revisions 70712,70714,70764-70765,70769-70771,70773,70776-70777,70788-70789,70824,70828,70832,70836,70842,70851,70855,70857,70866-70872,70883,70885,70893-70894,70896-70897,70903,70905-70907,70915,70927,70933,70951,70960,70962-70964,70998,71001,71006,71008,71010-71011,71019,71037,71056,71094,71101-71103,71106,71119,71123,71149-71150,71203,71212,71214-71217,71221,71240 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 51246
diff changeset
48 object's ``tp_getattro`` slot. It looks for a descriptor in the dictionary
792bb885029f Merged revisions 70712,70714,70764-70765,70769-70771,70773,70776-70777,70788-70789,70824,70828,70832,70836,70842,70851,70855,70857,70866-70872,70883,70885,70893-70894,70896-70897,70903,70905-70907,70915,70927,70933,70951,70960,70962-70964,70998,71001,71006,71008,71010-71011,71019,71037,71056,71094,71101-71103,71106,71119,71123,71149-71150,71203,71212,71214-71217,71221,71240 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 51246
diff changeset
49 of classes in the object's MRO as well as an attribute in the object's
792bb885029f Merged revisions 70712,70714,70764-70765,70769-70771,70773,70776-70777,70788-70789,70824,70828,70832,70836,70842,70851,70855,70857,70866-70872,70883,70885,70893-70894,70896-70897,70903,70905-70907,70915,70927,70933,70951,70960,70962-70964,70998,71001,71006,71008,71010-71011,71019,71037,71056,71094,71101-71103,71106,71119,71123,71149-71150,71203,71212,71214-71217,71221,71240 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 51246
diff changeset
50 :attr:`__dict__` (if present). As outlined in :ref:`descriptors`, data
792bb885029f Merged revisions 70712,70714,70764-70765,70769-70771,70773,70776-70777,70788-70789,70824,70828,70832,70836,70842,70851,70855,70857,70866-70872,70883,70885,70893-70894,70896-70897,70903,70905-70907,70915,70927,70933,70951,70960,70962-70964,70998,71001,71006,71008,71010-71011,71019,71037,71056,71094,71101-71103,71106,71119,71123,71149-71150,71203,71212,71214-71217,71221,71240 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 51246
diff changeset
51 descriptors take preference over instance attributes, while non-data
792bb885029f Merged revisions 70712,70714,70764-70765,70769-70771,70773,70776-70777,70788-70789,70824,70828,70832,70836,70842,70851,70855,70857,70866-70872,70883,70885,70893-70894,70896-70897,70903,70905-70907,70915,70927,70933,70951,70960,70962-70964,70998,71001,71006,71008,71010-71011,71019,71037,71056,71094,71101-71103,71106,71119,71123,71149-71150,71203,71212,71214-71217,71221,71240 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 51246
diff changeset
52 descriptors don't. Otherwise, an :exc:`AttributeError` is raised.
792bb885029f Merged revisions 70712,70714,70764-70765,70769-70771,70773,70776-70777,70788-70789,70824,70828,70832,70836,70842,70851,70855,70857,70866-70872,70883,70885,70893-70894,70896-70897,70903,70905-70907,70915,70927,70933,70951,70960,70962-70964,70998,71001,71006,71008,71010-71011,71019,71037,71056,71094,71101-71103,71106,71119,71123,71149-71150,71203,71212,71214-71217,71221,71240 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 51246
diff changeset
53
792bb885029f Merged revisions 70712,70714,70764-70765,70769-70771,70773,70776-70777,70788-70789,70824,70828,70832,70836,70842,70851,70855,70857,70866-70872,70883,70885,70893-70894,70896-70897,70903,70905-70907,70915,70927,70933,70951,70960,70962-70964,70998,71001,71006,71008,71010-71011,71019,71037,71056,71094,71101-71103,71106,71119,71123,71149-71150,71203,71212,71214-71217,71221,71240 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 51246
diff changeset
54
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
55 .. c:function:: int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
56
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
57 Set the value of the attribute named *attr_name*, for object *o*, to the value
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
58 *v*. Returns ``-1`` on failure. This is the equivalent of the Python statement
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
59 ``o.attr_name = v``.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
60
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
61
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
62 .. c:function:: int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
63
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
64 Set the value of the attribute named *attr_name*, for object *o*, to the value
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
65 *v*. Returns ``-1`` on failure. This is the equivalent of the Python statement
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
66 ``o.attr_name = v``.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
67
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
68
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
69 .. c:function:: int PyObject_GenericSetAttr(PyObject *o, PyObject *name, PyObject *value)
52892
792bb885029f Merged revisions 70712,70714,70764-70765,70769-70771,70773,70776-70777,70788-70789,70824,70828,70832,70836,70842,70851,70855,70857,70866-70872,70883,70885,70893-70894,70896-70897,70903,70905-70907,70915,70927,70933,70951,70960,70962-70964,70998,71001,71006,71008,71010-71011,71019,71037,71056,71094,71101-71103,71106,71119,71123,71149-71150,71203,71212,71214-71217,71221,71240 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 51246
diff changeset
70
792bb885029f Merged revisions 70712,70714,70764-70765,70769-70771,70773,70776-70777,70788-70789,70824,70828,70832,70836,70842,70851,70855,70857,70866-70872,70883,70885,70893-70894,70896-70897,70903,70905-70907,70915,70927,70933,70951,70960,70962-70964,70998,71001,71006,71008,71010-71011,71019,71037,71056,71094,71101-71103,71106,71119,71123,71149-71150,71203,71212,71214-71217,71221,71240 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 51246
diff changeset
71 Generic attribute setter function that is meant to be put into a type
792bb885029f Merged revisions 70712,70714,70764-70765,70769-70771,70773,70776-70777,70788-70789,70824,70828,70832,70836,70842,70851,70855,70857,70866-70872,70883,70885,70893-70894,70896-70897,70903,70905-70907,70915,70927,70933,70951,70960,70962-70964,70998,71001,71006,71008,71010-71011,71019,71037,71056,71094,71101-71103,71106,71119,71123,71149-71150,71203,71212,71214-71217,71221,71240 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 51246
diff changeset
72 object's ``tp_setattro`` slot. It looks for a data descriptor in the
792bb885029f Merged revisions 70712,70714,70764-70765,70769-70771,70773,70776-70777,70788-70789,70824,70828,70832,70836,70842,70851,70855,70857,70866-70872,70883,70885,70893-70894,70896-70897,70903,70905-70907,70915,70927,70933,70951,70960,70962-70964,70998,71001,71006,71008,71010-71011,71019,71037,71056,71094,71101-71103,71106,71119,71123,71149-71150,71203,71212,71214-71217,71221,71240 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 51246
diff changeset
73 dictionary of classes in the object's MRO, and if found it takes preference
792bb885029f Merged revisions 70712,70714,70764-70765,70769-70771,70773,70776-70777,70788-70789,70824,70828,70832,70836,70842,70851,70855,70857,70866-70872,70883,70885,70893-70894,70896-70897,70903,70905-70907,70915,70927,70933,70951,70960,70962-70964,70998,71001,71006,71008,71010-71011,71019,71037,71056,71094,71101-71103,71106,71119,71123,71149-71150,71203,71212,71214-71217,71221,71240 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 51246
diff changeset
74 over setting the attribute in the instance dictionary. Otherwise, the
792bb885029f Merged revisions 70712,70714,70764-70765,70769-70771,70773,70776-70777,70788-70789,70824,70828,70832,70836,70842,70851,70855,70857,70866-70872,70883,70885,70893-70894,70896-70897,70903,70905-70907,70915,70927,70933,70951,70960,70962-70964,70998,71001,71006,71008,71010-71011,71019,71037,71056,71094,71101-71103,71106,71119,71123,71149-71150,71203,71212,71214-71217,71221,71240 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 51246
diff changeset
75 attribute is set in the object's :attr:`__dict__` (if present). Otherwise,
792bb885029f Merged revisions 70712,70714,70764-70765,70769-70771,70773,70776-70777,70788-70789,70824,70828,70832,70836,70842,70851,70855,70857,70866-70872,70883,70885,70893-70894,70896-70897,70903,70905-70907,70915,70927,70933,70951,70960,70962-70964,70998,71001,71006,71008,71010-71011,71019,71037,71056,71094,71101-71103,71106,71119,71123,71149-71150,71203,71212,71214-71217,71221,71240 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 51246
diff changeset
76 an :exc:`AttributeError` is raised and ``-1`` is returned.
792bb885029f Merged revisions 70712,70714,70764-70765,70769-70771,70773,70776-70777,70788-70789,70824,70828,70832,70836,70842,70851,70855,70857,70866-70872,70883,70885,70893-70894,70896-70897,70903,70905-70907,70915,70927,70933,70951,70960,70962-70964,70998,71001,71006,71008,71010-71011,71019,71037,71056,71094,71101-71103,71106,71119,71123,71149-71150,71203,71212,71214-71217,71221,71240 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 51246
diff changeset
77
792bb885029f Merged revisions 70712,70714,70764-70765,70769-70771,70773,70776-70777,70788-70789,70824,70828,70832,70836,70842,70851,70855,70857,70866-70872,70883,70885,70893-70894,70896-70897,70903,70905-70907,70915,70927,70933,70951,70960,70962-70964,70998,71001,71006,71008,71010-71011,71019,71037,71056,71094,71101-71103,71106,71119,71123,71149-71150,71203,71212,71214-71217,71221,71240 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 51246
diff changeset
78
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
79 .. c:function:: int PyObject_DelAttr(PyObject *o, PyObject *attr_name)
44812
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 Delete attribute named *attr_name*, for object *o*. Returns ``-1`` on failure.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
82 This is the equivalent of the Python statement ``del o.attr_name``.
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
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
85 .. c:function:: int PyObject_DelAttrString(PyObject *o, const char *attr_name)
44812
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 Delete attribute named *attr_name*, for object *o*. Returns ``-1`` on failure.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
88 This is the equivalent of the Python statement ``del o.attr_name``.
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
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
91 .. c:function:: PyObject* PyObject_RichCompare(PyObject *o1, PyObject *o2, int opid)
44812
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 Compare the values of *o1* and *o2* using the operation specified by *opid*,
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
94 which must be one of :const:`Py_LT`, :const:`Py_LE`, :const:`Py_EQ`,
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
95 :const:`Py_NE`, :const:`Py_GT`, or :const:`Py_GE`, corresponding to ``<``,
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
96 ``<=``, ``==``, ``!=``, ``>``, or ``>=`` respectively. This is the equivalent of
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
97 the Python expression ``o1 op o2``, where ``op`` is the operator corresponding
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
98 to *opid*. Returns the value of the comparison on success, or *NULL* on failure.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
99
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
100
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
101 .. c:function:: int PyObject_RichCompareBool(PyObject *o1, PyObject *o2, int opid)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
102
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
103 Compare the values of *o1* and *o2* using the operation specified by *opid*,
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
104 which must be one of :const:`Py_LT`, :const:`Py_LE`, :const:`Py_EQ`,
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
105 :const:`Py_NE`, :const:`Py_GT`, or :const:`Py_GE`, corresponding to ``<``,
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
106 ``<=``, ``==``, ``!=``, ``>``, or ``>=`` respectively. Returns ``-1`` on error,
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
107 ``0`` if the result is false, ``1`` otherwise. This is the equivalent of the
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
108 Python expression ``o1 op o2``, where ``op`` is the operator corresponding to
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
109 *opid*.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
110
67602
4dc5503731fe Merged revisions 88009 via svnmerge from
Eli Bendersky <eliben@gmail.com>
parents: 53500
diff changeset
111 .. note::
67601
0b4c995299dd Issue #10912: Clarify the documentation of PyObject_RichCompareBool. Thanks to Devin Jeanpierre for spotting the problem.
Eli Bendersky <eliben@gmail.com>
parents: 65494
diff changeset
112 If *o1* and *o2* are the same object, :c:func:`PyObject_RichCompareBool`
67602
4dc5503731fe Merged revisions 88009 via svnmerge from
Eli Bendersky <eliben@gmail.com>
parents: 53500
diff changeset
113 will always return ``1`` for :const:`Py_EQ` and ``0`` for :const:`Py_NE`.
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
114
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
115 .. c:function:: PyObject* PyObject_Repr(PyObject *o)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
116
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
117 .. index:: builtin: repr
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
118
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
119 Compute a string representation of object *o*. Returns the string
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
120 representation on success, *NULL* on failure. This is the equivalent of the
47611
da47e7e135ae #2630: Implement PEP 3138.
Georg Brandl <georg@python.org>
parents: 44812
diff changeset
121 Python expression ``repr(o)``. Called by the :func:`repr` built-in function.
da47e7e135ae #2630: Implement PEP 3138.
Georg Brandl <georg@python.org>
parents: 44812
diff changeset
122
da47e7e135ae #2630: Implement PEP 3138.
Georg Brandl <georg@python.org>
parents: 44812
diff changeset
123
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
124 .. c:function:: PyObject* PyObject_ASCII(PyObject *o)
47611
da47e7e135ae #2630: Implement PEP 3138.
Georg Brandl <georg@python.org>
parents: 44812
diff changeset
125
da47e7e135ae #2630: Implement PEP 3138.
Georg Brandl <georg@python.org>
parents: 44812
diff changeset
126 .. index:: builtin: ascii
da47e7e135ae #2630: Implement PEP 3138.
Georg Brandl <georg@python.org>
parents: 44812
diff changeset
127
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
128 As :c:func:`PyObject_Repr`, compute a string representation of object *o*, but
47611
da47e7e135ae #2630: Implement PEP 3138.
Georg Brandl <georg@python.org>
parents: 44812
diff changeset
129 escape the non-ASCII characters in the string returned by
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
130 :c:func:`PyObject_Repr` with ``\x``, ``\u`` or ``\U`` escapes. This generates
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
131 a string similar to that returned by :c:func:`PyObject_Repr` in Python 2.
47611
da47e7e135ae #2630: Implement PEP 3138.
Georg Brandl <georg@python.org>
parents: 44812
diff changeset
132 Called by the :func:`ascii` built-in function.
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
133
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
134
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
135 .. c:function:: PyObject* PyObject_Str(PyObject *o)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
136
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
137 .. index:: builtin: str
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
138
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
139 Compute a string representation of object *o*. Returns the string
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
140 representation on success, *NULL* on failure. This is the equivalent of the
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
141 Python expression ``str(o)``. Called by the :func:`str` built-in function
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
142 and, therefore, by the :func:`print` function.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
143
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
144 .. c:function:: PyObject* PyObject_Bytes(PyObject *o)
48871
548dccc4008e make bytes(o) respect __bytes__ #2415
Benjamin Peterson <benjamin@python.org>
parents: 48814
diff changeset
145
548dccc4008e make bytes(o) respect __bytes__ #2415
Benjamin Peterson <benjamin@python.org>
parents: 48814
diff changeset
146 .. index:: builtin: bytes
548dccc4008e make bytes(o) respect __bytes__ #2415
Benjamin Peterson <benjamin@python.org>
parents: 48814
diff changeset
147
58029
d52a7179eece Issue #6687: Moved the special-case for integers out of PyBytes_FromObject.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 53500
diff changeset
148 Compute a bytes representation of object *o*. *NULL* is returned on
d52a7179eece Issue #6687: Moved the special-case for integers out of PyBytes_FromObject.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 53500
diff changeset
149 failure and a bytes object on success. This is equivalent to the Python
d52a7179eece Issue #6687: Moved the special-case for integers out of PyBytes_FromObject.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 53500
diff changeset
150 expression ``bytes(o)``, when *o* is not an integer. Unlike ``bytes(o)``,
d52a7179eece Issue #6687: Moved the special-case for integers out of PyBytes_FromObject.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 53500
diff changeset
151 a TypeError is raised when *o* is an integer instead of a zero-initialized
d52a7179eece Issue #6687: Moved the special-case for integers out of PyBytes_FromObject.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 53500
diff changeset
152 bytes object.
48871
548dccc4008e make bytes(o) respect __bytes__ #2415
Benjamin Peterson <benjamin@python.org>
parents: 48814
diff changeset
153
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
154 .. c:function:: int PyObject_IsInstance(PyObject *inst, PyObject *cls)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
155
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
156 Returns ``1`` if *inst* is an instance of the class *cls* or a subclass of
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
157 *cls*, or ``0`` if not. On error, returns ``-1`` and sets an exception. If
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
158 *cls* is a type object rather than a class object, :c:func:`PyObject_IsInstance`
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
159 returns ``1`` if *inst* is of type *cls*. If *cls* is a tuple, the check will
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
160 be done against every entry in *cls*. The result will be ``1`` when at least one
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
161 of the checks returns ``1``, otherwise it will be ``0``. If *inst* is not a
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
162 class instance and *cls* is neither a type object, nor a class object, nor a
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
163 tuple, *inst* must have a :attr:`__class__` attribute --- the class relationship
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
164 of the value of that attribute with *cls* will be used to determine the result
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
165 of this function.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
166
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
167
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
168 Subclass determination is done in a fairly straightforward way, but includes a
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
169 wrinkle that implementors of extensions to the class system may want to be aware
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
170 of. If :class:`A` and :class:`B` are class objects, :class:`B` is a subclass of
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
171 :class:`A` if it inherits from :class:`A` either directly or indirectly. If
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
172 either is not a class object, a more general mechanism is used to determine the
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
173 class relationship of the two objects. When testing if *B* is a subclass of
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
174 *A*, if *A* is *B*, :c:func:`PyObject_IsSubclass` returns true. If *A* and *B*
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
175 are different objects, *B*'s :attr:`__bases__` attribute is searched in a
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
176 depth-first fashion for *A* --- the presence of the :attr:`__bases__` attribute
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
177 is considered sufficient for this determination.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
178
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
179
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
180 .. c:function:: int PyObject_IsSubclass(PyObject *derived, PyObject *cls)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
181
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
182 Returns ``1`` if the class *derived* is identical to or derived from the class
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
183 *cls*, otherwise returns ``0``. In case of an error, returns ``-1``. If *cls*
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
184 is a tuple, the check will be done against every entry in *cls*. The result will
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
185 be ``1`` when at least one of the checks returns ``1``, otherwise it will be
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
186 ``0``. If either *derived* or *cls* is not an actual class object (or tuple),
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
187 this function uses the generic algorithm described above.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
188
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
189
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
190 .. c:function:: int PyCallable_Check(PyObject *o)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
191
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
192 Determine if the object *o* is callable. Return ``1`` if the object is callable
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
193 and ``0`` otherwise. This function always succeeds.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
194
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
195
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
196 .. c:function:: PyObject* PyObject_Call(PyObject *callable_object, PyObject *args, PyObject *kw)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
197
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
198 Call a callable Python object *callable_object*, with arguments given by the
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
199 tuple *args*, and named arguments given by the dictionary *kw*. If no named
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
200 arguments are needed, *kw* may be *NULL*. *args* must not be *NULL*, use an
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
201 empty tuple if no arguments are needed. Returns the result of the call on
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
202 success, or *NULL* on failure. This is the equivalent of the Python expression
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
203 ``callable_object(*args, **kw)``.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
204
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
205
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
206 .. c:function:: PyObject* PyObject_CallObject(PyObject *callable_object, PyObject *args)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
207
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
208 Call a callable Python object *callable_object*, with arguments given by the
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
209 tuple *args*. If no arguments are needed, then *args* may be *NULL*. Returns
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
210 the result of the call on success, or *NULL* on failure. This is the equivalent
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
211 of the Python expression ``callable_object(*args)``.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
212
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
213
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
214 .. c:function:: PyObject* PyObject_CallFunction(PyObject *callable, char *format, ...)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
215
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
216 Call a callable Python object *callable*, with a variable number of C arguments.
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
217 The C arguments are described using a :c:func:`Py_BuildValue` style format
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
218 string. The format may be *NULL*, indicating that no arguments are provided.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
219 Returns the result of the call on success, or *NULL* on failure. This is the
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
220 equivalent of the Python expression ``callable(*args)``. Note that if you only
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
221 pass :c:type:`PyObject \*` args, :c:func:`PyObject_CallFunctionObjArgs` is a
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
222 faster alternative.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
223
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
224
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
225 .. c:function:: PyObject* PyObject_CallMethod(PyObject *o, char *method, char *format, ...)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
226
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
227 Call the method named *method* of object *o* with a variable number of C
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
228 arguments. The C arguments are described by a :c:func:`Py_BuildValue` format
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
229 string that should produce a tuple. The format may be *NULL*, indicating that
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
230 no arguments are provided. Returns the result of the call on success, or *NULL*
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
231 on failure. This is the equivalent of the Python expression ``o.method(args)``.
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
232 Note that if you only pass :c:type:`PyObject \*` args,
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
233 :c:func:`PyObject_CallMethodObjArgs` is a faster alternative.
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
234
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
235
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
236 .. c:function:: PyObject* PyObject_CallFunctionObjArgs(PyObject *callable, ..., NULL)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
237
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
238 Call a callable Python object *callable*, with a variable number of
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
239 :c:type:`PyObject\*` arguments. The arguments are provided as a variable number
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
240 of parameters followed by *NULL*. Returns the result of the call on success, or
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
241 *NULL* on failure.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
242
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
243
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
244 .. c:function:: PyObject* PyObject_CallMethodObjArgs(PyObject *o, PyObject *name, ..., NULL)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
245
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
246 Calls a method of the object *o*, where the name of the method is given as a
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
247 Python string object in *name*. It is called with a variable number of
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
248 :c:type:`PyObject\*` arguments. The arguments are provided as a variable number
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
249 of parameters followed by *NULL*. Returns the result of the call on success, or
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
250 *NULL* on failure.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
251
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
252
65494
e8969fb822fc make hashes always the size of pointers; introduce Py_hash_t #9778
Benjamin Peterson <benjamin@python.org>
parents: 65137
diff changeset
253 .. c:function:: Py_hash_t PyObject_Hash(PyObject *o)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
254
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
255 .. index:: builtin: hash
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
256
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
257 Compute and return the hash value of an object *o*. On failure, return ``-1``.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
258 This is the equivalent of the Python expression ``hash(o)``.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
259
65494
e8969fb822fc make hashes always the size of pointers; introduce Py_hash_t #9778
Benjamin Peterson <benjamin@python.org>
parents: 65137
diff changeset
260 .. versionchanged:: 3.2
e8969fb822fc make hashes always the size of pointers; introduce Py_hash_t #9778
Benjamin Peterson <benjamin@python.org>
parents: 65137
diff changeset
261 The return type is now Py_hash_t. This is a signed integer the same size
e8969fb822fc make hashes always the size of pointers; introduce Py_hash_t #9778
Benjamin Peterson <benjamin@python.org>
parents: 65137
diff changeset
262 as Py_ssize_t.
e8969fb822fc make hashes always the size of pointers; introduce Py_hash_t #9778
Benjamin Peterson <benjamin@python.org>
parents: 65137
diff changeset
263
e8969fb822fc make hashes always the size of pointers; introduce Py_hash_t #9778
Benjamin Peterson <benjamin@python.org>
parents: 65137
diff changeset
264
e8969fb822fc make hashes always the size of pointers; introduce Py_hash_t #9778
Benjamin Peterson <benjamin@python.org>
parents: 65137
diff changeset
265 .. c:function:: Py_hash_t PyObject_HashNotImplemented(PyObject *o)
48741
7517bdcc769a Merged revisions 65810 via svnmerge from
Nick Coghlan <ncoghlan@gmail.com>
parents: 47611
diff changeset
266
49433
8f5a8ea5ba76 Merged revisions 66670,66681,66688,66696-66699 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 48871
diff changeset
267 Set a :exc:`TypeError` indicating that ``type(o)`` is not hashable and return ``-1``.
48741
7517bdcc769a Merged revisions 65810 via svnmerge from
Nick Coghlan <ncoghlan@gmail.com>
parents: 47611
diff changeset
268 This function receives special treatment when stored in a ``tp_hash`` slot,
48771
ea3d13cd7c1e Merged revisions 65780,65782,65785,65809,65812,65834,65846,65859,65861 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 48741
diff changeset
269 allowing a type to explicitly indicate to the interpreter that it is not
48741
7517bdcc769a Merged revisions 65810 via svnmerge from
Nick Coghlan <ncoghlan@gmail.com>
parents: 47611
diff changeset
270 hashable.
7517bdcc769a Merged revisions 65810 via svnmerge from
Nick Coghlan <ncoghlan@gmail.com>
parents: 47611
diff changeset
271
7517bdcc769a Merged revisions 65810 via svnmerge from
Nick Coghlan <ncoghlan@gmail.com>
parents: 47611
diff changeset
272
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
273 .. c:function:: int PyObject_IsTrue(PyObject *o)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
274
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
275 Returns ``1`` if the object *o* is considered to be true, and ``0`` otherwise.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
276 This is equivalent to the Python expression ``not not o``. On failure, return
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
277 ``-1``.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
278
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
279
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
280 .. c:function:: int PyObject_Not(PyObject *o)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
281
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
282 Returns ``0`` if the object *o* is considered to be true, and ``1`` otherwise.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
283 This is equivalent to the Python expression ``not o``. On failure, return
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
284 ``-1``.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
285
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
286
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
287 .. c:function:: PyObject* PyObject_Type(PyObject *o)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
288
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
289 .. index:: builtin: type
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
290
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
291 When *o* is non-*NULL*, returns a type object corresponding to the object type
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
292 of object *o*. On failure, raises :exc:`SystemError` and returns *NULL*. This
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
293 is equivalent to the Python expression ``type(o)``. This function increments the
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
294 reference count of the return value. There's really no reason to use this
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
295 function instead of the common expression ``o->ob_type``, which returns a
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
296 pointer of type :c:type:`PyTypeObject\*`, except when the incremented reference
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
297 count is needed.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
298
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
299
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
300 .. c:function:: int PyObject_TypeCheck(PyObject *o, PyTypeObject *type)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
301
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
302 Return true if the object *o* is of type *type* or a subtype of *type*. Both
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
303 parameters must be non-*NULL*.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
304
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
305
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
306 .. c:function:: Py_ssize_t PyObject_Length(PyObject *o)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
307 Py_ssize_t PyObject_Size(PyObject *o)
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
308
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
309 .. index:: builtin: len
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
310
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
311 Return the length of object *o*. If the object *o* provides either the sequence
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
312 and mapping protocols, the sequence length is returned. On error, ``-1`` is
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
313 returned. This is the equivalent to the Python expression ``len(o)``.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
314
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
315
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
316 .. c:function:: PyObject* PyObject_GetItem(PyObject *o, PyObject *key)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
317
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
318 Return element of *o* corresponding to the object *key* or *NULL* on failure.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
319 This is the equivalent of the Python expression ``o[key]``.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
320
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
321
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
322 .. c:function:: int PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
323
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
324 Map the object *key* to the value *v*. Returns ``-1`` on failure. This is the
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
325 equivalent of the Python statement ``o[key] = v``.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
326
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
327
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
328 .. c:function:: int PyObject_DelItem(PyObject *o, PyObject *key)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
329
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
330 Delete the mapping for *key* from *o*. Returns ``-1`` on failure. This is the
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
331 equivalent of the Python statement ``del o[key]``.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
332
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
333
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
334 .. c:function:: PyObject* PyObject_Dir(PyObject *o)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
335
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
336 This is equivalent to the Python expression ``dir(o)``, returning a (possibly
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
337 empty) list of strings appropriate for the object argument, or *NULL* if there
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
338 was an error. If the argument is *NULL*, this is like the Python ``dir()``,
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
339 returning the names of the current locals; in this case, if no execution frame
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
340 is active then *NULL* is returned but :c:func:`PyErr_Occurred` will return false.
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
341
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
342
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 58029
diff changeset
343 .. c:function:: PyObject* PyObject_GetIter(PyObject *o)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
344
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
345 This is equivalent to the Python expression ``iter(o)``. It returns a new
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
346 iterator for the object argument, or the object itself if the object is already
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
347 an iterator. Raises :exc:`TypeError` and returns *NULL* if the object cannot be
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
348 iterated.