Doc/c-api/dict.rst

   1 .. highlightlang:: c
   2
   3 .. _dictobjects:
   4
   5 Dictionary 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