9
.. c:function:: int PyObject_Print(PyObject *o, FILE *fp, int flags)
11
Print an object *o*, on file *fp*. Returns ``-1`` on error. The flags argument
12
is used to enable certain printing options. The only option currently supported
13
is :const:`Py_PRINT_RAW`; if given, the :func:`str` of the object is written
14
instead of the :func:`repr`.
17
.. c:function:: int PyObject_HasAttr(PyObject *o, PyObject *attr_name)
19
Returns ``1`` if *o* has the attribute *attr_name*, and ``0`` otherwise. This
20
is equivalent to the Python expression ``hasattr(o, attr_name)``. This function
24
.. c:function:: int PyObject_HasAttrString(PyObject *o, const char *attr_name)
26
Returns ``1`` if *o* has the attribute *attr_name*, and ``0`` otherwise. This
27
is equivalent to the Python expression ``hasattr(o, attr_name)``. This function
31
.. c:function:: PyObject* PyObject_GetAttr(PyObject *o, PyObject *attr_name)
33
Retrieve an attribute named *attr_name* from object *o*. Returns the attribute
34
value on success, or *NULL* on failure. This is the equivalent of the Python
35
expression ``o.attr_name``.
38
.. c:function:: PyObject* PyObject_GetAttrString(PyObject *o, const char *attr_name)
40
Retrieve an attribute named *attr_name* from object *o*. Returns the attribute
41
value on success, or *NULL* on failure. This is the equivalent of the Python
42
expression ``o.attr_name``.
45
.. c:function:: PyObject* PyObject_GenericGetAttr(PyObject *o, PyObject *name)
47
Generic attribute getter function that is meant to be put into a type
48
object's ``tp_getattro`` slot. It looks for a descriptor in the dictionary
49
of classes in the object's MRO as well as an attribute in the object's
50
:attr:`~object.__dict__` (if present). As outlined in :ref:`descriptors`,
51
data descriptors take preference over instance attributes, while non-data
52
descriptors don't. Otherwise, an :exc:`AttributeError` is raised.
55
.. c:function:: int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v)
57
Set the value of the attribute named *attr_name*, for object *o*, to the value
58
*v*. Returns ``-1`` on failure. This is the equivalent of the Python statement
62
.. c:function:: int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v)
64
Set the value of the attribute named *attr_name*, for object *o*, to the value
65
*v*. Returns ``-1`` on failure. This is the equivalent of the Python statement
69
.. c:function:: int PyObject_GenericSetAttr(PyObject *o, PyObject *name, PyObject *value)
71
Generic attribute setter function that is meant to be put into a type
72
object's ``tp_setattro`` slot. It looks for a data descriptor in the
73
dictionary of classes in the object's MRO, and if found it takes preference
74
over setting the attribute in the instance dictionary. Otherwise, the
75
attribute is set in the object's :attr:`~object.__dict__` (if present).
76
Otherwise, an :exc:`AttributeError` is raised and ``-1`` is returned.
79
.. c:function:: int PyObject_DelAttr(PyObject *o, PyObject *attr_name)
81
Delete attribute named *attr_name*, for object *o*. Returns ``-1`` on failure.
82
This is the equivalent of the Python statement ``del o.attr_name``.
85
.. c:function:: int PyObject_DelAttrString(PyObject *o, const char *attr_name)
87
Delete attribute named *attr_name*, for object *o*. Returns ``-1`` on failure.
88
This is the equivalent of the Python statement ``del o.attr_name``.
91
.. c:function:: PyObject* PyObject_RichCompare(PyObject *o1, PyObject *o2, int opid)
93
Compare the values of *o1* and *o2* using the operation specified by *opid*,
94
which must be one of :const:`Py_LT`, :const:`Py_LE`, :const:`Py_EQ`,
95
:const:`Py_NE`, :const:`Py_GT`, or :const:`Py_GE`, corresponding to ``<``,
96
``<=``, ``==``, ``!=``, ``>``, or ``>=`` respectively. This is the equivalent of
97
the Python expression ``o1 op o2``, where ``op`` is the operator corresponding
98
to *opid*. Returns the value of the comparison on success, or *NULL* on failure.
101
.. c:function:: int PyObject_RichCompareBool(PyObject *o1, PyObject *o2, int opid)
103
Compare the values of *o1* and *o2* using the operation specified by *opid*,
104
which must be one of :const:`Py_LT`, :const:`Py_LE`, :const:`Py_EQ`,
105
:const:`Py_NE`, :const:`Py_GT`, or :const:`Py_GE`, corresponding to ``<``,
106
``<=``, ``==``, ``!=``, ``>``, or ``>=`` respectively. Returns ``-1`` on error,
107
``0`` if the result is false, ``1`` otherwise. This is the equivalent of the
108
Python expression ``o1 op o2``, where ``op`` is the operator corresponding to
112
If *o1* and *o2* are the same object, :c:func:`PyObject_RichCompareBool`
113
will always return ``1`` for :const:`Py_EQ` and ``0`` for :const:`Py_NE`.
115
.. c:function:: int PyObject_Cmp(PyObject *o1, PyObject *o2, int *result)
117
.. index:: builtin: cmp
119
Compare the values of *o1* and *o2* using a routine provided by *o1*, if one
120
exists, otherwise with a routine provided by *o2*. The result of the comparison
121
is returned in *result*. Returns ``-1`` on failure. This is the equivalent of
122
the Python statement ``result = cmp(o1, o2)``.
125
.. c:function:: int PyObject_Compare(PyObject *o1, PyObject *o2)
127
.. index:: builtin: cmp
129
Compare the values of *o1* and *o2* using a routine provided by *o1*, if one
130
exists, otherwise with a routine provided by *o2*. Returns the result of the
131
comparison on success. On error, the value returned is undefined; use
132
:c:func:`PyErr_Occurred` to detect an error. This is equivalent to the Python
133
expression ``cmp(o1, o2)``.
136
.. c:function:: PyObject* PyObject_Repr(PyObject *o)
138
.. index:: builtin: repr
140
Compute a string representation of object *o*. Returns the string
141
representation on success, *NULL* on failure. This is the equivalent of the
142
Python expression ``repr(o)``. Called by the :func:`repr` built-in function and
146
.. c:function:: PyObject* PyObject_Str(PyObject *o)
148
.. index:: builtin: str
150
Compute a string representation of object *o*. Returns the string
151
representation on success, *NULL* on failure. This is the equivalent of the
152
Python expression ``str(o)``. Called by the :func:`str` built-in function and
153
by the :keyword:`print` statement.
156
.. c:function:: PyObject* PyObject_Bytes(PyObject *o)
158
.. index:: builtin: bytes
160
Compute a bytes representation of object *o*. In 2.x, this is just a alias
161
for :c:func:`PyObject_Str`.
164
.. c:function:: PyObject* PyObject_Unicode(PyObject *o)
166
.. index:: builtin: unicode
168
Compute a Unicode string representation of object *o*. Returns the Unicode
169
string representation on success, *NULL* on failure. This is the equivalent of
170
the Python expression ``unicode(o)``. Called by the :func:`unicode` built-in
174
.. c:function:: int PyObject_IsInstance(PyObject *inst, PyObject *cls)
176
Returns ``1`` if *inst* is an instance of the class *cls* or a subclass of
177
*cls*, or ``0`` if not. On error, returns ``-1`` and sets an exception. If
178
*cls* is a type object rather than a class object, :c:func:`PyObject_IsInstance`
179
returns ``1`` if *inst* is of type *cls*. If *cls* is a tuple, the check will
180
be done against every entry in *cls*. The result will be ``1`` when at least one
181
of the checks returns ``1``, otherwise it will be ``0``. If *inst* is not a
182
class instance and *cls* is neither a type object, nor a class object, nor a
183
tuple, *inst* must have a :attr:`~instance.__class__` attribute --- the
184
class relationship of the value of that attribute with *cls* will be used
185
to determine the result of this function.
187
.. versionadded:: 2.1
189
.. versionchanged:: 2.2
190
Support for a tuple as the second argument added.
192
Subclass determination is done in a fairly straightforward way, but includes a
193
wrinkle that implementors of extensions to the class system may want to be aware
194
of. If :class:`A` and :class:`B` are class objects, :class:`B` is a subclass of
195
:class:`A` if it inherits from :class:`A` either directly or indirectly. If
196
either is not a class object, a more general mechanism is used to determine the
197
class relationship of the two objects. When testing if *B* is a subclass of
198
*A*, if *A* is *B*, :c:func:`PyObject_IsSubclass` returns true. If *A* and *B*
199
are different objects, *B*'s :attr:`~class.__bases__` attribute is searched in
200
a depth-first fashion for *A* --- the presence of the :attr:`~class.__bases__`
201
attribute is considered sufficient for this determination.
204
.. c:function:: int PyObject_IsSubclass(PyObject *derived, PyObject *cls)
206
Returns ``1`` if the class *derived* is identical to or derived from the class
207
*cls*, otherwise returns ``0``. In case of an error, returns ``-1``. If *cls*
208
is a tuple, the check will be done against every entry in *cls*. The result will
209
be ``1`` when at least one of the checks returns ``1``, otherwise it will be
210
``0``. If either *derived* or *cls* is not an actual class object (or tuple),
211
this function uses the generic algorithm described above.
213
.. versionadded:: 2.1
215
.. versionchanged:: 2.3
216
Older versions of Python did not support a tuple as the second argument.
219
.. c:function:: int PyCallable_Check(PyObject *o)
221
Determine if the object *o* is callable. Return ``1`` if the object is callable
222
and ``0`` otherwise. This function always succeeds.
225
.. c:function:: PyObject* PyObject_Call(PyObject *callable_object, PyObject *args, PyObject *kw)
227
.. index:: builtin: apply
229
Call a callable Python object *callable_object*, with arguments given by the
230
tuple *args*, and named arguments given by the dictionary *kw*. If no named
231
arguments are needed, *kw* may be *NULL*. *args* must not be *NULL*, use an
232
empty tuple if no arguments are needed. Returns the result of the call on
233
success, or *NULL* on failure. This is the equivalent of the Python expression
234
``apply(callable_object, args, kw)`` or ``callable_object(*args, **kw)``.
236
.. versionadded:: 2.2
239
.. c:function:: PyObject* PyObject_CallObject(PyObject *callable_object, PyObject *args)
241
.. index:: builtin: apply
243
Call a callable Python object *callable_object*, with arguments given by the
244
tuple *args*. If no arguments are needed, then *args* may be *NULL*. Returns
245
the result of the call on success, or *NULL* on failure. This is the equivalent
246
of the Python expression ``apply(callable_object, args)`` or
247
``callable_object(*args)``.
250
.. c:function:: PyObject* PyObject_CallFunction(PyObject *callable, char *format, ...)
252
.. index:: builtin: apply
254
Call a callable Python object *callable*, with a variable number of C arguments.
255
The C arguments are described using a :c:func:`Py_BuildValue` style format
256
string. The format may be *NULL*, indicating that no arguments are provided.
257
Returns the result of the call on success, or *NULL* on failure. This is the
258
equivalent of the Python expression ``apply(callable, args)`` or
259
``callable(*args)``. Note that if you only pass :c:type:`PyObject \*` args,
260
:c:func:`PyObject_CallFunctionObjArgs` is a faster alternative.
263
.. c:function:: PyObject* PyObject_CallMethod(PyObject *o, char *method, char *format, ...)
265
Call the method named *method* of object *o* with a variable number of C
266
arguments. The C arguments are described by a :c:func:`Py_BuildValue` format
267
string that should produce a tuple. The format may be *NULL*, indicating that
268
no arguments are provided. Returns the result of the call on success, or *NULL*
269
on failure. This is the equivalent of the Python expression ``o.method(args)``.
270
Note that if you only pass :c:type:`PyObject \*` args,
271
:c:func:`PyObject_CallMethodObjArgs` is a faster alternative.
274
.. c:function:: PyObject* PyObject_CallFunctionObjArgs(PyObject *callable, ..., NULL)
276
Call a callable Python object *callable*, with a variable number of
277
:c:type:`PyObject\*` arguments. The arguments are provided as a variable number
278
of parameters followed by *NULL*. Returns the result of the call on success, or
281
.. versionadded:: 2.2
284
.. c:function:: PyObject* PyObject_CallMethodObjArgs(PyObject *o, PyObject *name, ..., NULL)
286
Calls a method of the object *o*, where the name of the method is given as a
287
Python string object in *name*. It is called with a variable number of
288
:c:type:`PyObject\*` arguments. The arguments are provided as a variable number
289
of parameters followed by *NULL*. Returns the result of the call on success, or
292
.. versionadded:: 2.2
295
.. c:function:: long PyObject_Hash(PyObject *o)
297
.. index:: builtin: hash
299
Compute and return the hash value of an object *o*. On failure, return ``-1``.
300
This is the equivalent of the Python expression ``hash(o)``.
303
.. c:function:: long PyObject_HashNotImplemented(PyObject *o)
305
Set a :exc:`TypeError` indicating that ``type(o)`` is not hashable and return ``-1``.
306
This function receives special treatment when stored in a ``tp_hash`` slot,
307
allowing a type to explicitly indicate to the interpreter that it is not
310
.. versionadded:: 2.6
313
.. c:function:: int PyObject_IsTrue(PyObject *o)
315
Returns ``1`` if the object *o* is considered to be true, and ``0`` otherwise.
316
This is equivalent to the Python expression ``not not o``. On failure, return
320
.. c:function:: int PyObject_Not(PyObject *o)
322
Returns ``0`` if the object *o* is considered to be true, and ``1`` otherwise.
323
This is equivalent to the Python expression ``not o``. On failure, return
327
.. c:function:: PyObject* PyObject_Type(PyObject *o)
329
.. index:: builtin: type
331
When *o* is non-*NULL*, returns a type object corresponding to the object type
332
of object *o*. On failure, raises :exc:`SystemError` and returns *NULL*. This
333
is equivalent to the Python expression ``type(o)``. This function increments the
334
reference count of the return value. There's really no reason to use this
335
function instead of the common expression ``o->ob_type``, which returns a
336
pointer of type :c:type:`PyTypeObject\*`, except when the incremented reference
340
.. c:function:: int PyObject_TypeCheck(PyObject *o, PyTypeObject *type)
342
Return true if the object *o* is of type *type* or a subtype of *type*. Both
343
parameters must be non-*NULL*.
345
.. versionadded:: 2.2
348
.. c:function:: Py_ssize_t PyObject_Length(PyObject *o)
349
Py_ssize_t PyObject_Size(PyObject *o)
351
.. index:: builtin: len
353
Return the length of object *o*. If the object *o* provides either the sequence
354
and mapping protocols, the sequence length is returned. On error, ``-1`` is
355
returned. This is the equivalent to the Python expression ``len(o)``.
357
.. versionchanged:: 2.5
358
These functions returned an :c:type:`int` type. This might require
359
changes in your code for properly supporting 64-bit systems.
362
.. c:function:: PyObject* PyObject_GetItem(PyObject *o, PyObject *key)
364
Return element of *o* corresponding to the object *key* or *NULL* on failure.
365
This is the equivalent of the Python expression ``o[key]``.
368
.. c:function:: int PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v)
370
Map the object *key* to the value *v*. Returns ``-1`` on failure. This is the
371
equivalent of the Python statement ``o[key] = v``.
374
.. c:function:: int PyObject_DelItem(PyObject *o, PyObject *key)
376
Delete the mapping for *key* from *o*. Returns ``-1`` on failure. This is the
377
equivalent of the Python statement ``del o[key]``.
380
.. c:function:: int PyObject_AsFileDescriptor(PyObject *o)
382
Derives a file descriptor from a Python object. If the object is an integer or
383
long integer, its value is returned. If not, the object's :meth:`fileno` method
384
is called if it exists; the method must return an integer or long integer, which
385
is returned as the file descriptor value. Returns ``-1`` on failure.
388
.. c:function:: PyObject* PyObject_Dir(PyObject *o)
390
This is equivalent to the Python expression ``dir(o)``, returning a (possibly
391
empty) list of strings appropriate for the object argument, or *NULL* if there
392
was an error. If the argument is *NULL*, this is like the Python ``dir()``,
393
returning the names of the current locals; in this case, if no execution frame
394
is active then *NULL* is returned but :c:func:`PyErr_Occurred` will return false.
397
.. c:function:: PyObject* PyObject_GetIter(PyObject *o)
399
This is equivalent to the Python expression ``iter(o)``. It returns a new
400
iterator for the object argument, or the object itself if the object is already
401
an iterator. Raises :exc:`TypeError` and returns *NULL* if the object cannot be
added
removed
python-2.7.11-docs-html/_sources/c-api/object.txt
