Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1 | .. highlightlang:: c |
| 2 | |
| 3 | .. _object: |
| 4 | |
| 5 | Object Protocol |
| 6 | =============== |
| 7 | |
| 8 | |
Brian Curtin | 4928107 | 2011-08-11 09:41:31 -0500 | [diff] [blame] | 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 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 22 | .. c:function:: int PyObject_Print(PyObject *o, FILE *fp, int flags) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 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 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 30 | .. c:function:: int PyObject_HasAttr(PyObject *o, PyObject *attr_name) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 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 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 37 | .. c:function:: int PyObject_HasAttrString(PyObject *o, const char *attr_name) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 38 | |
| 39 | Returns ``1`` if *o* has the attribute *attr_name*, and ``0`` otherwise. This |
| 40 | is equivalent to the Python expression ``hasattr(o, attr_name)``. This function |
| 41 | always succeeds. |
| 42 | |
| 43 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 44 | .. c:function:: PyObject* PyObject_GetAttr(PyObject *o, PyObject *attr_name) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 45 | |
| 46 | Retrieve an attribute named *attr_name* from object *o*. Returns the attribute |
| 47 | value on success, or *NULL* on failure. This is the equivalent of the Python |
| 48 | expression ``o.attr_name``. |
| 49 | |
| 50 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 51 | .. c:function:: PyObject* PyObject_GetAttrString(PyObject *o, const char *attr_name) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 52 | |
| 53 | Retrieve an attribute named *attr_name* from object *o*. Returns the attribute |
| 54 | value on success, or *NULL* on failure. This is the equivalent of the Python |
| 55 | expression ``o.attr_name``. |
| 56 | |
| 57 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 58 | .. c:function:: PyObject* PyObject_GenericGetAttr(PyObject *o, PyObject *name) |
Benjamin Peterson | d23f822 | 2009-04-05 19:13:16 +0000 | [diff] [blame] | 59 | |
| 60 | Generic attribute getter function that is meant to be put into a type |
| 61 | object's ``tp_getattro`` slot. It looks for a descriptor in the dictionary |
| 62 | of classes in the object's MRO as well as an attribute in the object's |
Serhiy Storchaka | 0b68a2d | 2013-10-09 13:26:17 +0300 | [diff] [blame] | 63 | :attr:`~object.__dict__` (if present). As outlined in :ref:`descriptors`, |
| 64 | data descriptors take preference over instance attributes, while non-data |
Benjamin Peterson | d23f822 | 2009-04-05 19:13:16 +0000 | [diff] [blame] | 65 | descriptors don't. Otherwise, an :exc:`AttributeError` is raised. |
| 66 | |
| 67 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 68 | .. c:function:: int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 69 | |
| 70 | Set the value of the attribute named *attr_name*, for object *o*, to the value |
Martin Panter | 45be8d6 | 2015-12-08 00:03:20 +0000 | [diff] [blame] | 71 | *v*. Raise an exception and return ``-1`` on failure; |
| 72 | return ``0`` on success. This is the equivalent of the Python statement |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 73 | ``o.attr_name = v``. |
| 74 | |
Martin Panter | 45be8d6 | 2015-12-08 00:03:20 +0000 | [diff] [blame] | 75 | If *v* is *NULL*, the attribute is deleted, however this feature is |
| 76 | deprecated in favour of using :c:func:`PyObject_DelAttr`. |
| 77 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 78 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 79 | .. c:function:: int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 80 | |
| 81 | Set the value of the attribute named *attr_name*, for object *o*, to the value |
Martin Panter | 45be8d6 | 2015-12-08 00:03:20 +0000 | [diff] [blame] | 82 | *v*. Raise an exception and return ``-1`` on failure; |
| 83 | return ``0`` on success. This is the equivalent of the Python statement |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 84 | ``o.attr_name = v``. |
| 85 | |
Martin Panter | 45be8d6 | 2015-12-08 00:03:20 +0000 | [diff] [blame] | 86 | If *v* is *NULL*, the attribute is deleted, however this feature is |
| 87 | deprecated in favour of using :c:func:`PyObject_DelAttrString`. |
| 88 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 89 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 90 | .. c:function:: int PyObject_GenericSetAttr(PyObject *o, PyObject *name, PyObject *value) |
Benjamin Peterson | d23f822 | 2009-04-05 19:13:16 +0000 | [diff] [blame] | 91 | |
Martin Panter | 45be8d6 | 2015-12-08 00:03:20 +0000 | [diff] [blame] | 92 | Generic attribute setter and deleter function that is meant |
| 93 | to be put into a type object's :c:member:`~PyTypeObject.tp_setattro` |
| 94 | slot. It looks for a data descriptor in the |
Benjamin Peterson | d23f822 | 2009-04-05 19:13:16 +0000 | [diff] [blame] | 95 | dictionary of classes in the object's MRO, and if found it takes preference |
Martin Panter | 45be8d6 | 2015-12-08 00:03:20 +0000 | [diff] [blame] | 96 | over setting or deleting the attribute in the instance dictionary. Otherwise, the |
| 97 | attribute is set or deleted in the object's :attr:`~object.__dict__` (if present). |
| 98 | On success, ``0`` is returned, otherwise an :exc:`AttributeError` |
| 99 | is raised and ``-1`` is returned. |
Benjamin Peterson | d23f822 | 2009-04-05 19:13:16 +0000 | [diff] [blame] | 100 | |
| 101 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 102 | .. c:function:: int PyObject_DelAttr(PyObject *o, PyObject *attr_name) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 103 | |
| 104 | Delete attribute named *attr_name*, for object *o*. Returns ``-1`` on failure. |
| 105 | This is the equivalent of the Python statement ``del o.attr_name``. |
| 106 | |
| 107 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 108 | .. c:function:: int PyObject_DelAttrString(PyObject *o, const char *attr_name) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 109 | |
| 110 | Delete attribute named *attr_name*, for object *o*. Returns ``-1`` on failure. |
| 111 | This is the equivalent of the Python statement ``del o.attr_name``. |
| 112 | |
| 113 | |
Benjamin Peterson | 1c262a6 | 2014-10-05 21:20:36 -0400 | [diff] [blame] | 114 | .. c:function:: PyObject* PyObject_GenericGetDict(PyObject *o, void *context) |
Benjamin Peterson | 8eb1269 | 2012-02-19 19:59:10 -0500 | [diff] [blame] | 115 | |
| 116 | A generic implementation for the getter of a ``__dict__`` descriptor. It |
| 117 | creates the dictionary if necessary. |
| 118 | |
Benjamin Peterson | 4384435 | 2012-02-20 08:48:25 -0500 | [diff] [blame] | 119 | .. versionadded:: 3.3 |
| 120 | |
Benjamin Peterson | 8eb1269 | 2012-02-19 19:59:10 -0500 | [diff] [blame] | 121 | |
Benjamin Peterson | 1c262a6 | 2014-10-05 21:20:36 -0400 | [diff] [blame] | 122 | .. c:function:: int PyObject_GenericSetDict(PyObject *o, void *context) |
Benjamin Peterson | 8eb1269 | 2012-02-19 19:59:10 -0500 | [diff] [blame] | 123 | |
| 124 | A generic implementation for the setter of a ``__dict__`` descriptor. This |
| 125 | implementation does not allow the dictionary to be deleted. |
| 126 | |
Benjamin Peterson | 4384435 | 2012-02-20 08:48:25 -0500 | [diff] [blame] | 127 | .. versionadded:: 3.3 |
| 128 | |
Benjamin Peterson | 8eb1269 | 2012-02-19 19:59:10 -0500 | [diff] [blame] | 129 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 130 | .. c:function:: PyObject* PyObject_RichCompare(PyObject *o1, PyObject *o2, int opid) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 131 | |
| 132 | Compare the values of *o1* and *o2* using the operation specified by *opid*, |
| 133 | which must be one of :const:`Py_LT`, :const:`Py_LE`, :const:`Py_EQ`, |
| 134 | :const:`Py_NE`, :const:`Py_GT`, or :const:`Py_GE`, corresponding to ``<``, |
| 135 | ``<=``, ``==``, ``!=``, ``>``, or ``>=`` respectively. This is the equivalent of |
| 136 | the Python expression ``o1 op o2``, where ``op`` is the operator corresponding |
| 137 | to *opid*. Returns the value of the comparison on success, or *NULL* on failure. |
| 138 | |
| 139 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 140 | .. c:function:: int PyObject_RichCompareBool(PyObject *o1, PyObject *o2, int opid) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 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. Returns ``-1`` on error, |
| 146 | ``0`` if the result is false, ``1`` otherwise. This is the equivalent of the |
| 147 | Python expression ``o1 op o2``, where ``op`` is the operator corresponding to |
| 148 | *opid*. |
| 149 | |
Eli Bendersky | ad30c42 | 2011-01-15 10:23:34 +0000 | [diff] [blame] | 150 | .. note:: |
| 151 | If *o1* and *o2* are the same object, :c:func:`PyObject_RichCompareBool` |
| 152 | will always return ``1`` for :const:`Py_EQ` and ``0`` for :const:`Py_NE`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 153 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 154 | .. c:function:: PyObject* PyObject_Repr(PyObject *o) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 155 | |
| 156 | .. index:: builtin: repr |
| 157 | |
| 158 | Compute a string representation of object *o*. Returns the string |
| 159 | representation on success, *NULL* on failure. This is the equivalent of the |
Georg Brandl | 559e5d7 | 2008-06-11 18:37:52 +0000 | [diff] [blame] | 160 | Python expression ``repr(o)``. Called by the :func:`repr` built-in function. |
| 161 | |
Nick Coghlan | c0bc0b4 | 2014-02-09 12:00:01 +1000 | [diff] [blame] | 162 | .. versionchanged:: 3.4 |
| 163 | This function now includes a debug assertion to help ensure that it |
| 164 | does not silently discard an active exception. |
Georg Brandl | 559e5d7 | 2008-06-11 18:37:52 +0000 | [diff] [blame] | 165 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 166 | .. c:function:: PyObject* PyObject_ASCII(PyObject *o) |
Georg Brandl | 559e5d7 | 2008-06-11 18:37:52 +0000 | [diff] [blame] | 167 | |
| 168 | .. index:: builtin: ascii |
| 169 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 170 | As :c:func:`PyObject_Repr`, compute a string representation of object *o*, but |
Georg Brandl | 559e5d7 | 2008-06-11 18:37:52 +0000 | [diff] [blame] | 171 | escape the non-ASCII characters in the string returned by |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 172 | :c:func:`PyObject_Repr` with ``\x``, ``\u`` or ``\U`` escapes. This generates |
| 173 | a string similar to that returned by :c:func:`PyObject_Repr` in Python 2. |
Georg Brandl | 559e5d7 | 2008-06-11 18:37:52 +0000 | [diff] [blame] | 174 | Called by the :func:`ascii` built-in function. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 175 | |
Chris Jerdonek | bb4e941 | 2012-11-28 01:38:40 -0800 | [diff] [blame] | 176 | .. index:: string; PyObject_Str (C function) |
| 177 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 178 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 179 | .. c:function:: PyObject* PyObject_Str(PyObject *o) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 180 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 181 | Compute a string representation of object *o*. Returns the string |
| 182 | representation on success, *NULL* on failure. This is the equivalent of the |
| 183 | Python expression ``str(o)``. Called by the :func:`str` built-in function |
| 184 | and, therefore, by the :func:`print` function. |
| 185 | |
Nick Coghlan | 3d7b364 | 2014-02-09 10:57:34 +1000 | [diff] [blame] | 186 | .. versionchanged:: 3.4 |
Nick Coghlan | c0bc0b4 | 2014-02-09 12:00:01 +1000 | [diff] [blame] | 187 | This function now includes a debug assertion to help ensure that it |
| 188 | does not silently discard an active exception. |
Nick Coghlan | 3d7b364 | 2014-02-09 10:57:34 +1000 | [diff] [blame] | 189 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 190 | .. c:function:: PyObject* PyObject_Bytes(PyObject *o) |
Benjamin Peterson | c15a073 | 2008-08-26 16:46:47 +0000 | [diff] [blame] | 191 | |
| 192 | .. index:: builtin: bytes |
| 193 | |
Alexandre Vassalotti | eb6f8de | 2009-12-31 03:56:09 +0000 | [diff] [blame] | 194 | Compute a bytes representation of object *o*. *NULL* is returned on |
| 195 | failure and a bytes object on success. This is equivalent to the Python |
| 196 | expression ``bytes(o)``, when *o* is not an integer. Unlike ``bytes(o)``, |
| 197 | a TypeError is raised when *o* is an integer instead of a zero-initialized |
| 198 | bytes object. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 199 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 200 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 201 | .. c:function:: int PyObject_IsSubclass(PyObject *derived, PyObject *cls) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 202 | |
Georg Brandl | f6d6dc2 | 2014-10-06 14:38:53 +0200 | [diff] [blame] | 203 | Return ``1`` if the class *derived* is identical to or derived from the class |
| 204 | *cls*, otherwise return ``0``. In case of an error, return ``-1``. |
| 205 | |
| 206 | If *cls* is a tuple, the check will be done against every entry in *cls*. |
| 207 | The result will be ``1`` when at least one of the checks returns ``1``, |
| 208 | otherwise it will be ``0``. |
| 209 | |
| 210 | If *cls* has a :meth:`~class.__subclasscheck__` method, it will be called to |
| 211 | determine the subclass status as described in :pep:`3119`. Otherwise, |
| 212 | *derived* is a subclass of *cls* if it is a direct or indirect subclass, |
| 213 | i.e. contained in ``cls.__mro__``. |
| 214 | |
| 215 | Normally only class objects, i.e. instances of :class:`type` or a derived |
Serhiy Storchaka | a7db057 | 2015-05-02 19:24:41 +0300 | [diff] [blame] | 216 | class, are considered classes. However, objects can override this by having |
Georg Brandl | f6d6dc2 | 2014-10-06 14:38:53 +0200 | [diff] [blame] | 217 | a :attr:`__bases__` attribute (which must be a tuple of base classes). |
| 218 | |
| 219 | |
| 220 | .. c:function:: int PyObject_IsInstance(PyObject *inst, PyObject *cls) |
| 221 | |
| 222 | Return ``1`` if *inst* is an instance of the class *cls* or a subclass of |
| 223 | *cls*, or ``0`` if not. On error, returns ``-1`` and sets an exception. |
| 224 | |
| 225 | If *cls* is a tuple, the check will be done against every entry in *cls*. |
| 226 | The result will be ``1`` when at least one of the checks returns ``1``, |
| 227 | otherwise it will be ``0``. |
| 228 | |
| 229 | If *cls* has a :meth:`~class.__instancecheck__` method, it will be called to |
| 230 | determine the subclass status as described in :pep:`3119`. Otherwise, *inst* |
| 231 | is an instance of *cls* if its class is a subclass of *cls*. |
| 232 | |
| 233 | An instance *inst* can override what is considered its class by having a |
| 234 | :attr:`__class__` attribute. |
| 235 | |
| 236 | An object *cls* can override if it is considered a class, and what its base |
| 237 | classes are, by having a :attr:`__bases__` attribute (which must be a tuple |
| 238 | of base classes). |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 239 | |
| 240 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 241 | .. c:function:: int PyCallable_Check(PyObject *o) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 242 | |
| 243 | Determine if the object *o* is callable. Return ``1`` if the object is callable |
| 244 | and ``0`` otherwise. This function always succeeds. |
| 245 | |
| 246 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 247 | .. c:function:: PyObject* PyObject_Call(PyObject *callable_object, PyObject *args, PyObject *kw) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 248 | |
| 249 | Call a callable Python object *callable_object*, with arguments given by the |
| 250 | tuple *args*, and named arguments given by the dictionary *kw*. If no named |
| 251 | arguments are needed, *kw* may be *NULL*. *args* must not be *NULL*, use an |
| 252 | empty tuple if no arguments are needed. Returns the result of the call on |
| 253 | success, or *NULL* on failure. This is the equivalent of the Python expression |
| 254 | ``callable_object(*args, **kw)``. |
| 255 | |
| 256 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 257 | .. c:function:: PyObject* PyObject_CallObject(PyObject *callable_object, PyObject *args) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 258 | |
| 259 | Call a callable Python object *callable_object*, with arguments given by the |
| 260 | tuple *args*. If no arguments are needed, then *args* may be *NULL*. Returns |
| 261 | the result of the call on success, or *NULL* on failure. This is the equivalent |
| 262 | of the Python expression ``callable_object(*args)``. |
| 263 | |
| 264 | |
Serhiy Storchaka | 1cfebc7 | 2013-05-29 18:50:54 +0300 | [diff] [blame] | 265 | .. c:function:: PyObject* PyObject_CallFunction(PyObject *callable, const char *format, ...) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 266 | |
| 267 | Call a callable Python object *callable*, with a variable number of C arguments. |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 268 | The C arguments are described using a :c:func:`Py_BuildValue` style format |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 269 | string. The format may be *NULL*, indicating that no arguments are provided. |
| 270 | Returns the result of the call on success, or *NULL* on failure. This is the |
| 271 | equivalent of the Python expression ``callable(*args)``. Note that if you only |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 272 | pass :c:type:`PyObject \*` args, :c:func:`PyObject_CallFunctionObjArgs` is a |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 273 | faster alternative. |
| 274 | |
Serhiy Storchaka | 1cfebc7 | 2013-05-29 18:50:54 +0300 | [diff] [blame] | 275 | .. versionchanged:: 3.4 |
| 276 | The type of *format* was changed from ``char *``. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 277 | |
Serhiy Storchaka | 1cfebc7 | 2013-05-29 18:50:54 +0300 | [diff] [blame] | 278 | |
| 279 | .. c:function:: PyObject* PyObject_CallMethod(PyObject *o, const char *method, const char *format, ...) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 280 | |
| 281 | Call the method named *method* of object *o* with a variable number of C |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 282 | arguments. The C arguments are described by a :c:func:`Py_BuildValue` format |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 283 | string that should produce a tuple. The format may be *NULL*, indicating that |
| 284 | no arguments are provided. Returns the result of the call on success, or *NULL* |
| 285 | on failure. This is the equivalent of the Python expression ``o.method(args)``. |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 286 | Note that if you only pass :c:type:`PyObject \*` args, |
| 287 | :c:func:`PyObject_CallMethodObjArgs` is a faster alternative. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 288 | |
Serhiy Storchaka | 1cfebc7 | 2013-05-29 18:50:54 +0300 | [diff] [blame] | 289 | .. versionchanged:: 3.4 |
| 290 | The types of *method* and *format* were changed from ``char *``. |
| 291 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 292 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 293 | .. c:function:: PyObject* PyObject_CallFunctionObjArgs(PyObject *callable, ..., NULL) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 294 | |
| 295 | Call a callable Python object *callable*, with a variable number of |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 296 | :c:type:`PyObject\*` arguments. The arguments are provided as a variable number |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 297 | of parameters followed by *NULL*. Returns the result of the call on success, or |
| 298 | *NULL* on failure. |
| 299 | |
| 300 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 301 | .. c:function:: PyObject* PyObject_CallMethodObjArgs(PyObject *o, PyObject *name, ..., NULL) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 302 | |
| 303 | Calls a method of the object *o*, where the name of the method is given as a |
| 304 | Python string object in *name*. It is called with a variable number of |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 305 | :c:type:`PyObject\*` arguments. The arguments are provided as a variable number |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 306 | of parameters followed by *NULL*. Returns the result of the call on success, or |
| 307 | *NULL* on failure. |
| 308 | |
| 309 | |
Benjamin Peterson | 8f67d08 | 2010-10-17 20:54:53 +0000 | [diff] [blame] | 310 | .. c:function:: Py_hash_t PyObject_Hash(PyObject *o) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 311 | |
| 312 | .. index:: builtin: hash |
| 313 | |
| 314 | Compute and return the hash value of an object *o*. On failure, return ``-1``. |
| 315 | This is the equivalent of the Python expression ``hash(o)``. |
| 316 | |
Benjamin Peterson | 8f67d08 | 2010-10-17 20:54:53 +0000 | [diff] [blame] | 317 | .. versionchanged:: 3.2 |
Benjamin Peterson | 8f67d08 | 2010-10-17 20:54:53 +0000 | [diff] [blame] | 318 | The return type is now Py_hash_t. This is a signed integer the same size |
| 319 | as Py_ssize_t. |
| 320 | |
| 321 | |
| 322 | .. c:function:: Py_hash_t PyObject_HashNotImplemented(PyObject *o) |
Nick Coghlan | 7a70a3a | 2008-08-18 13:18:16 +0000 | [diff] [blame] | 323 | |
Benjamin Peterson | e5384b0 | 2008-10-04 22:00:42 +0000 | [diff] [blame] | 324 | Set a :exc:`TypeError` indicating that ``type(o)`` is not hashable and return ``-1``. |
Nick Coghlan | 7a70a3a | 2008-08-18 13:18:16 +0000 | [diff] [blame] | 325 | This function receives special treatment when stored in a ``tp_hash`` slot, |
Benjamin Peterson | c4fe6f3 | 2008-08-19 18:57:56 +0000 | [diff] [blame] | 326 | allowing a type to explicitly indicate to the interpreter that it is not |
Nick Coghlan | 7a70a3a | 2008-08-18 13:18:16 +0000 | [diff] [blame] | 327 | hashable. |
| 328 | |
Nick Coghlan | 7a70a3a | 2008-08-18 13:18:16 +0000 | [diff] [blame] | 329 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 330 | .. c:function:: int PyObject_IsTrue(PyObject *o) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 331 | |
| 332 | Returns ``1`` if the object *o* is considered to be true, and ``0`` otherwise. |
| 333 | This is equivalent to the Python expression ``not not o``. On failure, return |
| 334 | ``-1``. |
| 335 | |
| 336 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 337 | .. c:function:: int PyObject_Not(PyObject *o) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 338 | |
| 339 | Returns ``0`` if the object *o* is considered to be true, and ``1`` otherwise. |
| 340 | This is equivalent to the Python expression ``not o``. On failure, return |
| 341 | ``-1``. |
| 342 | |
| 343 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 344 | .. c:function:: PyObject* PyObject_Type(PyObject *o) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 345 | |
| 346 | .. index:: builtin: type |
| 347 | |
| 348 | When *o* is non-*NULL*, returns a type object corresponding to the object type |
| 349 | of object *o*. On failure, raises :exc:`SystemError` and returns *NULL*. This |
| 350 | is equivalent to the Python expression ``type(o)``. This function increments the |
| 351 | reference count of the return value. There's really no reason to use this |
| 352 | function instead of the common expression ``o->ob_type``, which returns a |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 353 | pointer of type :c:type:`PyTypeObject\*`, except when the incremented reference |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 354 | count is needed. |
| 355 | |
| 356 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 357 | .. c:function:: int PyObject_TypeCheck(PyObject *o, PyTypeObject *type) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 358 | |
| 359 | Return true if the object *o* is of type *type* or a subtype of *type*. Both |
| 360 | parameters must be non-*NULL*. |
| 361 | |
| 362 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 363 | .. c:function:: Py_ssize_t PyObject_Length(PyObject *o) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 364 | Py_ssize_t PyObject_Size(PyObject *o) |
| 365 | |
| 366 | .. index:: builtin: len |
| 367 | |
| 368 | Return the length of object *o*. If the object *o* provides either the sequence |
| 369 | and mapping protocols, the sequence length is returned. On error, ``-1`` is |
| 370 | returned. This is the equivalent to the Python expression ``len(o)``. |
| 371 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 372 | |
Armin Ronacher | aa9a79d | 2012-10-06 14:03:24 +0200 | [diff] [blame] | 373 | .. c:function:: Py_ssize_t PyObject_LengthHint(PyObject *o, Py_ssize_t default) |
| 374 | |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 375 | Return an estimated length for the object *o*. First try to return its |
| 376 | actual length, then an estimate using :meth:`~object.__length_hint__`, and |
| 377 | finally return the default value. On error return ``-1``. This is the |
Armin Ronacher | aa9a79d | 2012-10-06 14:03:24 +0200 | [diff] [blame] | 378 | equivalent to the Python expression ``operator.length_hint(o, default)``. |
| 379 | |
Armin Ronacher | 74b38b1 | 2012-10-07 10:29:32 +0200 | [diff] [blame] | 380 | .. versionadded:: 3.4 |
| 381 | |
Georg Brandl | df48b97 | 2014-03-24 09:06:18 +0100 | [diff] [blame] | 382 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 383 | .. c:function:: PyObject* PyObject_GetItem(PyObject *o, PyObject *key) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 384 | |
| 385 | Return element of *o* corresponding to the object *key* or *NULL* on failure. |
| 386 | This is the equivalent of the Python expression ``o[key]``. |
| 387 | |
| 388 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 389 | .. c:function:: int PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 390 | |
Martin Panter | 45be8d6 | 2015-12-08 00:03:20 +0000 | [diff] [blame] | 391 | Map the object *key* to the value *v*. Raise an exception and |
| 392 | return ``-1`` on failure; return ``0`` on success. This is the |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 393 | equivalent of the Python statement ``o[key] = v``. |
| 394 | |
| 395 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 396 | .. c:function:: int PyObject_DelItem(PyObject *o, PyObject *key) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 397 | |
| 398 | Delete the mapping for *key* from *o*. Returns ``-1`` on failure. This is the |
| 399 | equivalent of the Python statement ``del o[key]``. |
| 400 | |
| 401 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 402 | .. c:function:: PyObject* PyObject_Dir(PyObject *o) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 403 | |
| 404 | This is equivalent to the Python expression ``dir(o)``, returning a (possibly |
| 405 | empty) list of strings appropriate for the object argument, or *NULL* if there |
| 406 | was an error. If the argument is *NULL*, this is like the Python ``dir()``, |
| 407 | returning the names of the current locals; in this case, if no execution frame |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 408 | is active then *NULL* is returned but :c:func:`PyErr_Occurred` will return false. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 409 | |
| 410 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 411 | .. c:function:: PyObject* PyObject_GetIter(PyObject *o) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 412 | |
| 413 | This is equivalent to the Python expression ``iter(o)``. It returns a new |
| 414 | iterator for the object argument, or the object itself if the object is already |
| 415 | an iterator. Raises :exc:`TypeError` and returns *NULL* if the object cannot be |
| 416 | iterated. |