Dictionary Objects¶

PyDictObject¶

This subtype ofPyObject represents a Python dictionary object.

PyTypeObjectPyDict_Type¶

This instance ofPyTypeObject represents the Python dictionarytype. This is the same object asdict in the Python layer.

intPyDict_Check(PyObject *p)¶

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

intPyDict_CheckExact(PyObject *p)¶

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

PyObject*PyDict_New()¶

Return value: New reference.

Return a new empty dictionary, orNULL on failure.

PyObject*PyDictProxy_New(PyObject *mapping)¶

Return value: New reference.

Return atypes.MappingProxyType object for a mapping whichenforces read-only behavior. This is normally used to create a view toprevent modification of the dictionary for non-dynamic class types.

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.

PyObject*PyDict_Copy(PyObject *p)¶

Return value: New reference.

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

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

Insertval 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. This functiondoes not steal areference toval.

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

Insertval into the dictionaryp usingkey as a key.key shouldbe aconstchar*. The key object is created usingPyUnicode_FromString(key). Return0 on success or-1 onfailure. This functiondoes not steal a reference toval.

intPyDict_DelItem(PyObject *p,PyObject *key)¶

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

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

Remove the entry in dictionaryp which has a key specified by the stringkey.Ifkey is not in the dictionary,KeyError is raised.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.

Note that exceptions which occur while calling__hash__() and__eq__() methods will get suppressed.To get error reporting usePyDict_GetItemWithError() instead.

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

Return value: Borrowed reference.

Variant ofPyDict_GetItem() that does not suppressexceptions. ReturnNULLwith an exception set if an exceptionoccurred. ReturnNULLwithout an exception set if the keywasn’t present.

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

Return value: Borrowed reference.

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

Note that exceptions which occur while calling__hash__() and__eq__() methods and creating a temporary string objectwill get suppressed.To get error reporting usePyDict_GetItemWithError() instead.

PyObject*PyDict_SetDefault(PyObject *p,PyObject *key,PyObject *defaultobj)¶

Return value: Borrowed reference.

This is the same as the Python-leveldict.setdefault(). If present, itreturns the value corresponding tokey from the dictionaryp. If the keyis not in the dict, it is inserted with valuedefaultobj anddefaultobjis returned. This function evaluates the hash function ofkey only once,instead of evaluating it independently for the lookup and the insertion.

New in version 3.4.

PyObject*PyDict_Items(PyObject *p)¶

Return value: New reference.

Return aPyListObject containing all the items from the dictionary.

PyObject*PyDict_Keys(PyObject *p)¶

Return value: New reference.

Return aPyListObject containing all the keys from the dictionary.

PyObject*PyDict_Values(PyObject *p)¶

Return value: New reference.

Return aPyListObject containing all the values from the dictionaryp.

Py_ssize_tPyDict_Size(PyObject *p)¶

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

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 tomodify the values of the keys as you iterate over the dictionary, but onlyso long as the set of keys does not change. For example:

PyObject*key,*value;Py_ssize_tpos=0;while(PyDict_Next(self->dict,&pos,&key,&value)){longi=PyLong_AsLong(value);if(i==-1&&PyErr_Occurred()){return-1;}PyObject*o=PyLong_FromLong(i+1);if(o==NULL)return-1;if(PyDict_SetItem(self->dict,key,o)<0){Py_DECREF(o);return-1;}Py_DECREF(o);}

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.

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.

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

intPyDict_ClearFreeList()¶

Clear the free list. Return the total number of freed items.

New in version 3.3.