Doc/c-api/object.rst

   1 .. highlightlang:: c
   2
   3 .. _object:
   4
   5 Object Protocol
   6 ===============
   7
   8
   9 .. c:function:: int PyObject_Print(PyObject *o, FILE *fp, int flags)
  10
  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`.
  15
  16
  17 .. c:function:: int PyObject_HasAttr(PyObject *o, PyObject *attr_name)
  18
  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
  21    always succeeds.
  22
  23
  24 .. c:function:: int PyObject_HasAttrString(PyObject *o, const char *attr_name)
  25
  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
  28    always succeeds.
  29
  30
  31 .. c:function:: PyObject* PyObject_GetAttr(PyObject *o, PyObject *attr_name)
  32
  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``.
  36
  37
  38 .. c:function:: PyObject* PyObject_GetAttrString(PyObject *o, const char *attr_name)
  39
  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``.
  43
  44
  45 .. c:function:: PyObject* PyObject_GenericGetAttr(PyObject *o, PyObject *name)
  46
  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:`__dict__` (if present).  As outlined in :ref:`descriptors`, data
  51    descriptors take preference over instance attributes, while non-data
  52    descriptors don't.  Otherwise, an :exc:`AttributeError` is raised.
  53
  54
  55 .. c:function:: int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v)
  56
  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
  59    ``o.attr_name = v``.
  60
  61
  62 .. c:function:: int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v)
  63
  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
  66    ``o.attr_name = v``.
  67
  68
  69 .. c:function:: int PyObject_GenericSetAttr(PyObject *o, PyObject *name, PyObject *value)
  70
  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:`__dict__` (if present).  Otherwise,
  76    an :exc:`AttributeError` is raised and ``-1`` is returned.
  77
  78
  79 .. c:function:: int PyObject_DelAttr(PyObject *o, PyObject *attr_name)
  80
  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``.
  83
  84
  85 .. c:function:: int PyObject_DelAttrString(PyObject *o, const char *attr_name)
  86
  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``.
  89
  90
  91 .. c:function:: PyObject* PyObject_RichCompare(PyObject *o1, PyObject *o2, int opid)
  92
  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.
  99
 100
 101 .. c:function:: int PyObject_RichCompareBool(PyObject *o1, PyObject *o2, int opid)
 102
 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
 109    *opid*.
 110
 111 .. note::
 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`.
 114
 115 .. c:function:: int PyObject_Cmp(PyObject *o1, PyObject *o2, int *result)
 116
 117    .. index:: builtin: cmp
 118
 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)``.
 123
 124
 125 .. c:function:: int PyObject_Compare(PyObject *o1, PyObject *o2)
 126
 127    .. index:: builtin: cmp
 128
 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)``.
 134
 135
 136 .. c:function:: PyObject* PyObject_Repr(PyObject *o)
 137
 138    .. index:: builtin: repr
 139
 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
 143    by reverse quotes.
 144
 145
 146 .. c:function:: PyObject* PyObject_Str(PyObject *o)
 147
 148    .. index:: builtin: str
 149
 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.
 154
 155
 156 .. c:function:: PyObject* PyObject_Bytes(PyObject *o)
 157
 158    .. index:: builtin: bytes
 159
 160    Compute a bytes representation of object *o*.  In 2.x, this is just a alias
 161    for :c:func:`PyObject_Str`.
 162
 163
 164 .. c:function:: PyObject* PyObject_Unicode(PyObject *o)
 165
 166    .. index:: builtin: unicode
 167
 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
 171    function.
 172
 173
 174 .. c:function:: int PyObject_IsInstance(PyObject *inst, PyObject *cls)
 175
 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:`__class__` attribute --- the class relationship
 184    of the value of that attribute with *cls* will be used to determine the result
 185    of this function.
 186
 187    .. versionadded:: 2.1
 188
 189    .. versionchanged:: 2.2
 190       Support for a tuple as the second argument added.
 191
 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:`__bases__` attribute is searched in a
 200 depth-first fashion for *A* --- the presence of the :attr:`__bases__` attribute
 201 is considered sufficient for this determination.
 202
 203
 204 .. c:function:: int PyObject_IsSubclass(PyObject *derived, PyObject *cls)
 205
 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.
 212
 213    .. versionadded:: 2.1
 214
 215    .. versionchanged:: 2.3
 216       Older versions of Python did not support a tuple as the second argument.
 217
 218
 219 .. c:function:: int PyCallable_Check(PyObject *o)
 220
 221    Determine if the object *o* is callable.  Return ``1`` if the object is callable
 222    and ``0`` otherwise.  This function always succeeds.
 223
 224
 225 .. c:function:: PyObject* PyObject_Call(PyObject *callable_object, PyObject *args, PyObject *kw)
 226
 227    .. index:: builtin: apply
 228
 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)``.
 235
 236    .. versionadded:: 2.2
 237
 238
 239 .. c:function:: PyObject* PyObject_CallObject(PyObject *callable_object, PyObject *args)
 240
 241    .. index:: builtin: apply
 242
 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)``.
 248
 249
 250 .. c:function:: PyObject* PyObject_CallFunction(PyObject *callable, char *format, ...)
 251
 252    .. index:: builtin: apply
 253
 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.
 261
 262
 263 .. c:function:: PyObject* PyObject_CallMethod(PyObject *o, char *method, char *format, ...)
 264
 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.
 272
 273
 274 .. c:function:: PyObject* PyObject_CallFunctionObjArgs(PyObject *callable, ..., NULL)
 275
 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
 279    *NULL* on failure.
 280
 281    .. versionadded:: 2.2
 282
 283
 284 .. c:function:: PyObject* PyObject_CallMethodObjArgs(PyObject *o, PyObject *name, ..., NULL)
 285
 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
 290    *NULL* on failure.
 291
 292    .. versionadded:: 2.2
 293
 294
 295 .. c:function:: long PyObject_Hash(PyObject *o)
 296
 297    .. index:: builtin: hash
 298
 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)``.
 301
 302
 303 .. c:function:: long PyObject_HashNotImplemented(PyObject *o)
 304
 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
 308    hashable.
 309
 310    .. versionadded:: 2.6
 311
 312
 313 .. c:function:: int PyObject_IsTrue(PyObject *o)
 314
 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
 317    ``-1``.
 318
 319
 320 .. c:function:: int PyObject_Not(PyObject *o)
 321
 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
 324    ``-1``.
 325
 326
 327 .. c:function:: PyObject* PyObject_Type(PyObject *o)
 328
 329    .. index:: builtin: type
 330
 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
 337    count is needed.
 338
 339
 340 .. c:function:: int PyObject_TypeCheck(PyObject *o, PyTypeObject *type)
 341
 342    Return true if the object *o* is of type *type* or a subtype of *type*.  Both
 343    parameters must be non-*NULL*.
 344
 345    .. versionadded:: 2.2
 346
 347
 348 .. c:function:: Py_ssize_t PyObject_Length(PyObject *o)
 349                Py_ssize_t PyObject_Size(PyObject *o)
 350
 351    .. index:: builtin: len
 352
 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)``.
 356
 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.
 360
 361
 362 .. c:function:: PyObject* PyObject_GetItem(PyObject *o, PyObject *key)
 363
 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]``.
 366
 367
 368 .. c:function:: int PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v)
 369
 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``.
 372
 373
 374 .. c:function:: int PyObject_DelItem(PyObject *o, PyObject *key)
 375
 376    Delete the mapping for *key* from *o*.  Returns ``-1`` on failure. This is the
 377    equivalent of the Python statement ``del o[key]``.
 378
 379
 380 .. c:function:: int PyObject_AsFileDescriptor(PyObject *o)
 381
 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.
 386
 387
 388 .. c:function:: PyObject* PyObject_Dir(PyObject *o)
 389
 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.
 395
 396
 397 .. c:function:: PyObject* PyObject_GetIter(PyObject *o)
 398
 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
 402    iterated.