path: root/devdocs/python~3.12/c-api%2Fobject.html

 <span id="object"></span><h1>Object Protocol</h1> <dl class="c var"> <dt class="sig sig-object c" id="c.Py_NotImplemented">
<code>PyObject *Py_NotImplemented</code> </dt> <dd>
<p>The <code>NotImplemented</code> singleton, used to signal that an operation is not implemented for the given type combination.</p> </dd>
</dl> <dl class="c macro"> <dt class="sig sig-object c" id="c.Py_RETURN_NOTIMPLEMENTED">
<code>Py_RETURN_NOTIMPLEMENTED</code> </dt> <dd>
<p>Properly handle returning <a class="reference internal" href="#c.Py_NotImplemented" title="Py_NotImplemented"><code>Py_NotImplemented</code></a> from within a C function (that is, create a new <a class="reference internal" href="../glossary#term-strong-reference"><span class="xref std std-term">strong reference</span></a> to NotImplemented and return it).</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyObject_Print">
<code>int PyObject_Print(PyObject *o, FILE *fp, int flags)</code> </dt> <dd>
<p>Print an object <em>o</em>, on file <em>fp</em>. Returns <code>-1</code> on error. The flags argument is used to enable certain printing options. The only option currently supported is <code>Py_PRINT_RAW</code>; if given, the <a class="reference internal" href="../library/stdtypes#str" title="str"><code>str()</code></a> of the object is written instead of the <a class="reference internal" href="../library/functions#repr" title="repr"><code>repr()</code></a>.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyObject_HasAttr">
<code>int PyObject_HasAttr(PyObject *o, PyObject *attr_name)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Returns <code>1</code> if <em>o</em> has the attribute <em>attr_name</em>, and <code>0</code> otherwise. This is equivalent to the Python expression <code>hasattr(o, attr_name)</code>. This function always succeeds.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>Exceptions that occur when this calls <a class="reference internal" href="../reference/datamodel#object.__getattr__" title="object.__getattr__"><code>__getattr__()</code></a> and <a class="reference internal" href="../reference/datamodel#object.__getattribute__" title="object.__getattribute__"><code>__getattribute__()</code></a> methods are silently ignored. For proper error handling, use <a class="reference internal" href="#c.PyObject_GetAttr" title="PyObject_GetAttr"><code>PyObject_GetAttr()</code></a> instead.</p> </div> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyObject_HasAttrString">
<code>int PyObject_HasAttrString(PyObject *o, const char *attr_name)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>This is the same as <a class="reference internal" href="#c.PyObject_HasAttr" title="PyObject_HasAttr"><code>PyObject_HasAttr()</code></a>, but <em>attr_name</em> is specified as a <span class="c-expr sig sig-inline c"><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="p">*</span></span> UTF-8 encoded bytes string, rather than a <span class="c-expr sig sig-inline c"><a class="reference internal" href="structures#c.PyObject" title="PyObject"><span class="n">PyObject</span></a><span class="p">*</span></span>.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>Exceptions that occur when this calls <a class="reference internal" href="../reference/datamodel#object.__getattr__" title="object.__getattr__"><code>__getattr__()</code></a> and <a class="reference internal" href="../reference/datamodel#object.__getattribute__" title="object.__getattribute__"><code>__getattribute__()</code></a> methods or while creating the temporary <a class="reference internal" href="../library/stdtypes#str" title="str"><code>str</code></a> object are silently ignored. For proper error handling, use <a class="reference internal" href="#c.PyObject_GetAttrString" title="PyObject_GetAttrString"><code>PyObject_GetAttrString()</code></a> instead.</p> </div> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyObject_GetAttr">
<code>PyObject *PyObject_GetAttr(PyObject *o, PyObject *attr_name)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Retrieve an attribute named <em>attr_name</em> from object <em>o</em>. Returns the attribute value on success, or <code>NULL</code> on failure. This is the equivalent of the Python expression <code>o.attr_name</code>.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyObject_GetAttrString">
<code>PyObject *PyObject_GetAttrString(PyObject *o, const char *attr_name)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>This is the same as <a class="reference internal" href="#c.PyObject_GetAttr" title="PyObject_GetAttr"><code>PyObject_GetAttr()</code></a>, but <em>attr_name</em> is specified as a <span class="c-expr sig sig-inline c"><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="p">*</span></span> UTF-8 encoded bytes string, rather than a <span class="c-expr sig sig-inline c"><a class="reference internal" href="structures#c.PyObject" title="PyObject"><span class="n">PyObject</span></a><span class="p">*</span></span>.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyObject_GenericGetAttr">
<code>PyObject *PyObject_GenericGetAttr(PyObject *o, PyObject *name)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Generic attribute getter function that is meant to be put into a type object’s <code>tp_getattro</code> slot. It looks for a descriptor in the dictionary of classes in the object’s MRO as well as an attribute in the object’s <a class="reference internal" href="../library/stdtypes#object.__dict__" title="object.__dict__"><code>__dict__</code></a> (if present). As outlined in <a class="reference internal" href="../reference/datamodel#descriptors"><span class="std std-ref">Implementing Descriptors</span></a>, data descriptors take preference over instance attributes, while non-data descriptors don’t. Otherwise, an <a class="reference internal" href="../library/exceptions#AttributeError" title="AttributeError"><code>AttributeError</code></a> is raised.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyObject_SetAttr">
<code>int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Set the value of the attribute named <em>attr_name</em>, for object <em>o</em>, to the value <em>v</em>. Raise an exception and return <code>-1</code> on failure; return <code>0</code> on success. This is the equivalent of the Python statement <code>o.attr_name = v</code>.</p> <p>If <em>v</em> is <code>NULL</code>, the attribute is deleted. This behaviour is deprecated in favour of using <a class="reference internal" href="#c.PyObject_DelAttr" title="PyObject_DelAttr"><code>PyObject_DelAttr()</code></a>, but there are currently no plans to remove it.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyObject_SetAttrString">
<code>int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>This is the same as <a class="reference internal" href="#c.PyObject_SetAttr" title="PyObject_SetAttr"><code>PyObject_SetAttr()</code></a>, but <em>attr_name</em> is specified as a <span class="c-expr sig sig-inline c"><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="p">*</span></span> UTF-8 encoded bytes string, rather than a <span class="c-expr sig sig-inline c"><a class="reference internal" href="structures#c.PyObject" title="PyObject"><span class="n">PyObject</span></a><span class="p">*</span></span>.</p> <p>If <em>v</em> is <code>NULL</code>, the attribute is deleted, but this feature is deprecated in favour of using <a class="reference internal" href="#c.PyObject_DelAttrString" title="PyObject_DelAttrString"><code>PyObject_DelAttrString()</code></a>.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyObject_GenericSetAttr">
<code>int PyObject_GenericSetAttr(PyObject *o, PyObject *name, PyObject *value)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Generic attribute setter and deleter function that is meant to be put into a type object’s <a class="reference internal" href="typeobj#c.PyTypeObject.tp_setattro" title="PyTypeObject.tp_setattro"><code>tp_setattro</code></a> slot. It looks for a data descriptor in the dictionary of classes in the object’s MRO, and if found it takes preference over setting or deleting the attribute in the instance dictionary. Otherwise, the attribute is set or deleted in the object’s <a class="reference internal" href="../library/stdtypes#object.__dict__" title="object.__dict__"><code>__dict__</code></a> (if present). On success, <code>0</code> is returned, otherwise an <a class="reference internal" href="../library/exceptions#AttributeError" title="AttributeError"><code>AttributeError</code></a> is raised and <code>-1</code> is returned.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyObject_DelAttr">
<code>int PyObject_DelAttr(PyObject *o, PyObject *attr_name)</code> </dt> <dd>
<p>Delete attribute named <em>attr_name</em>, for object <em>o</em>. Returns <code>-1</code> on failure. This is the equivalent of the Python statement <code>del o.attr_name</code>.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyObject_DelAttrString">
<code>int PyObject_DelAttrString(PyObject *o, const char *attr_name)</code> </dt> <dd>
<p>This is the same as <a class="reference internal" href="#c.PyObject_DelAttr" title="PyObject_DelAttr"><code>PyObject_DelAttr()</code></a>, but <em>attr_name</em> is specified as a <span class="c-expr sig sig-inline c"><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="p">*</span></span> UTF-8 encoded bytes string, rather than a <span class="c-expr sig sig-inline c"><a class="reference internal" href="structures#c.PyObject" title="PyObject"><span class="n">PyObject</span></a><span class="p">*</span></span>.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyObject_GenericGetDict">
<code>PyObject *PyObject_GenericGetDict(PyObject *o, void *context)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.10.</em><p>A generic implementation for the getter of a <code>__dict__</code> descriptor. It creates the dictionary if necessary.</p> <p>This function may also be called to get the <a class="reference internal" href="../library/stdtypes#object.__dict__" title="object.__dict__"><code>__dict__</code></a> of the object <em>o</em>. Pass <code>NULL</code> for <em>context</em> when calling it. Since this function may need to allocate memory for the dictionary, it may be more efficient to call <a class="reference internal" href="#c.PyObject_GetAttr" title="PyObject_GetAttr"><code>PyObject_GetAttr()</code></a> when accessing an attribute on the object.</p> <p>On failure, returns <code>NULL</code> with an exception set.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.3.</span></p> </div> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyObject_GenericSetDict">
<code>int PyObject_GenericSetDict(PyObject *o, PyObject *value, void *context)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.7.</em><p>A generic implementation for the setter of a <code>__dict__</code> descriptor. This implementation does not allow the dictionary to be deleted.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.3.</span></p> </div> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c._PyObject_GetDictPtr">
<code>PyObject **_PyObject_GetDictPtr(PyObject *obj)</code> </dt> <dd>
<p>Return a pointer to <a class="reference internal" href="../library/stdtypes#object.__dict__" title="object.__dict__"><code>__dict__</code></a> of the object <em>obj</em>. If there is no <code>__dict__</code>, return <code>NULL</code> without setting an exception.</p> <p>This function may need to allocate memory for the dictionary, so it may be more efficient to call <a class="reference internal" href="#c.PyObject_GetAttr" title="PyObject_GetAttr"><code>PyObject_GetAttr()</code></a> when accessing an attribute on the object.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyObject_RichCompare">
<code>PyObject *PyObject_RichCompare(PyObject *o1, PyObject *o2, int opid)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Compare the values of <em>o1</em> and <em>o2</em> using the operation specified by <em>opid</em>, which must be one of <a class="reference internal" href="typeobj#c.Py_LT" title="Py_LT"><code>Py_LT</code></a>, <a class="reference internal" href="typeobj#c.Py_LE" title="Py_LE"><code>Py_LE</code></a>, <a class="reference internal" href="typeobj#c.Py_EQ" title="Py_EQ"><code>Py_EQ</code></a>, <a class="reference internal" href="typeobj#c.Py_NE" title="Py_NE"><code>Py_NE</code></a>, <a class="reference internal" href="typeobj#c.Py_GT" title="Py_GT"><code>Py_GT</code></a>, or <a class="reference internal" href="typeobj#c.Py_GE" title="Py_GE"><code>Py_GE</code></a>, corresponding to <code>&lt;</code>, <code>&lt;=</code>, <code>==</code>, <code>!=</code>, <code>&gt;</code>, or <code>&gt;=</code> respectively. This is the equivalent of the Python expression <code>o1 op o2</code>, where <code>op</code> is the operator corresponding to <em>opid</em>. Returns the value of the comparison on success, or <code>NULL</code> on failure.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyObject_RichCompareBool">
<code>int PyObject_RichCompareBool(PyObject *o1, PyObject *o2, int opid)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Compare the values of <em>o1</em> and <em>o2</em> using the operation specified by <em>opid</em>, which must be one of <a class="reference internal" href="typeobj#c.Py_LT" title="Py_LT"><code>Py_LT</code></a>, <a class="reference internal" href="typeobj#c.Py_LE" title="Py_LE"><code>Py_LE</code></a>, <a class="reference internal" href="typeobj#c.Py_EQ" title="Py_EQ"><code>Py_EQ</code></a>, <a class="reference internal" href="typeobj#c.Py_NE" title="Py_NE"><code>Py_NE</code></a>, <a class="reference internal" href="typeobj#c.Py_GT" title="Py_GT"><code>Py_GT</code></a>, or <a class="reference internal" href="typeobj#c.Py_GE" title="Py_GE"><code>Py_GE</code></a>, corresponding to <code>&lt;</code>, <code>&lt;=</code>, <code>==</code>, <code>!=</code>, <code>&gt;</code>, or <code>&gt;=</code> respectively. Returns <code>-1</code> on error, <code>0</code> if the result is false, <code>1</code> otherwise. This is the equivalent of the Python expression <code>o1 op o2</code>, where <code>op</code> is the operator corresponding to <em>opid</em>.</p> </dd>
</dl> <div class="admonition note"> <p class="admonition-title">Note</p> <p>If <em>o1</em> and <em>o2</em> are the same object, <a class="reference internal" href="#c.PyObject_RichCompareBool" title="PyObject_RichCompareBool"><code>PyObject_RichCompareBool()</code></a> will always return <code>1</code> for <a class="reference internal" href="typeobj#c.Py_EQ" title="Py_EQ"><code>Py_EQ</code></a> and <code>0</code> for <a class="reference internal" href="typeobj#c.Py_NE" title="Py_NE"><code>Py_NE</code></a>.</p> </div> <dl class="c function"> <dt class="sig sig-object c" id="c.PyObject_Format">
<code>PyObject *PyObject_Format(PyObject *obj, PyObject *format_spec)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Format <em>obj</em> using <em>format_spec</em>. This is equivalent to the Python expression <code>format(obj, format_spec)</code>.</p> <p><em>format_spec</em> may be <code>NULL</code>. In this case the call is equivalent to <code>format(obj)</code>. Returns the formatted string on success, <code>NULL</code> on failure.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyObject_Repr">
<code>PyObject *PyObject_Repr(PyObject *o)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p id="index-0">Compute a string representation of object <em>o</em>. Returns the string representation on success, <code>NULL</code> on failure. This is the equivalent of the Python expression <code>repr(o)</code>. Called by the <a class="reference internal" href="../library/functions#repr" title="repr"><code>repr()</code></a> built-in function.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.4: </span>This function now includes a debug assertion to help ensure that it does not silently discard an active exception.</p> </div> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyObject_ASCII">
<code>PyObject *PyObject_ASCII(PyObject *o)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p id="index-1">As <a class="reference internal" href="#c.PyObject_Repr" title="PyObject_Repr"><code>PyObject_Repr()</code></a>, compute a string representation of object <em>o</em>, but escape the non-ASCII characters in the string returned by <a class="reference internal" href="#c.PyObject_Repr" title="PyObject_Repr"><code>PyObject_Repr()</code></a> with <code>\x</code>, <code>\u</code> or <code>\U</code> escapes. This generates a string similar to that returned by <a class="reference internal" href="#c.PyObject_Repr" title="PyObject_Repr"><code>PyObject_Repr()</code></a> in Python 2. Called by the <a class="reference internal" href="../library/functions#ascii" title="ascii"><code>ascii()</code></a> built-in function.</p> <span class="target" id="index-2"></span>
</dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyObject_Str">
<code>PyObject *PyObject_Str(PyObject *o)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Compute a string representation of object <em>o</em>. Returns the string representation on success, <code>NULL</code> on failure. This is the equivalent of the Python expression <code>str(o)</code>. Called by the <a class="reference internal" href="../library/stdtypes#str" title="str"><code>str()</code></a> built-in function and, therefore, by the <a class="reference internal" href="../library/functions#print" title="print"><code>print()</code></a> function.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.4: </span>This function now includes a debug assertion to help ensure that it does not silently discard an active exception.</p> </div> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyObject_Bytes">
<code>PyObject *PyObject_Bytes(PyObject *o)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p id="index-3">Compute a bytes representation of object <em>o</em>. <code>NULL</code> is returned on failure and a bytes object on success. This is equivalent to the Python expression <code>bytes(o)</code>, when <em>o</em> is not an integer. Unlike <code>bytes(o)</code>, a TypeError is raised when <em>o</em> is an integer instead of a zero-initialized bytes object.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyObject_IsSubclass">
<code>int PyObject_IsSubclass(PyObject *derived, PyObject *cls)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return <code>1</code> if the class <em>derived</em> is identical to or derived from the class <em>cls</em>, otherwise return <code>0</code>. In case of an error, return <code>-1</code>.</p> <p>If <em>cls</em> is a tuple, the check will be done against every entry in <em>cls</em>. The result will be <code>1</code> when at least one of the checks returns <code>1</code>, otherwise it will be <code>0</code>.</p> <p>If <em>cls</em> has a <a class="reference internal" href="../reference/datamodel#class.__subclasscheck__" title="class.__subclasscheck__"><code>__subclasscheck__()</code></a> method, it will be called to determine the subclass status as described in <span class="target" id="index-4"></span><a class="pep reference external" href="https://peps.python.org/pep-3119/"><strong>PEP 3119</strong></a>. Otherwise, <em>derived</em> is a subclass of <em>cls</em> if it is a direct or indirect subclass, i.e. contained in <code>cls.__mro__</code>.</p> <p>Normally only class objects, i.e. instances of <a class="reference internal" href="../library/functions#type" title="type"><code>type</code></a> or a derived class, are considered classes. However, objects can override this by having a <a class="reference internal" href="../library/stdtypes#class.__bases__" title="class.__bases__"><code>__bases__</code></a> attribute (which must be a tuple of base classes).</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyObject_IsInstance">
<code>int PyObject_IsInstance(PyObject *inst, PyObject *cls)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return <code>1</code> if <em>inst</em> is an instance of the class <em>cls</em> or a subclass of <em>cls</em>, or <code>0</code> if not. On error, returns <code>-1</code> and sets an exception.</p> <p>If <em>cls</em> is a tuple, the check will be done against every entry in <em>cls</em>. The result will be <code>1</code> when at least one of the checks returns <code>1</code>, otherwise it will be <code>0</code>.</p> <p>If <em>cls</em> has a <a class="reference internal" href="../reference/datamodel#class.__instancecheck__" title="class.__instancecheck__"><code>__instancecheck__()</code></a> method, it will be called to determine the subclass status as described in <span class="target" id="index-5"></span><a class="pep reference external" href="https://peps.python.org/pep-3119/"><strong>PEP 3119</strong></a>. Otherwise, <em>inst</em> is an instance of <em>cls</em> if its class is a subclass of <em>cls</em>.</p> <p>An instance <em>inst</em> can override what is considered its class by having a <a class="reference internal" href="../library/stdtypes#instance.__class__" title="instance.__class__"><code>__class__</code></a> attribute.</p> <p>An object <em>cls</em> can override if it is considered a class, and what its base classes are, by having a <a class="reference internal" href="../library/stdtypes#class.__bases__" title="class.__bases__"><code>__bases__</code></a> attribute (which must be a tuple of base classes).</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyObject_Hash">
<code>Py_hash_t PyObject_Hash(PyObject *o)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p id="index-6">Compute and return the hash value of an object <em>o</em>. On failure, return <code>-1</code>. This is the equivalent of the Python expression <code>hash(o)</code>.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.2: </span>The return type is now Py_hash_t. This is a signed integer the same size as <a class="reference internal" href="intro#c.Py_ssize_t" title="Py_ssize_t"><code>Py_ssize_t</code></a>.</p> </div> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyObject_HashNotImplemented">
<code>Py_hash_t PyObject_HashNotImplemented(PyObject *o)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Set a <a class="reference internal" href="../library/exceptions#TypeError" title="TypeError"><code>TypeError</code></a> indicating that <code>type(o)</code> is not <a class="reference internal" href="../glossary#term-hashable"><span class="xref std std-term">hashable</span></a> and return <code>-1</code>. This function receives special treatment when stored in a <code>tp_hash</code> slot, allowing a type to explicitly indicate to the interpreter that it is not hashable.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyObject_IsTrue">
<code>int PyObject_IsTrue(PyObject *o)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Returns <code>1</code> if the object <em>o</em> is considered to be true, and <code>0</code> otherwise. This is equivalent to the Python expression <code>not not o</code>. On failure, return <code>-1</code>.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyObject_Not">
<code>int PyObject_Not(PyObject *o)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Returns <code>0</code> if the object <em>o</em> is considered to be true, and <code>1</code> otherwise. This is equivalent to the Python expression <code>not o</code>. On failure, return <code>-1</code>.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyObject_Type">
<code>PyObject *PyObject_Type(PyObject *o)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p id="index-7">When <em>o</em> is non-<code>NULL</code>, returns a type object corresponding to the object type of object <em>o</em>. On failure, raises <a class="reference internal" href="../library/exceptions#SystemError" title="SystemError"><code>SystemError</code></a> and returns <code>NULL</code>. This is equivalent to the Python expression <code>type(o)</code>. This function creates a new <a class="reference internal" href="../glossary#term-strong-reference"><span class="xref std std-term">strong reference</span></a> to the return value. There’s really no reason to use this function instead of the <a class="reference internal" href="structures#c.Py_TYPE" title="Py_TYPE"><code>Py_TYPE()</code></a> function, which returns a pointer of type <span class="c-expr sig sig-inline c"><a class="reference internal" href="type#c.PyTypeObject" title="PyTypeObject"><span class="n">PyTypeObject</span></a><span class="p">*</span></span>, except when a new <a class="reference internal" href="../glossary#term-strong-reference"><span class="xref std std-term">strong reference</span></a> is needed.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyObject_TypeCheck">
<code>int PyObject_TypeCheck(PyObject *o, PyTypeObject *type)</code> </dt> <dd>
<p>Return non-zero if the object <em>o</em> is of type <em>type</em> or a subtype of <em>type</em>, and <code>0</code> otherwise. Both parameters must be non-<code>NULL</code>.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyObject_Size">
<code>Py_ssize_t PyObject_Size(PyObject *o)</code> </dt> <dt class="sig sig-object c" id="c.PyObject_Length">
<code>Py_ssize_t PyObject_Length(PyObject *o)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p id="index-8">Return the length of object <em>o</em>. If the object <em>o</em> provides either the sequence and mapping protocols, the sequence length is returned. On error, <code>-1</code> is returned. This is the equivalent to the Python expression <code>len(o)</code>.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyObject_LengthHint">
<code>Py_ssize_t PyObject_LengthHint(PyObject *o, Py_ssize_t defaultvalue)</code> </dt> <dd>
<p>Return an estimated length for the object <em>o</em>. First try to return its actual length, then an estimate using <a class="reference internal" href="../reference/datamodel#object.__length_hint__" title="object.__length_hint__"><code>__length_hint__()</code></a>, and finally return the default value. On error return <code>-1</code>. This is the equivalent to the Python expression <code>operator.length_hint(o, defaultvalue)</code>.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.4.</span></p> </div> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyObject_GetItem">
<code>PyObject *PyObject_GetItem(PyObject *o, PyObject *key)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return element of <em>o</em> corresponding to the object <em>key</em> or <code>NULL</code> on failure. This is the equivalent of the Python expression <code>o[key]</code>.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyObject_SetItem">
<code>int PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Map the object <em>key</em> to the value <em>v</em>. Raise an exception and return <code>-1</code> on failure; return <code>0</code> on success. This is the equivalent of the Python statement <code>o[key] = v</code>. This function <em>does not</em> steal a reference to <em>v</em>.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyObject_DelItem">
<code>int PyObject_DelItem(PyObject *o, PyObject *key)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Remove the mapping for the object <em>key</em> from the object <em>o</em>. Return <code>-1</code> on failure. This is equivalent to the Python statement <code>del o[key]</code>.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyObject_Dir">
<code>PyObject *PyObject_Dir(PyObject *o)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>This is equivalent to the Python expression <code>dir(o)</code>, returning a (possibly empty) list of strings appropriate for the object argument, or <code>NULL</code> if there was an error. If the argument is <code>NULL</code>, this is like the Python <code>dir()</code>, returning the names of the current locals; in this case, if no execution frame is active then <code>NULL</code> is returned but <a class="reference internal" href="exceptions#c.PyErr_Occurred" title="PyErr_Occurred"><code>PyErr_Occurred()</code></a> will return false.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyObject_GetIter">
<code>PyObject *PyObject_GetIter(PyObject *o)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>This is equivalent to the Python expression <code>iter(o)</code>. It returns a new iterator for the object argument, or the object itself if the object is already an iterator. Raises <a class="reference internal" href="../library/exceptions#TypeError" title="TypeError"><code>TypeError</code></a> and returns <code>NULL</code> if the object cannot be iterated.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyObject_GetAIter">
<code>PyObject *PyObject_GetAIter(PyObject *o)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.10.</em><p>This is the equivalent to the Python expression <code>aiter(o)</code>. Takes an <code>AsyncIterable</code> object and returns an <code>AsyncIterator</code> for it. This is typically a new iterator but if the argument is an <code>AsyncIterator</code>, this returns itself. Raises <a class="reference internal" href="../library/exceptions#TypeError" title="TypeError"><code>TypeError</code></a> and returns <code>NULL</code> if the object cannot be iterated.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.10.</span></p> </div> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyObject_GetTypeData">
<code>void *PyObject_GetTypeData(PyObject *o, PyTypeObject *cls)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.12.</em><p>Get a pointer to subclass-specific data reserved for <em>cls</em>.</p> <p>The object <em>o</em> must be an instance of <em>cls</em>, and <em>cls</em> must have been created using negative <a class="reference internal" href="type#c.PyType_Spec.basicsize" title="PyType_Spec.basicsize"><code>PyType_Spec.basicsize</code></a>. Python does not check this.</p> <p>On error, set an exception and return <code>NULL</code>.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.12.</span></p> </div> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyType_GetTypeDataSize">
<code>Py_ssize_t PyType_GetTypeDataSize(PyTypeObject *cls)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.12.</em><p>Return the size of the instance memory space reserved for <em>cls</em>, i.e. the size of the memory <a class="reference internal" href="#c.PyObject_GetTypeData" title="PyObject_GetTypeData"><code>PyObject_GetTypeData()</code></a> returns.</p> <p>This may be larger than requested using <a class="reference internal" href="type#c.PyType_Spec.basicsize" title="PyType_Spec.basicsize"><code>-PyType_Spec.basicsize</code></a>; it is safe to use this larger size (e.g. with <code>memset()</code>).</p> <p>The type <em>cls</em> <strong>must</strong> have been created using negative <a class="reference internal" href="type#c.PyType_Spec.basicsize" title="PyType_Spec.basicsize"><code>PyType_Spec.basicsize</code></a>. Python does not check this.</p> <p>On error, set an exception and return a negative value.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.12.</span></p> </div> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyObject_GetItemData">
<code>void *PyObject_GetItemData(PyObject *o)</code> </dt> <dd>
<p>Get a pointer to per-item data for a class with <a class="reference internal" href="typeobj#c.Py_TPFLAGS_ITEMS_AT_END" title="Py_TPFLAGS_ITEMS_AT_END"><code>Py_TPFLAGS_ITEMS_AT_END</code></a>.</p> <p>On error, set an exception and return <code>NULL</code>. <a class="reference internal" href="../library/exceptions#TypeError" title="TypeError"><code>TypeError</code></a> is raised if <em>o</em> does not have <a class="reference internal" href="typeobj#c.Py_TPFLAGS_ITEMS_AT_END" title="Py_TPFLAGS_ITEMS_AT_END"><code>Py_TPFLAGS_ITEMS_AT_END</code></a> set.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.12.</span></p> </div> </dd>
</dl> <div class="_attribution">
  <p class="_attribution-p">
    &copy; 2001&ndash;2023 Python Software Foundation<br>Licensed under the PSF License.<br>
    <a href="https://docs.python.org/3.12/c-api/object.html" class="_attribution-link">https://docs.python.org/3.12/c-api/object.html</a>
  </p>
</div>