File: //usr/local/ssl/share/doc/python-docs-2.4.3/html/api/dictObjects.html
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="api.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index' />
<link rel="first" href="api.html" title='Python/C API Reference Manual' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="prev" href="mapObjects.html" />
<link rel="parent" href="mapObjects.html" />
<link rel="next" href="otherObjects.html" />
<meta name='aesop' content='information' />
<title>7.4.1 Dictionary Objects </title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="7.4 Mapping Objects"
href="mapObjects.html"><img src='../icons/previous.png'
border='0' height='32' alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="7.4 Mapping Objects"
href="mapObjects.html"><img src='../icons/up.png'
border='0' height='32' alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="7.5 Other Objects"
href="otherObjects.html"><img src='../icons/next.png'
border='0' height='32' alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python/C API Reference Manual</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
href="contents.html"><img src='../icons/contents.png'
border='0' height='32' alt='Contents' width='32' /></A></td>
<td class='online-navigation'><img src='../icons/blank.png'
border='0' height='32' alt='' width='32' /></td>
<td class='online-navigation'><a rel="index" title="Index"
href="genindex.html"><img src='../icons/index.png'
border='0' height='32' alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="mapObjects.html">7.4 Mapping Objects</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="mapObjects.html">7.4 Mapping Objects</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="otherObjects.html">7.5 Other Objects</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->
<H2><A NAME="SECTION009410000000000000000"></A><A NAME="dictObjects"></A>
<BR>
7.4.1 Dictionary Objects
</H2>
<P>
<a id='l2h-602' xml:id='l2h-602'></a><dl><dt><b><tt class="ctype"><a id='l2h-603' xml:id='l2h-603'>PyDictObject</a></tt></b></dt>
<dd>
This subtype of <tt class="ctype">PyObject</tt> represents a Python dictionary
object.
</dl>
<P>
<dl><dt>PyTypeObject <b><tt id='l2h-604' xml:id='l2h-604' class="cdata">PyDict_Type</tt></b></dt>
<dd>
This instance of <tt class="ctype">PyTypeObject</tt> represents the Python
dictionary type. This is exposed to Python programs as
<code>types.DictType</code> and <code>types.DictionaryType</code>.
<a id='l2h-606' xml:id='l2h-606'></a></dd></dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-607' xml:id='l2h-607' class="cfunction">PyDict_Check</tt></b>(</nobr></td><td>PyObject *<var>p</var>)</td></tr></table></dt>
<dd>
Return true if <var>p</var> is a dict object or an instance of a
subtype of the dict type.
<span class="versionnote">Changed in version 2.2:
Allowed subtypes to be accepted.</span>
</dd></dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-608' xml:id='l2h-608' class="cfunction">PyDict_CheckExact</tt></b>(</nobr></td><td>PyObject *<var>p</var>)</td></tr></table></dt>
<dd>
Return true if <var>p</var> is a dict object, but not an instance of a
subtype of the dict type.
<span class="versionnote">New in version 2.4.</span>
</dd></dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-609' xml:id='l2h-609' class="cfunction">PyDict_New</tt></b>(</nobr></td><td>)</td></tr></table></dt>
<dd>
<div class="refcount-info">
<span class="label">Return value:</span>
<span class="value">New reference.</span>
</div>
Return a new empty dictionary, or <tt class="constant">NULL</tt> on failure.
</dd></dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-610' xml:id='l2h-610' class="cfunction">PyDictProxy_New</tt></b>(</nobr></td><td>PyObject *<var>dict</var>)</td></tr></table></dt>
<dd>
<div class="refcount-info">
<span class="label">Return value:</span>
<span class="value">New reference.</span>
</div>
Return a proxy object for a mapping which enforces read-only
behavior. This is normally used to create a proxy to prevent
modification of the dictionary for non-dynamic class types.
<span class="versionnote">New in version 2.2.</span>
</dd></dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void <b><tt id='l2h-611' xml:id='l2h-611' class="cfunction">PyDict_Clear</tt></b>(</nobr></td><td>PyObject *<var>p</var>)</td></tr></table></dt>
<dd>
Empty an existing dictionary of all key-value pairs.
</dd></dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-612' xml:id='l2h-612' class="cfunction">PyDict_Contains</tt></b>(</nobr></td><td>PyObject *<var>p</var>, PyObject *<var>key</var>)</td></tr></table></dt>
<dd>
Determine if dictionary <var>p</var> contains <var>key</var>. If an item
in <var>p</var> is matches <var>key</var>, return <code>1</code>, otherwise return
<code>0</code>. On error, return <code>-1</code>. This is equivalent to the
Python expression "<tt class="samp"><var>key</var> in <var>p</var></tt>".
<span class="versionnote">New in version 2.4.</span>
</dd></dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-613' xml:id='l2h-613' class="cfunction">PyDict_Copy</tt></b>(</nobr></td><td>PyObject *<var>p</var>)</td></tr></table></dt>
<dd>
<div class="refcount-info">
<span class="label">Return value:</span>
<span class="value">New reference.</span>
</div>
Return a new dictionary that contains the same key-value pairs as
<var>p</var>.
<span class="versionnote">New in version 1.6.</span>
</dd></dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-614' xml:id='l2h-614' class="cfunction">PyDict_SetItem</tt></b>(</nobr></td><td>PyObject *<var>p</var>, PyObject *<var>key</var>,
PyObject *<var>val</var>)</td></tr></table></dt>
<dd>
Insert <var>value</var> into the dictionary <var>p</var> with a key of
<var>key</var>. <var>key</var> must be hashable; if it isn't,
<tt class="exception">TypeError</tt> will be raised.
Return <code>0</code> on success or <code>-1</code> on failure.
</dd></dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-615' xml:id='l2h-615' class="cfunction">PyDict_SetItemString</tt></b>(</nobr></td><td>PyObject *<var>p</var>,
char *<var>key</var>,
PyObject *<var>val</var>)</td></tr></table></dt>
<dd>
Insert <var>value</var> into the dictionary <var>p</var> using <var>key</var> as a
key. <var>key</var> should be a <tt class="ctype">char*</tt>. The key object is created
using <code>PyString_FromString(<var>key</var>)</code>. Return <code>0</code> on
success or <code>-1</code> on failure.
<a id='l2h-629' xml:id='l2h-629'></a>
</dd></dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-616' xml:id='l2h-616' class="cfunction">PyDict_DelItem</tt></b>(</nobr></td><td>PyObject *<var>p</var>, PyObject *<var>key</var>)</td></tr></table></dt>
<dd>
Remove the entry in dictionary <var>p</var> with key <var>key</var>.
<var>key</var> must be hashable; if it isn't, <tt class="exception">TypeError</tt> is
raised. Return <code>0</code> on success or <code>-1</code> on failure.
</dd></dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-617' xml:id='l2h-617' class="cfunction">PyDict_DelItemString</tt></b>(</nobr></td><td>PyObject *<var>p</var>, char *<var>key</var>)</td></tr></table></dt>
<dd>
Remove the entry in dictionary <var>p</var> which has a key specified by
the string <var>key</var>. Return <code>0</code> on success or <code>-1</code> on
failure.
</dd></dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-618' xml:id='l2h-618' class="cfunction">PyDict_GetItem</tt></b>(</nobr></td><td>PyObject *<var>p</var>, PyObject *<var>key</var>)</td></tr></table></dt>
<dd>
<div class="refcount-info">
<span class="label">Return value:</span>
<span class="value">Borrowed reference.</span>
</div>
Return the object from dictionary <var>p</var> which has a key
<var>key</var>. Return <tt class="constant">NULL</tt> if the key <var>key</var> is not present, but
<em>without</em> setting an exception.
</dd></dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-619' xml:id='l2h-619' class="cfunction">PyDict_GetItemString</tt></b>(</nobr></td><td>PyObject *<var>p</var>, char *<var>key</var>)</td></tr></table></dt>
<dd>
<div class="refcount-info">
<span class="label">Return value:</span>
<span class="value">Borrowed reference.</span>
</div>
This is the same as <tt class="cfunction">PyDict_GetItem()</tt>, but <var>key</var> is
specified as a <tt class="ctype">char*</tt>, rather than a <tt class="ctype">PyObject*</tt>.
</dd></dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-620' xml:id='l2h-620' class="cfunction">PyDict_Items</tt></b>(</nobr></td><td>PyObject *<var>p</var>)</td></tr></table></dt>
<dd>
<div class="refcount-info">
<span class="label">Return value:</span>
<span class="value">New reference.</span>
</div>
Return a <tt class="ctype">PyListObject</tt> containing all the items from the
dictionary, as in the dictionary method <tt class="method">items()</tt> (see the
<em class="citetitle"><a
href="../lib/lib.html"
title="Python Library Reference"
>Python Library Reference</a></em>).
</dd></dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-621' xml:id='l2h-621' class="cfunction">PyDict_Keys</tt></b>(</nobr></td><td>PyObject *<var>p</var>)</td></tr></table></dt>
<dd>
<div class="refcount-info">
<span class="label">Return value:</span>
<span class="value">New reference.</span>
</div>
Return a <tt class="ctype">PyListObject</tt> containing all the keys from the
dictionary, as in the dictionary method <tt class="method">keys()</tt> (see the
<em class="citetitle"><a
href="../lib/lib.html"
title="Python Library Reference"
>Python Library Reference</a></em>).
</dd></dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-622' xml:id='l2h-622' class="cfunction">PyDict_Values</tt></b>(</nobr></td><td>PyObject *<var>p</var>)</td></tr></table></dt>
<dd>
<div class="refcount-info">
<span class="label">Return value:</span>
<span class="value">New reference.</span>
</div>
Return a <tt class="ctype">PyListObject</tt> containing all the values from the
dictionary <var>p</var>, as in the dictionary method <tt class="method">values()</tt>
(see the <em class="citetitle"><a
href="../lib/lib.html"
title="Python Library Reference"
>Python Library Reference</a></em>).
</dd></dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-623' xml:id='l2h-623' class="cfunction">PyDict_Size</tt></b>(</nobr></td><td>PyObject *<var>p</var>)</td></tr></table></dt>
<dd>
Return the number of items in the dictionary. This is equivalent
to "<tt class="samp">len(<var>p</var>)</tt>" on a dictionary.<a id='l2h-624' xml:id='l2h-624'></a></dd></dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-625' xml:id='l2h-625' class="cfunction">PyDict_Next</tt></b>(</nobr></td><td>PyObject *<var>p</var>, int *<var>ppos</var>,
PyObject **<var>pkey</var>, PyObject **<var>pvalue</var>)</td></tr></table></dt>
<dd>
Iterate over all key-value pairs in the dictionary <var>p</var>. The
<tt class="ctype">int</tt> referred to by <var>ppos</var> must be initialized to
<code>0</code> prior to the first call to this function to start the
iteration; the function returns true for each pair in the
dictionary, and false once all pairs have been reported. The
parameters <var>pkey</var> and <var>pvalue</var> should either point to
<tt class="ctype">PyObject*</tt> variables that will be filled in with each key and
value, respectively, or may be <tt class="constant">NULL</tt>. Any references returned through
them are borrowed. <var>ppos</var> should not be altered during iteration.
Its value represents offsets within the internal dictionary structure,
and since the structure is sparse, the offsets are not consecutive.
<P>
For example:
<P>
<div class="verbatim"><pre>
PyObject *key, *value;
int pos = 0;
while (PyDict_Next(self->dict, &pos, &key, &value)) {
/* do something interesting with the values... */
...
}
</pre></div>
<P>
The dictionary <var>p</var> should not be mutated during iteration. It
is safe (since Python 2.1) to modify the values of the keys as you
iterate over the dictionary, but only so long as the set of keys
does not change. For example:
<P>
<div class="verbatim"><pre>
PyObject *key, *value;
int pos = 0;
while (PyDict_Next(self->dict, &pos, &key, &value)) {
int i = PyInt_AS_LONG(value) + 1;
PyObject *o = PyInt_FromLong(i);
if (o == NULL)
return -1;
if (PyDict_SetItem(self->dict, key, o) < 0) {
Py_DECREF(o);
return -1;
}
Py_DECREF(o);
}
</pre></div>
</dd></dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-626' xml:id='l2h-626' class="cfunction">PyDict_Merge</tt></b>(</nobr></td><td>PyObject *<var>a</var>, PyObject *<var>b</var>, int <var>override</var>)</td></tr></table></dt>
<dd>
Iterate over mapping object <var>b</var> adding key-value pairs to dictionary
<var>a</var>.
<var>b</var> may be a dictionary, or any object supporting
<tt class="function">PyMapping_Keys()</tt> and <tt class="function">PyObject_GetItem()</tt>.
If <var>override</var> is true, existing pairs in <var>a</var> will
be replaced if a matching key is found in <var>b</var>, otherwise pairs
will only be added if there is not a matching key in <var>a</var>.
Return <code>0</code> on success or <code>-1</code> if an exception was
raised.
<span class="versionnote">New in version 2.2.</span>
</dd></dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-627' xml:id='l2h-627' class="cfunction">PyDict_Update</tt></b>(</nobr></td><td>PyObject *<var>a</var>, PyObject *<var>b</var>)</td></tr></table></dt>
<dd>
This is the same as <code>PyDict_Merge(<var>a</var>, <var>b</var>, 1)</code> in C,
or <code><var>a</var>.update(<var>b</var>)</code> in Python. Return <code>0</code> on
success or <code>-1</code> if an exception was raised.
<span class="versionnote">New in version 2.2.</span>
</dd></dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-628' xml:id='l2h-628' class="cfunction">PyDict_MergeFromSeq2</tt></b>(</nobr></td><td>PyObject *<var>a</var>, PyObject *<var>seq2</var>,
int <var>override</var>)</td></tr></table></dt>
<dd>
Update or merge into dictionary <var>a</var>, from the key-value pairs in
<var>seq2</var>. <var>seq2</var> must be an iterable object producing
iterable objects of length 2, viewed as key-value pairs. In case of
duplicate keys, the last wins if <var>override</var> is true, else the
first wins.
Return <code>0</code> on success or <code>-1</code> if an exception
was raised.
Equivalent Python (except for the return value):
<P>
<div class="verbatim"><pre>
def PyDict_MergeFromSeq2(a, seq2, override):
for key, value in seq2:
if override or key not in a:
a[key] = value
</pre></div>
<P>
<span class="versionnote">New in version 2.2.</span>
</dd></dl>
<P>
<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="7.4 Mapping Objects"
href="mapObjects.html"><img src='../icons/previous.png'
border='0' height='32' alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="7.4 Mapping Objects"
href="mapObjects.html"><img src='../icons/up.png'
border='0' height='32' alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="7.5 Other Objects"
href="otherObjects.html"><img src='../icons/next.png'
border='0' height='32' alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python/C API Reference Manual</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
href="contents.html"><img src='../icons/contents.png'
border='0' height='32' alt='Contents' width='32' /></A></td>
<td class='online-navigation'><img src='../icons/blank.png'
border='0' height='32' alt='' width='32' /></td>
<td class='online-navigation'><a rel="index" title="Index"
href="genindex.html"><img src='../icons/index.png'
border='0' height='32' alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="mapObjects.html">7.4 Mapping Objects</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="mapObjects.html">7.4 Mapping Objects</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="otherObjects.html">7.5 Other Objects</A>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.3, documentation updated on 29 March 2006.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>