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

 <span id="mapping"></span><h1>Mapping Protocol</h1> <p>See also <a class="reference internal" href="object#c.PyObject_GetItem" title="PyObject_GetItem"><code>PyObject_GetItem()</code></a>, <a class="reference internal" href="object#c.PyObject_SetItem" title="PyObject_SetItem"><code>PyObject_SetItem()</code></a> and <a class="reference internal" href="object#c.PyObject_DelItem" title="PyObject_DelItem"><code>PyObject_DelItem()</code></a>.</p> <dl class="c function"> <dt class="sig sig-object c" id="c.PyMapping_Check">
<code>int PyMapping_Check(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>Return <code>1</code> if the object provides the mapping protocol or supports slicing, and <code>0</code> otherwise. Note that it returns <code>1</code> for Python classes with a <a class="reference internal" href="../reference/datamodel#object.__getitem__" title="object.__getitem__"><code>__getitem__()</code></a> method, since in general it is impossible to determine what type of keys the class supports. This function always succeeds.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyMapping_Size">
<code>Py_ssize_t PyMapping_Size(PyObject *o)</code> </dt> <dt class="sig sig-object c" id="c.PyMapping_Length">
<code>Py_ssize_t PyMapping_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-0">Returns the number of keys in object <em>o</em> on success, and <code>-1</code> on failure. This is equivalent to the Python expression <code>len(o)</code>.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyMapping_GetItemString">
<code>PyObject *PyMapping_GetItemString(PyObject *o, const char *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>This is the same as <a class="reference internal" href="object#c.PyObject_GetItem" title="PyObject_GetItem"><code>PyObject_GetItem()</code></a>, but <em>key</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.PyMapping_SetItemString">
<code>int PyMapping_SetItemString(PyObject *o, const char *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>This is the same as <a class="reference internal" href="object#c.PyObject_SetItem" title="PyObject_SetItem"><code>PyObject_SetItem()</code></a>, but <em>key</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.PyMapping_DelItem">
<code>int PyMapping_DelItem(PyObject *o, PyObject *key)</code> </dt> <dd>
<p>This is an alias of <a class="reference internal" href="object#c.PyObject_DelItem" title="PyObject_DelItem"><code>PyObject_DelItem()</code></a>.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyMapping_DelItemString">
<code>int PyMapping_DelItemString(PyObject *o, const char *key)</code> </dt> <dd>
<p>This is the same as <a class="reference internal" href="object#c.PyObject_DelItem" title="PyObject_DelItem"><code>PyObject_DelItem()</code></a>, but <em>key</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.PyMapping_HasKey">
<code>int PyMapping_HasKey(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>Return <code>1</code> if the mapping object has the key <em>key</em> and <code>0</code> otherwise. This is equivalent to the Python expression <code>key in o</code>. This function always succeeds.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>Exceptions which occur when this calls <a class="reference internal" href="../reference/datamodel#object.__getitem__" title="object.__getitem__"><code>__getitem__()</code></a> method are silently ignored. For proper error handling, use <a class="reference internal" href="object#c.PyObject_GetItem" title="PyObject_GetItem"><code>PyObject_GetItem()</code></a> instead.</p> </div> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyMapping_HasKeyString">
<code>int PyMapping_HasKeyString(PyObject *o, const char *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>This is the same as <a class="reference internal" href="#c.PyMapping_HasKey" title="PyMapping_HasKey"><code>PyMapping_HasKey()</code></a>, but <em>key</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.__getitem__" title="object.__getitem__"><code>__getitem__()</code></a> method 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.PyMapping_GetItemString" title="PyMapping_GetItemString"><code>PyMapping_GetItemString()</code></a> instead.</p> </div> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyMapping_Keys">
<code>PyObject *PyMapping_Keys(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>On success, return a list of the keys in object <em>o</em>. On failure, return <code>NULL</code>.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.7: </span>Previously, the function returned a list or a tuple.</p> </div> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyMapping_Values">
<code>PyObject *PyMapping_Values(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>On success, return a list of the values in object <em>o</em>. On failure, return <code>NULL</code>.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.7: </span>Previously, the function returned a list or a tuple.</p> </div> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyMapping_Items">
<code>PyObject *PyMapping_Items(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>On success, return a list of the items in object <em>o</em>, where each item is a tuple containing a key-value pair. On failure, return <code>NULL</code>.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.7: </span>Previously, the function returned a list or a tuple.</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/mapping.html" class="_attribution-link">https://docs.python.org/3.12/c-api/mapping.html</a>
  </p>
</div>