7.3.1 Dictionary Objects
Keywords: api

##
7.3.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 with a key of key. key must be hashable; if it isn't, `TypeError` will be raised.

int `PyDict_SetItemString` (PyDictObject *p, char *key, PyObject *val)
  Inserts value into the dictionary using key as a key. key should be a `char*`. The key object is created using `PyString_FromString(key)`.

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.

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` (PyDictObject *p, int *ppos, PyObject **pkey, PyObject **pvalue)