7.4.1 Dictionary Objects

PyDictObject: This subtype of PyObject represents a Python dictionary object.

PyTypeObject PyDict_Type: This instance of PyTypeObject represents the Python dictionary type. This is exposed to Python programs as types.DictType and types.DictionaryType.

int PyDict_Check(PyObject *p): Returns true if its argument is a PyDictObject.

PyObject* PyDict_New(): Return value: New reference.
Returns a new empty dictionary, or NULL on failure.

void PyDict_Clear(PyObject *p): Empties an existing dictionary of all key-value pairs.

PyObject* PyDict_Copy(PyObject *p): Return value: New reference.
Returns a new dictionary that contains the same key-value pairs as p. Empties an existing dictionary of all key-value pairs.

int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val): Inserts value into the dictionary p with a key of key. key must be hashable; if it isn't, TypeError will be raised. Returns 0 on success or -1 on failure.

int PyDict_SetItemString(PyObject *p, char *key, PyObject *val): Inserts value into the dictionary p using key as a key. key should be a char*. The key object is created using PyString_FromString(key). Returns 0 on success or -1 on failure.

int PyDict_DelItem(PyObject *p, PyObject *key): Removes the entry in dictionary p with key key. key must be hashable; if it isn't, TypeError is raised.

int PyDict_DelItemString(PyObject *p, char *key): Removes the entry in dictionary p which has a key specified by the string key. Returns 0 on success or -1 on failure.

PyObject* PyDict_GetItem(PyObject *p, PyObject *key): Return value: Borrowed reference.
Returns the object from dictionary p which has a key key. Returns NULL if the key key is not present, but without setting an exception.

PyObject* PyDict_GetItemString(PyObject *p, char *key): Return value: Borrowed reference.
This is the same as PyDict_GetItem(), but key is specified as a char*, rather than a PyObject*.

PyObject* PyDict_Items(PyObject *p): Return value: New reference.
Returns a PyListObject containing all the items from the dictionary, as in the dictinoary method items() (see the Python Library Reference).

PyObject* PyDict_Keys(PyObject *p): Return value: New reference.
Returns a PyListObject containing all the keys from the dictionary, as in the dictionary method keys() (see the Python Library Reference).

PyObject* PyDict_Values(PyObject *p): Return value: New reference.
Returns a PyListObject containing all the values from the dictionary p, as in the dictionary method values() (see the Python Library Reference).

int PyDict_Size(PyObject *p): Returns the number of items in the dictionary. This is equivalent to "len(p)" on a dictionary.

int PyDict_Next(PyObject *p, int *ppos, PyObject **pkey, PyObject **pvalue)

Iterate over all key-value pairs in the dictionary p. The int referred to by ppos must be initialized to 0 prior to the first call to this function to start the iteration; the function returns true for each pair in the dictionary, and false once all pairs have been reported. The parameters pkey and pvalue should either point to PyObject* variables that will be filled in with each key and value, respectively, or may be NULL.

For example:

PyObject *key, *value;
int pos = 0;

while (PyDict_Next(self->dict, &pos, &key, &value)) {
    /* do something interesting with the values... */
    ...
}

The dictionary p should not be mutated during iteration. It is safe (since Python 2.1) to modify the values of the keys as you iterate over the dictionary, for example:

PyObject *key, *value;
int pos = 0;

while (PyDict_Next(self->dict, &pos, &key, &value)) {
    int i = PyInt_AS_LONG(value) + 1;
    PyObject *o = PyInt_FromLong(i);
    if (o == NULL)
        return -1;
    if (PyDict_SetItem(self->dict, key, o) < 0) {
        Py_DECREF(o);
        return -1;
    }
    Py_DECREF(o);
}

See About this document... for information on suggesting changes.