/Doc/c-api/dict.rst

  1.. highlightlang:: c
  2
  3.. _dictobjects:
  4
  5Dictionary Objects
  6------------------
  7
  8.. index:: object: dictionary
  9
 10
 11.. ctype:: PyDictObject
 12
 13   This subtype of :ctype:`PyObject` represents a Python dictionary object.
 14
 15
 16.. cvar:: PyTypeObject PyDict_Type
 17
 18   .. index::
 19      single: DictType (in module types)
 20      single: DictionaryType (in module types)
 21
 22   This instance of :ctype:`PyTypeObject` represents the Python dictionary
 23   type.  This is exposed to Python programs as ``dict`` and
 24   ``types.DictType``.
 25
 26
 27.. cfunction:: 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.. cfunction:: 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.. cfunction:: PyObject* PyDict_New()
 45
 46   Return a new empty dictionary, or *NULL* on failure.
 47
 48
 49.. cfunction:: 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.. cfunction:: void PyDict_Clear(PyObject *p)
 59
 60   Empty an existing dictionary of all key-value pairs.
 61
 62
 63.. cfunction:: 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.. cfunction:: 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.. cfunction:: 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.. cfunction:: 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 :ctype:`char\*`.  The key object is created using
 92   ``PyString_FromString(key)``.  Return ``0`` on success or ``-1`` on
 93   failure.
 94
 95
 96.. cfunction:: 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.. cfunction:: 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.. cfunction:: 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.. cfunction:: PyObject* PyDict_GetItemString(PyObject *p, const char *key)
116
117   This is the same as :cfunc:`PyDict_GetItem`, but *key* is specified as a
118   :ctype:`char\*`, rather than a :ctype:`PyObject\*`.
119
120
121.. cfunction:: PyObject* PyDict_Items(PyObject *p)
122
123   Return a :ctype:`PyListObject` containing all the items from the
124   dictionary, as in the dictionary method :meth:`dict.items`.
125
126
127.. cfunction:: PyObject* PyDict_Keys(PyObject *p)
128
129   Return a :ctype:`PyListObject` containing all the keys from the dictionary,
130   as in the dictionary method :meth:`dict.keys`.
131
132
133.. cfunction:: PyObject* PyDict_Values(PyObject *p)
134
135   Return a :ctype:`PyListObject` containing all the values from the
136   dictionary *p*, as in the dictionary method :meth:`dict.values`.
137
138
139.. cfunction:: 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 :ctype:`int` type.  This might require changes
148      in your code for properly supporting 64-bit systems.
149
150
151.. cfunction:: 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   :ctype:`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 :ctype:`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 :ctype:`int *` type for *ppos*. This might require
196      changes in your code for properly supporting 64-bit systems.
197
198
199.. cfunction:: 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 :func:`PyMapping_Keys`
203   and :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.. cfunction:: int PyDict_Update(PyObject *a, PyObject *b)
212
213   This is the same as ``PyDict_Merge(a, b, 1)`` in C, or ``a.update(b)`` in
214   Python.  Return ``0`` on success or ``-1`` if an exception was raised.
215
216   .. versionadded:: 2.2
217
218
219.. cfunction:: int PyDict_MergeFromSeq2(PyObject *a, PyObject *seq2, int override)
220
221   Update or merge into dictionary *a*, from the key-value pairs in *seq2*.
222   *seq2* must be an iterable object producing iterable objects of length 2,
223   viewed as key-value pairs.  In case of duplicate keys, the last wins if
224   *override* is true, else the first wins. Return ``0`` on success or ``-1``
225   if an exception was raised. Equivalent Python (except for the return
226   value)::
227
228      def PyDict_MergeFromSeq2(a, seq2, override):
229          for key, value in seq2:
230              if override or key not in a:
231                  a[key] = value
232
233   .. versionadded:: 2.2