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 type.

    23    This is exposed to Python programs as ``dict`` and ``types.DictType``.

    24 

    25 

    26 .. cfunction:: int PyDict_Check(PyObject *p)

    27 

    28    Return true if *p* is a dict object or an instance of a subtype of the dict

    29    type.

    30 

    31    .. versionchanged:: 2.2

    32       Allowed subtypes to be accepted.

    33 

    34 

    35 .. cfunction:: int PyDict_CheckExact(PyObject *p)

    36 

    37    Return true if *p* is a dict object, but not an instance of a subtype of the

    38    dict type.

    39 

    40    .. versionadded:: 2.4

    41 

    42 

    43 .. cfunction:: PyObject* PyDict_New()

    44 

    45    Return a new empty dictionary, or *NULL* on failure.

    46 

    47 

    48 .. cfunction:: PyObject* PyDictProxy_New(PyObject *dict)

    49 

    50    Return a proxy object for a mapping which enforces read-only behavior.  This is

    51    normally used to create a proxy to prevent modification of the dictionary for

    52    non-dynamic class types.

    53 

    54    .. versionadded:: 2.2

    55 

    56 

    57 .. cfunction:: void PyDict_Clear(PyObject *p)

    58 

    59    Empty an existing dictionary of all key-value pairs.

    60 

    61 

    62 .. cfunction:: int PyDict_Contains(PyObject *p, PyObject *key)

    63 

    64    Determine if dictionary *p* contains *key*.  If an item in *p* is matches *key*,

    65    return ``1``, otherwise return ``0``.  On error, return ``-1``.  This is

    66    equivalent to the Python expression ``key in p``.

    67 

    68    .. versionadded:: 2.4

    69 

    70 

    71 .. cfunction:: PyObject* PyDict_Copy(PyObject *p)

    72 

    73    Return a new dictionary that contains the same key-value pairs as *p*.

    74 

    75    .. versionadded:: 1.6

    76 

    77 

    78 .. cfunction:: int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)

    79 

    80    Insert *value* into the dictionary *p* with a key of *key*.  *key* must be

    81    :term:`hashable`; if it isn't, :exc:`TypeError` will be raised. Return ``0``

    82    on success or ``-1`` on failure.

    83 

    84 

    85 .. cfunction:: int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)

    86 

    87    .. index:: single: PyString_FromString()

    88 

    89    Insert *value* into the dictionary *p* using *key* as a key. *key* should be a

    90    :ctype:`char\*`.  The key object is created using ``PyString_FromString(key)``.

    91    Return ``0`` on success or ``-1`` on failure.

    92 

    93 

    94 .. cfunction:: int PyDict_DelItem(PyObject *p, PyObject *key)

    95 

    96    Remove the entry in dictionary *p* with key *key*. *key* must be hashable; if it

    97    isn't, :exc:`TypeError` is raised.  Return ``0`` on success or ``-1`` on

    98    failure.

    99 

   100 

   101 .. cfunction:: int PyDict_DelItemString(PyObject *p, char *key)

   102 

   103    Remove the entry in dictionary *p* which has a key specified by the string

   104    *key*.  Return ``0`` on success or ``-1`` on failure.

   105 

   106 

   107 .. cfunction:: PyObject* PyDict_GetItem(PyObject *p, PyObject *key)

   108 

   109    Return the object from dictionary *p* which has a key *key*.  Return *NULL* if

   110    the key *key* is not present, but *without* setting an exception.

   111 

   112 

   113 .. cfunction:: PyObject* PyDict_GetItemString(PyObject *p, const char *key)

   114 

   115    This is the same as :cfunc:`PyDict_GetItem`, but *key* is specified as a

   116    :ctype:`char\*`, rather than a :ctype:`PyObject\*`.

   117 

   118 

   119 .. cfunction:: PyObject* PyDict_Items(PyObject *p)

   120 

   121    Return a :ctype:`PyListObject` containing all the items from the dictionary, as

   122    in the dictionary method :meth:`dict.items`.

   123 

   124 

   125 .. cfunction:: PyObject* PyDict_Keys(PyObject *p)

   126 

   127    Return a :ctype:`PyListObject` containing all the keys from the dictionary, as

   128    in the dictionary method :meth:`dict.keys`.

   129 

   130 

   131 .. cfunction:: PyObject* PyDict_Values(PyObject *p)

   132 

   133    Return a :ctype:`PyListObject` containing all the values from the dictionary

   134    *p*, as in the dictionary method :meth:`dict.values`.

   135 

   136 

   137 .. cfunction:: Py_ssize_t PyDict_Size(PyObject *p)

   138 

   139    .. index:: builtin: len

   140 

   141    Return the number of items in the dictionary.  This is equivalent to ``len(p)``

   142    on a dictionary.

   143 

   144 

   145 .. cfunction:: int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)

   146 

   147    Iterate over all key-value pairs in the dictionary *p*.  The :ctype:`int`

   148    referred to by *ppos* must be initialized to ``0`` prior to the first call to

   149    this function to start the iteration; the function returns true for each pair in

   150    the dictionary, and false once all pairs have been reported.  The parameters

   151    *pkey* and *pvalue* should either point to :ctype:`PyObject\*` variables that

   152    will be filled in with each key and value, respectively, or may be *NULL*.  Any

   153    references returned through them are borrowed.  *ppos* should not be altered

   154    during iteration. Its value represents offsets within the internal dictionary

   155    structure, and since the structure is sparse, the offsets are not consecutive.

   156 

   157    For example::

   158 

   159       PyObject *key, *value;

   160       Py_ssize_t pos = 0;

   161 

   162       while (PyDict_Next(self->dict, &pos, &key, &value)) {

   163           /* do something interesting with the values... */

   164           ...

   165       }

   166 

   167    The dictionary *p* should not be mutated during iteration.  It is safe (since

   168    Python 2.1) to modify the values of the keys as you iterate over the dictionary,

   169    but only so long as the set of keys does not change.  For example::

   170 

   171       PyObject *key, *value;

   172       Py_ssize_t pos = 0;

   173 

   174       while (PyDict_Next(self->dict, &pos, &key, &value)) {

   175           int i = PyInt_AS_LONG(value) + 1;

   176           PyObject *o = PyInt_FromLong(i);

   177           if (o == NULL)

   178               return -1;

   179           if (PyDict_SetItem(self->dict, key, o) < 0) {

   180               Py_DECREF(o);

   181               return -1;

   182           }

   183           Py_DECREF(o);

   184       }

   185 

   186 

   187 .. cfunction:: int PyDict_Merge(PyObject *a, PyObject *b, int override)

   188 

   189    Iterate over mapping object *b* adding key-value pairs to dictionary *a*. *b*

   190    may be a dictionary, or any object supporting :func:`PyMapping_Keys` and

   191    :func:`PyObject_GetItem`. If *override* is true, existing pairs in *a* will be

   192    replaced if a matching key is found in *b*, otherwise pairs will only be added

   193    if there is not a matching key in *a*. Return ``0`` on success or ``-1`` if an

   194    exception was raised.

   195 

   196    .. versionadded:: 2.2

   197 

   198 

   199 .. cfunction:: int PyDict_Update(PyObject *a, PyObject *b)

   200 

   201    This is the same as ``PyDict_Merge(a, b, 1)`` in C, or ``a.update(b)`` in

   202    Python.  Return ``0`` on success or ``-1`` if an exception was raised.

   203 

   204    .. versionadded:: 2.2

   205 

   206 

   207 .. cfunction:: int PyDict_MergeFromSeq2(PyObject *a, PyObject *seq2, int override)

   208 

   209    Update or merge into dictionary *a*, from the key-value pairs in *seq2*.  *seq2*

   210    must be an iterable object producing iterable objects of length 2, viewed as

   211    key-value pairs.  In case of duplicate keys, the last wins if *override* is

   212    true, else the first wins. Return ``0`` on success or ``-1`` if an exception was

   213    raised. Equivalent Python (except for the return value)::

   214 

   215       def PyDict_MergeFromSeq2(a, seq2, override):

   216           for key, value in seq2:

   217               if override or key not in a:

   218                   a[key] = value

   219 

   220    .. versionadded:: 2.2