Skip to main content

Overview

Dictionaries are hash tables mapping hashable keys to values.

Creating Dictionaries

PyObject* PyDict_New(void)
Example:
PyObject *dict = PyDict_New();
return dict;

Accessing Items

PyObject* PyDict_GetItem(PyObject *p, PyObject *key)  // Borrowed!
PyObject* PyDict_GetItemString(PyObject *p, const char *key)  // Borrowed!
int PyDict_Contains(PyObject *p, PyObject *key)
PyDict_GetItem returns borrowed reference - don’t Py_DECREF!
Example:
PyObject *key = PyUnicode_FromString("name");
PyObject *value = PyDict_GetItem(dict, key);
Py_DECREF(key);
if (value != NULL) {
    // Use value (borrowed reference)
}

Modifying Dictionaries

int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)
int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)
int PyDict_DelItem(PyObject *p, PyObject *key)
void PyDict_Clear(PyObject *p)
Example:
PyObject *key = PyUnicode_FromString("age");
PyObject *val = PyLong_FromLong(25);
PyDict_SetItem(dict, key, val);
Py_DECREF(key);
Py_DECREF(val);

Iterating

int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)
Example:
Py_ssize_t pos = 0;
PyObject *key, *value;
while (PyDict_Next(dict, &pos, &key, &value)) {
    // key and value are borrowed references
    printf("Key: %s\n", PyUnicode_AsUTF8(key));
}

Dict Views

PyObject* PyDict_Keys(PyObject *p)
PyObject* PyDict_Values(PyObject *p)
PyObject* PyDict_Items(PyObject *p)

See Also

Build docs developers (and LLMs) love