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