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