Dictionary Objects¶

PyDictObject¶

This subtype ofPyObject represents a Python dictionary object.

PyTypeObjectPyDict_Type¶

This instance ofPyTypeObject represents the Python dictionarytype. This is exposed to Python programs asdict andtypes.DictType.

intPyDict_Check(PyObject *p)¶

Return true ifp is a dict object or an instance of a subtype of the dicttype.

Changed in version 2.2:Allowed subtypes to be accepted.

intPyDict_CheckExact(PyObject *p)¶

Return true ifp is a dict object, but not an instance of a subtype ofthe dict type.

New in version 2.4.

PyObject*PyDict_New()¶

Return value: New reference.

Return a new empty dictionary, orNULL on failure.

PyObject*PyDictProxy_New(PyObject *dict)¶

Return value: New reference.

Return a proxy object for a mapping which enforces read-only behavior.This is normally used to create a proxy to prevent modification of thedictionary for non-dynamic class types.

New in version 2.2.

voidPyDict_Clear(PyObject *p)¶

Empty an existing dictionary of all key-value pairs.

intPyDict_Contains(PyObject *p,PyObject *key)¶

Determine if dictionaryp containskey. If an item inp is matcheskey, return1, otherwise return0. On error, return-1.This is equivalent to the Python expressionkeyinp.

New in version 2.4.

PyObject*PyDict_Copy(PyObject *p)¶

Return value: New reference.

Return a new dictionary that contains the same key-value pairs asp.

New in version 1.6.

intPyDict_SetItem(PyObject *p,PyObject *key,PyObject *val)¶

Insertvalue into the dictionaryp with a key ofkey.key must behashable; if it isn’t,TypeError will be raised. Return0 on success or-1 on failure.

intPyDict_SetItemString(PyObject *p, const char *key,PyObject *val)¶

Insertvalue into the dictionaryp usingkey as a key.key shouldbe achar*. The key object is created usingPyString_FromString(key). Return0 on success or-1 onfailure.

intPyDict_DelItem(PyObject *p,PyObject *key)¶

Remove the entry in dictionaryp with keykey.key must be hashable;if it isn’t,TypeError is raised. Return0 on success or-1on failure.

intPyDict_DelItemString(PyObject *p, char *key)¶

Remove the entry in dictionaryp which has a key specified by the stringkey. Return0 on success or-1 on failure.

PyObject*PyDict_GetItem(PyObject *p,PyObject *key)¶

Return value: Borrowed reference.

Return the object from dictionaryp which has a keykey. ReturnNULLif the keykey is not present, butwithout setting an exception.

PyObject*PyDict_GetItemString(PyObject *p, const char *key)¶

Return value: Borrowed reference.

This is the same asPyDict_GetItem(), butkey is specified as achar*, rather than aPyObject*.

PyObject*PyDict_Items(PyObject *p)¶

Return value: New reference.

Return aPyListObject containing all the items from thedictionary, as in the dictionary methoddict.items().

PyObject*PyDict_Keys(PyObject *p)¶

Return value: New reference.

Return aPyListObject containing all the keys from the dictionary,as in the dictionary methoddict.keys().

PyObject*PyDict_Values(PyObject *p)¶

Return value: New reference.

Return aPyListObject containing all the values from thedictionaryp, as in the dictionary methoddict.values().

Py_ssize_tPyDict_Size(PyObject *p)¶

Return the number of items in the dictionary. This is equivalent tolen(p) on a dictionary.

Changed in version 2.5:This function returned anint type. This might require changesin your code for properly supporting 64-bit systems.

intPyDict_Next(PyObject *p, Py_ssize_t *ppos,PyObject **pkey,PyObject **pvalue)¶

Iterate over all key-value pairs in the dictionaryp. ThePy_ssize_t referred to byppos must be initialized to0prior to the first call to this function to start the iteration; thefunction returns true for each pair in the dictionary, and false once allpairs have been reported. The parameterspkey andpvalue should eitherpoint toPyObject* variables that will be filled in with each keyand value, respectively, or may beNULL. Any references returned throughthem are borrowed.ppos should not be altered during iteration. Itsvalue represents offsets within the internal dictionary structure, andsince the structure is sparse, the offsets are not consecutive.

For example:

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

The dictionaryp should not be mutated during iteration. It is safe(since Python 2.1) to modify the values of the keys as you iterate over thedictionary, but only so long as the set of keys does not change. Forexample:

PyObject*key,*value;Py_ssize_tpos=0;while(PyDict_Next(self->dict,&pos,&key,&value)){inti=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);}

Changed in version 2.5:This function used anint* type forppos. This might requirechanges in your code for properly supporting 64-bit systems.

intPyDict_Merge(PyObject *a,PyObject *b, int override)¶

Iterate over mapping objectb adding key-value pairs to dictionarya.b may be a dictionary, or any object supportingPyMapping_Keys()andPyObject_GetItem(). Ifoverride is true, existing pairs inawill be replaced if a matching key is found inb, otherwise pairs willonly be added if there is not a matching key ina. Return0 onsuccess or-1 if an exception was raised.

New in version 2.2.

intPyDict_Update(PyObject *a,PyObject *b)¶

This is the same asPyDict_Merge(a,b,1) in C, and is similar toa.update(b) in Python except thatPyDict_Update() doesn’t fallback to the iterating over a sequence of key value pairs if the secondargument has no “keys” attribute. Return0 on success or-1 if anexception was raised.

New in version 2.2.

intPyDict_MergeFromSeq2(PyObject *a,PyObject *seq2, int override)¶

Update or merge into dictionarya, from the key-value pairs inseq2.seq2 must be an iterable object producing iterable objects of length 2,viewed as key-value pairs. In case of duplicate keys, the last wins ifoverride is true, else the first wins. Return0 on success or-1if an exception was raised. Equivalent Python (except for the returnvalue):

defPyDict_MergeFromSeq2(a,seq2,override):forkey,valueinseq2:ifoverrideorkeynotina:a[key]=value

New in version 2.2.