1.. highlightlang:: c 2 3.. _dictobjects: 4 5Dictionary Objects 6------------------ 7 8.. index:: object: dictionary 9 10 11.. c:type:: PyDictObject 12 13 This subtype of :c:type:`PyObject` represents a Python dictionary object. 14 15 16.. c:var:: PyTypeObject PyDict_Type 17 18 .. index:: 19 single: DictType (in module types) 20 single: DictionaryType (in module types) 21 22 This instance of :c:type:`PyTypeObject` represents the Python dictionary 23 type. This is exposed to Python programs as ``dict`` and 24 ``types.DictType``. 25 26 27.. c:function:: int PyDict_Check(PyObject *p) 28 29 Return true if *p* is a dict object or an instance of a subtype of the dict 30 type. 31 32 .. versionchanged:: 2.2 33 Allowed subtypes to be accepted. 34 35 36.. c:function:: int PyDict_CheckExact(PyObject *p) 37 38 Return true if *p* is a dict object, but not an instance of a subtype of 39 the dict type. 40 41 .. versionadded:: 2.4 42 43 44.. c:function:: PyObject* PyDict_New() 45 46 Return a new empty dictionary, or *NULL* on failure. 47 48 49.. c:function:: PyObject* PyDictProxy_New(PyObject *dict) 50 51 Return a proxy object for a mapping which enforces read-only behavior. 52 This is normally used to create a proxy to prevent modification of the 53 dictionary for non-dynamic class types. 54 55 .. versionadded:: 2.2 56 57 58.. c:function:: void PyDict_Clear(PyObject *p) 59 60 Empty an existing dictionary of all key-value pairs. 61 62 63.. c:function:: int PyDict_Contains(PyObject *p, PyObject *key) 64 65 Determine if dictionary *p* contains *key*. If an item in *p* is matches 66 *key*, return ``1``, otherwise return ``0``. On error, return ``-1``. 67 This is equivalent to the Python expression ``key in p``. 68 69 .. versionadded:: 2.4 70 71 72.. c:function:: PyObject* PyDict_Copy(PyObject *p) 73 74 Return a new dictionary that contains the same key-value pairs as *p*. 75 76 .. versionadded:: 1.6 77 78 79.. c:function:: int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val) 80 81 Insert *value* into the dictionary *p* with a key of *key*. *key* must be 82 :term:`hashable`; if it isn't, :exc:`TypeError` will be raised. Return 83 ``0`` on success or ``-1`` on failure. 84 85 86.. c:function:: int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val) 87 88 .. index:: single: PyString_FromString() 89 90 Insert *value* into the dictionary *p* using *key* as a key. *key* should 91 be a :c:type:`char\*`. The key object is created using 92 ``PyString_FromString(key)``. Return ``0`` on success or ``-1`` on 93 failure. 94 95 96.. c:function:: int PyDict_DelItem(PyObject *p, PyObject *key) 97 98 Remove the entry in dictionary *p* with key *key*. *key* must be hashable; 99 if it isn't, :exc:`TypeError` is raised. Return ``0`` on success or ``-1`` 100 on failure. 101 102 103.. c:function:: int PyDict_DelItemString(PyObject *p, char *key) 104 105 Remove the entry in dictionary *p* which has a key specified by the string 106 *key*. Return ``0`` on success or ``-1`` on failure. 107 108 109.. c:function:: PyObject* PyDict_GetItem(PyObject *p, PyObject *key) 110 111 Return the object from dictionary *p* which has a key *key*. Return *NULL* 112 if the key *key* is not present, but *without* setting an exception. 113 114 115.. c:function:: PyObject* PyDict_GetItemString(PyObject *p, const char *key) 116 117 This is the same as :c:func:`PyDict_GetItem`, but *key* is specified as a 118 :c:type:`char\*`, rather than a :c:type:`PyObject\*`. 119 120 121.. c:function:: PyObject* PyDict_Items(PyObject *p) 122 123 Return a :c:type:`PyListObject` containing all the items from the 124 dictionary, as in the dictionary method :meth:`dict.items`. 125 126 127.. c:function:: PyObject* PyDict_Keys(PyObject *p) 128 129 Return a :c:type:`PyListObject` containing all the keys from the dictionary, 130 as in the dictionary method :meth:`dict.keys`. 131 132 133.. c:function:: PyObject* PyDict_Values(PyObject *p) 134 135 Return a :c:type:`PyListObject` containing all the values from the 136 dictionary *p*, as in the dictionary method :meth:`dict.values`. 137 138 139.. c:function:: Py_ssize_t PyDict_Size(PyObject *p) 140 141 .. index:: builtin: len 142 143 Return the number of items in the dictionary. This is equivalent to 144 ``len(p)`` on a dictionary. 145 146 .. versionchanged:: 2.5 147 This function returned an :c:type:`int` type. This might require changes 148 in your code for properly supporting 64-bit systems. 149 150 151.. c:function:: int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue) 152 153 Iterate over all key-value pairs in the dictionary *p*. The 154 :c:type:`Py_ssize_t` referred to by *ppos* must be initialized to ``0`` 155 prior to the first call to this function to start the iteration; the 156 function returns true for each pair in the dictionary, and false once all 157 pairs have been reported. The parameters *pkey* and *pvalue* should either 158 point to :c:type:`PyObject\*` variables that will be filled in with each key 159 and value, respectively, or may be *NULL*. Any references returned through 160 them are borrowed. *ppos* should not be altered during iteration. Its 161 value represents offsets within the internal dictionary structure, and 162 since the structure is sparse, the offsets are not consecutive. 163 164 For example:: 165 166 PyObject *key, *value; 167 Py_ssize_t pos = 0; 168 169 while (PyDict_Next(self->dict, &pos, &key, &value)) { 170 /* do something interesting with the values... */ 171 ... 172 } 173 174 The dictionary *p* should not be mutated during iteration. It is safe 175 (since Python 2.1) to modify the values of the keys as you iterate over the 176 dictionary, but only so long as the set of keys does not change. For 177 example:: 178 179 PyObject *key, *value; 180 Py_ssize_t pos = 0; 181 182 while (PyDict_Next(self->dict, &pos, &key, &value)) { 183 int i = PyInt_AS_LONG(value) + 1; 184 PyObject *o = PyInt_FromLong(i); 185 if (o == NULL) 186 return -1; 187 if (PyDict_SetItem(self->dict, key, o) < 0) { 188 Py_DECREF(o); 189 return -1; 190 } 191 Py_DECREF(o); 192 } 193 194 .. versionchanged:: 2.5 195 This function used an :c:type:`int *` type for *ppos*. This might require 196 changes in your code for properly supporting 64-bit systems. 197 198 199.. c:function:: int PyDict_Merge(PyObject *a, PyObject *b, int override) 200 201 Iterate over mapping object *b* adding key-value pairs to dictionary *a*. 202 *b* may be a dictionary, or any object supporting :c:func:`PyMapping_Keys` 203 and :c:func:`PyObject_GetItem`. If *override* is true, existing pairs in *a* 204 will be replaced if a matching key is found in *b*, otherwise pairs will 205 only be added if there is not a matching key in *a*. Return ``0`` on 206 success or ``-1`` if an exception was raised. 207 208 .. versionadded:: 2.2 209 210 211.. c:function:: int PyDict_Update(PyObject *a, PyObject *b) 212 213 This is the same as ``PyDict_Merge(a, b, 1)`` in C, and is similar to 214 ``a.update(b)`` in Python except that :c:func:`PyDict_Update` doesn't fall 215 back to the iterating over a sequence of key value pairs if the second 216 argument has no "keys" attribute. Return ``0`` on success or ``-1`` if an 217 exception was raised. 218 219 .. versionadded:: 2.2 220 221 222.. c:function:: int PyDict_MergeFromSeq2(PyObject *a, PyObject *seq2, int override) 223 224 Update or merge into dictionary *a*, from the key-value pairs in *seq2*. 225 *seq2* must be an iterable object producing iterable objects of length 2, 226 viewed as key-value pairs. In case of duplicate keys, the last wins if 227 *override* is true, else the first wins. Return ``0`` on success or ``-1`` 228 if an exception was raised. Equivalent Python (except for the return 229 value):: 230 231 def PyDict_MergeFromSeq2(a, seq2, override): 232 for key, value in seq2: 233 if override or key not in a: 234 a[key] = value 235 236 .. versionadded:: 2.2 237