Dictionary Objects¶

typePyDictObject¶

This subtype ofPyObject represents a Python dictionary object.

PyTypeObjectPyDict_Type¶

Part of theStable ABI.

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. This function always succeeds.

intPyDict_CheckExact(PyObject*p)¶

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

PyObject*PyDict_New()¶

Return value: New reference. Part of theStable ABI.

Return a new empty dictionary, orNULL on failure.

PyObject*PyDictProxy_New(PyObject*mapping)¶

Return value: New reference. Part of theStable ABI.

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)¶

Part of theStable ABI.

Empty an existing dictionary of all key-value pairs.

intPyDict_Contains(PyObject*p,PyObject*key)¶

Part of theStable ABI.

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. Part of theStable ABI.

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

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

Part of theStable ABI.

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,constchar*key,PyObject*val)¶

Part of theStable ABI.

This is the same asPyDict_SetItem(), butkey isspecified as aconstchar* UTF-8 encoded bytes string,rather than aPyObject*.

intPyDict_DelItem(PyObject*p,PyObject*key)¶

Part of theStable ABI.

Remove the entry in dictionaryp with keykey.key must behashable;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,constchar*key)¶

Part of theStable ABI.

This is the same asPyDict_DelItem(), butkey isspecified as aconstchar* UTF-8 encoded bytes string,rather than aPyObject*.

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

Return value: Borrowed reference. Part of theStable ABI.

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

Note

Exceptions that occur while this calls__hash__() and__eq__() methods are silently ignored.Prefer thePyDict_GetItemWithError() function instead.

Changed in version 3.10:Calling this API withoutGIL held had been allowed for historicalreason. It is no longer allowed.

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

Return value: Borrowed reference. Part of theStable ABI.

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,constchar*key)¶

Return value: Borrowed reference. Part of theStable ABI.

This is the same asPyDict_GetItem(), butkey is specified as aconstchar* UTF-8 encoded bytes string, rather than aPyObject*.

Note

Exceptions that occur while this calls__hash__() and__eq__() methods or while creating the temporarystrobject are silently ignored.Prefer using thePyDict_GetItemWithError() function with your ownPyUnicode_FromString()key 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. Part of theStable ABI.

Return aPyListObject containing all the items from the dictionary.

PyObject*PyDict_Keys(PyObject*p)¶

Return value: New reference. Part of theStable ABI.

Return aPyListObject containing all the keys from the dictionary.

PyObject*PyDict_Values(PyObject*p)¶

Return value: New reference. Part of theStable ABI.

Return aPyListObject containing all the values from the dictionaryp.

Py_ssize_tPyDict_Size(PyObject*p)¶

Part of theStable ABI.

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)¶

Part of theStable ABI.

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,intoverride)¶

Part of theStable ABI.

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)¶

Part of theStable ABI.

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,intoverride)¶

Part of theStable ABI.

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