1.. highlight:: c 2 3.. _object: 4 5Object Protocol 6=============== 7 8 9.. c:var:: PyObject* Py_NotImplemented 10 11 The ``NotImplemented`` singleton, used to signal that an operation is 12 not implemented for the given type combination. 13 14 15.. c:macro:: Py_RETURN_NOTIMPLEMENTED 16 17 Properly handle returning :c:data:`Py_NotImplemented` from within a C 18 function (that is, increment the reference count of NotImplemented and 19 return it). 20 21 22.. c:function:: int PyObject_Print(PyObject *o, FILE *fp, int flags) 23 24 Print an object *o*, on file *fp*. Returns ``-1`` on error. The flags argument 25 is used to enable certain printing options. The only option currently supported 26 is :const:`Py_PRINT_RAW`; if given, the :func:`str` of the object is written 27 instead of the :func:`repr`. 28 29 30.. c:function:: int PyObject_HasAttr(PyObject *o, PyObject *attr_name) 31 32 Returns ``1`` if *o* has the attribute *attr_name*, and ``0`` otherwise. This 33 is equivalent to the Python expression ``hasattr(o, attr_name)``. This function 34 always succeeds. 35 36 Note that exceptions which occur while calling :meth:`__getattr__` and 37 :meth:`__getattribute__` methods will get suppressed. 38 To get error reporting use :c:func:`PyObject_GetAttr()` instead. 39 40 41.. c:function:: int PyObject_HasAttrString(PyObject *o, const char *attr_name) 42 43 Returns ``1`` if *o* has the attribute *attr_name*, and ``0`` otherwise. This 44 is equivalent to the Python expression ``hasattr(o, attr_name)``. This function 45 always succeeds. 46 47 Note that exceptions which occur while calling :meth:`__getattr__` and 48 :meth:`__getattribute__` methods and creating a temporary string object 49 will get suppressed. 50 To get error reporting use :c:func:`PyObject_GetAttrString()` instead. 51 52 53.. c:function:: PyObject* PyObject_GetAttr(PyObject *o, PyObject *attr_name) 54 55 Retrieve an attribute named *attr_name* from object *o*. Returns the attribute 56 value on success, or ``NULL`` on failure. This is the equivalent of the Python 57 expression ``o.attr_name``. 58 59 60.. c:function:: PyObject* PyObject_GetAttrString(PyObject *o, const char *attr_name) 61 62 Retrieve an attribute named *attr_name* from object *o*. Returns the attribute 63 value on success, or ``NULL`` on failure. This is the equivalent of the Python 64 expression ``o.attr_name``. 65 66 67.. c:function:: PyObject* PyObject_GenericGetAttr(PyObject *o, PyObject *name) 68 69 Generic attribute getter function that is meant to be put into a type 70 object's ``tp_getattro`` slot. It looks for a descriptor in the dictionary 71 of classes in the object's MRO as well as an attribute in the object's 72 :attr:`~object.__dict__` (if present). As outlined in :ref:`descriptors`, 73 data descriptors take preference over instance attributes, while non-data 74 descriptors don't. Otherwise, an :exc:`AttributeError` is raised. 75 76 77.. c:function:: int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v) 78 79 Set the value of the attribute named *attr_name*, for object *o*, to the value 80 *v*. Raise an exception and return ``-1`` on failure; 81 return ``0`` on success. This is the equivalent of the Python statement 82 ``o.attr_name = v``. 83 84 If *v* is ``NULL``, the attribute is deleted. This behaviour is deprecated 85 in favour of using :c:func:`PyObject_DelAttr`, but there are currently no 86 plans to remove it. 87 88 89.. c:function:: int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v) 90 91 Set the value of the attribute named *attr_name*, for object *o*, to the value 92 *v*. Raise an exception and return ``-1`` on failure; 93 return ``0`` on success. This is the equivalent of the Python statement 94 ``o.attr_name = v``. 95 96 If *v* is ``NULL``, the attribute is deleted, however this feature is 97 deprecated in favour of using :c:func:`PyObject_DelAttrString`. 98 99 100.. c:function:: int PyObject_GenericSetAttr(PyObject *o, PyObject *name, PyObject *value) 101 102 Generic attribute setter and deleter function that is meant 103 to be put into a type object's :c:member:`~PyTypeObject.tp_setattro` 104 slot. It looks for a data descriptor in the 105 dictionary of classes in the object's MRO, and if found it takes preference 106 over setting or deleting the attribute in the instance dictionary. Otherwise, the 107 attribute is set or deleted in the object's :attr:`~object.__dict__` (if present). 108 On success, ``0`` is returned, otherwise an :exc:`AttributeError` 109 is raised and ``-1`` is returned. 110 111 112.. c:function:: int PyObject_DelAttr(PyObject *o, PyObject *attr_name) 113 114 Delete attribute named *attr_name*, for object *o*. Returns ``-1`` on failure. 115 This is the equivalent of the Python statement ``del o.attr_name``. 116 117 118.. c:function:: int PyObject_DelAttrString(PyObject *o, const char *attr_name) 119 120 Delete attribute named *attr_name*, for object *o*. Returns ``-1`` on failure. 121 This is the equivalent of the Python statement ``del o.attr_name``. 122 123 124.. c:function:: PyObject* PyObject_GenericGetDict(PyObject *o, void *context) 125 126 A generic implementation for the getter of a ``__dict__`` descriptor. It 127 creates the dictionary if necessary. 128 129 .. versionadded:: 3.3 130 131 132.. c:function:: int PyObject_GenericSetDict(PyObject *o, PyObject *value, void *context) 133 134 A generic implementation for the setter of a ``__dict__`` descriptor. This 135 implementation does not allow the dictionary to be deleted. 136 137 .. versionadded:: 3.3 138 139 140.. c:function:: PyObject* PyObject_RichCompare(PyObject *o1, PyObject *o2, int opid) 141 142 Compare the values of *o1* and *o2* using the operation specified by *opid*, 143 which must be one of :const:`Py_LT`, :const:`Py_LE`, :const:`Py_EQ`, 144 :const:`Py_NE`, :const:`Py_GT`, or :const:`Py_GE`, corresponding to ``<``, 145 ``<=``, ``==``, ``!=``, ``>``, or ``>=`` respectively. This is the equivalent of 146 the Python expression ``o1 op o2``, where ``op`` is the operator corresponding 147 to *opid*. Returns the value of the comparison on success, or ``NULL`` on failure. 148 149 150.. c:function:: int PyObject_RichCompareBool(PyObject *o1, PyObject *o2, int opid) 151 152 Compare the values of *o1* and *o2* using the operation specified by *opid*, 153 which must be one of :const:`Py_LT`, :const:`Py_LE`, :const:`Py_EQ`, 154 :const:`Py_NE`, :const:`Py_GT`, or :const:`Py_GE`, corresponding to ``<``, 155 ``<=``, ``==``, ``!=``, ``>``, or ``>=`` respectively. Returns ``-1`` on error, 156 ``0`` if the result is false, ``1`` otherwise. This is the equivalent of the 157 Python expression ``o1 op o2``, where ``op`` is the operator corresponding to 158 *opid*. 159 160.. note:: 161 If *o1* and *o2* are the same object, :c:func:`PyObject_RichCompareBool` 162 will always return ``1`` for :const:`Py_EQ` and ``0`` for :const:`Py_NE`. 163 164.. c:function:: PyObject* PyObject_Repr(PyObject *o) 165 166 .. index:: builtin: repr 167 168 Compute a string representation of object *o*. Returns the string 169 representation on success, ``NULL`` on failure. This is the equivalent of the 170 Python expression ``repr(o)``. Called by the :func:`repr` built-in function. 171 172 .. versionchanged:: 3.4 173 This function now includes a debug assertion to help ensure that it 174 does not silently discard an active exception. 175 176.. c:function:: PyObject* PyObject_ASCII(PyObject *o) 177 178 .. index:: builtin: ascii 179 180 As :c:func:`PyObject_Repr`, compute a string representation of object *o*, but 181 escape the non-ASCII characters in the string returned by 182 :c:func:`PyObject_Repr` with ``\x``, ``\u`` or ``\U`` escapes. This generates 183 a string similar to that returned by :c:func:`PyObject_Repr` in Python 2. 184 Called by the :func:`ascii` built-in function. 185 186 .. index:: string; PyObject_Str (C function) 187 188 189.. c:function:: PyObject* PyObject_Str(PyObject *o) 190 191 Compute a string representation of object *o*. Returns the string 192 representation on success, ``NULL`` on failure. This is the equivalent of the 193 Python expression ``str(o)``. Called by the :func:`str` built-in function 194 and, therefore, by the :func:`print` function. 195 196 .. versionchanged:: 3.4 197 This function now includes a debug assertion to help ensure that it 198 does not silently discard an active exception. 199 200 201.. c:function:: PyObject* PyObject_Bytes(PyObject *o) 202 203 .. index:: builtin: bytes 204 205 Compute a bytes representation of object *o*. ``NULL`` is returned on 206 failure and a bytes object on success. This is equivalent to the Python 207 expression ``bytes(o)``, when *o* is not an integer. Unlike ``bytes(o)``, 208 a TypeError is raised when *o* is an integer instead of a zero-initialized 209 bytes object. 210 211 212.. c:function:: int PyObject_IsSubclass(PyObject *derived, PyObject *cls) 213 214 Return ``1`` if the class *derived* is identical to or derived from the class 215 *cls*, otherwise return ``0``. In case of an error, return ``-1``. 216 217 If *cls* is a tuple, the check will be done against every entry in *cls*. 218 The result will be ``1`` when at least one of the checks returns ``1``, 219 otherwise it will be ``0``. 220 221 If *cls* has a :meth:`~class.__subclasscheck__` method, it will be called to 222 determine the subclass status as described in :pep:`3119`. Otherwise, 223 *derived* is a subclass of *cls* if it is a direct or indirect subclass, 224 i.e. contained in ``cls.__mro__``. 225 226 Normally only class objects, i.e. instances of :class:`type` or a derived 227 class, are considered classes. However, objects can override this by having 228 a :attr:`__bases__` attribute (which must be a tuple of base classes). 229 230 231.. c:function:: int PyObject_IsInstance(PyObject *inst, PyObject *cls) 232 233 Return ``1`` if *inst* is an instance of the class *cls* or a subclass of 234 *cls*, or ``0`` if not. On error, returns ``-1`` and sets an exception. 235 236 If *cls* is a tuple, the check will be done against every entry in *cls*. 237 The result will be ``1`` when at least one of the checks returns ``1``, 238 otherwise it will be ``0``. 239 240 If *cls* has a :meth:`~class.__instancecheck__` method, it will be called to 241 determine the subclass status as described in :pep:`3119`. Otherwise, *inst* 242 is an instance of *cls* if its class is a subclass of *cls*. 243 244 An instance *inst* can override what is considered its class by having a 245 :attr:`__class__` attribute. 246 247 An object *cls* can override if it is considered a class, and what its base 248 classes are, by having a :attr:`__bases__` attribute (which must be a tuple 249 of base classes). 250 251 252.. c:function:: Py_hash_t PyObject_Hash(PyObject *o) 253 254 .. index:: builtin: hash 255 256 Compute and return the hash value of an object *o*. On failure, return ``-1``. 257 This is the equivalent of the Python expression ``hash(o)``. 258 259 .. versionchanged:: 3.2 260 The return type is now Py_hash_t. This is a signed integer the same size 261 as Py_ssize_t. 262 263 264.. c:function:: Py_hash_t PyObject_HashNotImplemented(PyObject *o) 265 266 Set a :exc:`TypeError` indicating that ``type(o)`` is not hashable and return ``-1``. 267 This function receives special treatment when stored in a ``tp_hash`` slot, 268 allowing a type to explicitly indicate to the interpreter that it is not 269 hashable. 270 271 272.. c:function:: int PyObject_IsTrue(PyObject *o) 273 274 Returns ``1`` if the object *o* is considered to be true, and ``0`` otherwise. 275 This is equivalent to the Python expression ``not not o``. On failure, return 276 ``-1``. 277 278 279.. c:function:: int PyObject_Not(PyObject *o) 280 281 Returns ``0`` if the object *o* is considered to be true, and ``1`` otherwise. 282 This is equivalent to the Python expression ``not o``. On failure, return 283 ``-1``. 284 285 286.. c:function:: PyObject* PyObject_Type(PyObject *o) 287 288 .. index:: builtin: type 289 290 When *o* is non-``NULL``, returns a type object corresponding to the object type 291 of object *o*. On failure, raises :exc:`SystemError` and returns ``NULL``. This 292 is equivalent to the Python expression ``type(o)``. This function increments the 293 reference count of the return value. There's really no reason to use this 294 function instead of the common expression ``o->ob_type``, which returns a 295 pointer of type :c:type:`PyTypeObject*`, except when the incremented reference 296 count is needed. 297 298 299.. c:function:: int PyObject_TypeCheck(PyObject *o, PyTypeObject *type) 300 301 Return non-zero if the object *o* is of type *type* or a subtype of *type*, and 302 ``0`` otherwise. Both parameters must be non-``NULL``. 303 304 305.. c:function:: Py_ssize_t PyObject_Size(PyObject *o) 306 Py_ssize_t PyObject_Length(PyObject *o) 307 308 .. index:: builtin: len 309 310 Return the length of object *o*. If the object *o* provides either the sequence 311 and mapping protocols, the sequence length is returned. On error, ``-1`` is 312 returned. This is the equivalent to the Python expression ``len(o)``. 313 314 315.. c:function:: Py_ssize_t PyObject_LengthHint(PyObject *o, Py_ssize_t defaultvalue) 316 317 Return an estimated length for the object *o*. First try to return its 318 actual length, then an estimate using :meth:`~object.__length_hint__`, and 319 finally return the default value. On error return ``-1``. This is the 320 equivalent to the Python expression ``operator.length_hint(o, defaultvalue)``. 321 322 .. versionadded:: 3.4 323 324 325.. c:function:: PyObject* PyObject_GetItem(PyObject *o, PyObject *key) 326 327 Return element of *o* corresponding to the object *key* or ``NULL`` on failure. 328 This is the equivalent of the Python expression ``o[key]``. 329 330 331.. c:function:: int PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v) 332 333 Map the object *key* to the value *v*. Raise an exception and 334 return ``-1`` on failure; return ``0`` on success. This is the 335 equivalent of the Python statement ``o[key] = v``. This function *does 336 not* steal a reference to *v*. 337 338 339.. c:function:: int PyObject_DelItem(PyObject *o, PyObject *key) 340 341 Remove the mapping for the object *key* from the object *o*. Return ``-1`` 342 on failure. This is equivalent to the Python statement ``del o[key]``. 343 344 345.. c:function:: PyObject* PyObject_Dir(PyObject *o) 346 347 This is equivalent to the Python expression ``dir(o)``, returning a (possibly 348 empty) list of strings appropriate for the object argument, or ``NULL`` if there 349 was an error. If the argument is ``NULL``, this is like the Python ``dir()``, 350 returning the names of the current locals; in this case, if no execution frame 351 is active then ``NULL`` is returned but :c:func:`PyErr_Occurred` will return false. 352 353 354.. c:function:: PyObject* PyObject_GetIter(PyObject *o) 355 356 This is equivalent to the Python expression ``iter(o)``. It returns a new 357 iterator for the object argument, or the object itself if the object is already 358 an iterator. Raises :exc:`TypeError` and returns ``NULL`` if the object cannot be 359 iterated. 360 361 362.. c:function:: PyObject* PyObject_GetAIter(PyObject *o) 363 364 This is the equivalent to the Python expression ``aiter(o)``. Takes an 365 :class:`AsyncIterable` object and returns an :class:`AsyncIterator` for it. 366 This is typically a new iterator but if the argument is an 367 :class:`AsyncIterator`, this returns itself. Raises :exc:`TypeError` and 368 returns ``NULL`` if the object cannot be iterated. 369 370 .. versionadded:: 3.10 371