##
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);
        }