字典物件¶

typePyDictObject¶

PyObject 子型態代表一個 Python 字典物件。

PyTypeObjectPyDict_Type¶

為穩定 ABI 的一部分.

PyTypeObject 實例代表一個 Python 字典型態。此與 Python 層中的dict 為同一個物件。

intPyDict_Check(PyObject*p)¶

若p 是一個字典物件或字典的子型態實例則會回傳 true。此函式每次都會執行成功。

intPyDict_CheckExact(PyObject*p)¶

若p 是一個字典物件但並不是一個字典子型態的實例，則回傳 true。此函式每次都會執行成功。

PyObject*PyDict_New()¶

回傳值：新的參照。 為穩定 ABI 的一部分.

回傳一個新的空字典，或在失敗時回傳NULL。

PyObject*PyDictProxy_New(PyObject*mapping)¶

回傳值：新的參照。 為穩定 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)¶

為穩定 ABI 的一部分.

清空現有字典中的所有鍵值對。

intPyDict_Contains(PyObject*p,PyObject*key)¶

為穩定 ABI 的一部分.

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

intPyDict_ContainsString(PyObject*p,constchar*key)¶

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

在 3.13 版被加入.

PyObject*PyDict_Copy(PyObject*p)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

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

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

為穩定 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)¶

為穩定 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)¶

為穩定 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)¶

為穩定 ABI 的一部分.

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

intPyDict_GetItemRef(PyObject*p,PyObject*key,PyObject**result)¶

為穩定 ABI 的一部分 自 3.13 版本開始.

Return a newstrong reference to the object from dictionarypwhich has a keykey:

• If the key is present, set*result to a newstrong referenceto the value and return1.

• If the key is missing, set*result toNULL and return0.

• 錯誤發生時，引發一個例外並回傳-1。

在 3.13 版被加入.

另見PyObject_GetItem() 函式。

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

回傳值：借用參照。 為穩定 ABI 的一部分.

Return aborrowed reference to the object from dictionaryp whichhas a keykey. ReturnNULL if the keykey is missingwithoutsetting an exception.

備註

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

在 3.10 版的變更:Calling this API without anattached thread state had been allowed for historicalreason. It is no longer allowed.

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

回傳值：借用參照。 為穩定 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)¶

回傳值：借用參照。 為穩定 ABI 的一部分.

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

備註

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.

intPyDict_GetItemStringRef(PyObject*p,constchar*key,PyObject**result)¶

為穩定 ABI 的一部分 自 3.13 版本開始.

Similar toPyDict_GetItemRef(), butkey is specified as aconstchar* UTF-8 encoded bytes string, rather than aPyObject*.

在 3.13 版被加入.

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

回傳值：借用參照。

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.

在 3.4 版被加入.

intPyDict_SetDefaultRef(PyObject*p,PyObject*key,PyObject*default_value,PyObject**result)¶

Insertsdefault_value into the dictionaryp with a key ofkey if thekey is not already present in the dictionary. Ifresult is notNULL,then*result is set to astrong reference to eitherdefault_value, if the key was not present, or the existing value, ifkeywas already present in the dictionary.Returns1 if the key was present anddefault_value was not inserted,or0 if the key was not present anddefault_value was inserted.On failure, returns-1, sets an exception, and sets*resulttoNULL.

For clarity: if you have a strong reference todefault_value beforecalling this function, then after it returns, you hold a strong referenceto bothdefault_value and*result (if it's notNULL).These may refer to the same object: in that case you hold two separatereferences to it.

在 3.13 版被加入.

intPyDict_Pop(PyObject*p,PyObject*key,PyObject**result)¶

Removekey from dictionaryp and optionally return the removed value.Do not raiseKeyError if the key is missing.

• If the key is present, set*result to a new reference to the removedvalue ifresult is notNULL, and return1.

• If the key is missing, set*result toNULL ifresult is notNULL, and return0.

• 錯誤發生時，引發一個例外並回傳-1。

Similar todict.pop(), but without the default value andnot raisingKeyError if the key is missing.

在 3.13 版被加入.

intPyDict_PopString(PyObject*p,constchar*key,PyObject**result)¶

Similar toPyDict_Pop(), butkey is specified as aconstchar* UTF-8 encoded bytes string, rather than aPyObject*.

在 3.13 版被加入.

PyObject*PyDict_Items(PyObject*p)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

回傳一個包含字典中所有項目的PyListObject。

PyObject*PyDict_Keys(PyObject*p)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

回傳一個包含字典中所有鍵的PyListObject。

PyObject*PyDict_Values(PyObject*p)¶

回傳值：新的參照。 為穩定 ABI 的一部分.

回傳一個包含字典p 中所有值的PyListObject。

Py_ssize_tPyDict_Size(PyObject*p)¶

為穩定 ABI 的一部分.

回傳字典中項目的數量。此與於字典呼叫len(p) 等效。

Py_ssize_tPyDict_GET_SIZE(PyObject*p)¶

Similar toPyDict_Size(), but without error checking.

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

為穩定 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.

舉例來說：

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

The function is not thread-safe in thefree-threadedbuild without external synchronization. You can usePy_BEGIN_CRITICAL_SECTION to lock the dictionary while iteratingover it:

Py_BEGIN_CRITICAL_SECTION(self->dict);while(PyDict_Next(self->dict,&pos,&key,&value)){...}Py_END_CRITICAL_SECTION();

備註

On the free-threaded build, this function can be used safely inside acritical section. However, the references returned forpkey andpvalueareborrowed and are only valid while thecritical section is held. If you need to use these objects outside thecritical section or when the critical section can be suspended, create astrong reference (for example, usingPy_NewRef()).

intPyDict_Merge(PyObject*a,PyObject*b,intoverride)¶

為穩定 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)¶

為穩定 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)¶

為穩定 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

intPyDict_AddWatcher(PyDict_WatchCallbackcallback)¶

Registercallback as a dictionary watcher. Return a non-negative integerid which must be passed to future calls toPyDict_Watch(). In caseof error (e.g. no more watcher IDs available), return-1 and set anexception.

在 3.12 版被加入.

intPyDict_ClearWatcher(intwatcher_id)¶

Clear watcher identified bywatcher_id previously returned fromPyDict_AddWatcher(). Return0 on success,-1 on error (e.g.if the givenwatcher_id was never registered.)

在 3.12 版被加入.

intPyDict_Watch(intwatcher_id,PyObject*dict)¶

Mark dictionarydict as watched. The callback grantedwatcher_id byPyDict_AddWatcher() will be called whendict is modified ordeallocated. Return0 on success or-1 on error.

在 3.12 版被加入.

intPyDict_Unwatch(intwatcher_id,PyObject*dict)¶

Mark dictionarydict as no longer watched. The callback grantedwatcher_id byPyDict_AddWatcher() will no longer be called whendict is modified or deallocated. The dict must previously have beenwatched by this watcher. Return0 on success or-1 on error.

在 3.12 版被加入.

typePyDict_WatchEvent¶

Enumeration of possible dictionary watcher events:PyDict_EVENT_ADDED,PyDict_EVENT_MODIFIED,PyDict_EVENT_DELETED,PyDict_EVENT_CLONED,PyDict_EVENT_CLEARED, orPyDict_EVENT_DEALLOCATED.

在 3.12 版被加入.

typedefint(*PyDict_WatchCallback)(PyDict_WatchEventevent,PyObject*dict,PyObject*key,PyObject*new_value)¶

Type of a dict watcher callback function.

Ifevent isPyDict_EVENT_CLEARED orPyDict_EVENT_DEALLOCATED, bothkey andnew_value will beNULL. Ifevent isPyDict_EVENT_ADDEDorPyDict_EVENT_MODIFIED,new_value will be the new value forkey.Ifevent isPyDict_EVENT_DELETED,key is being deleted from thedictionary andnew_value will beNULL.

PyDict_EVENT_CLONED occurs whendict was previously empty and anotherdict is merged into it. To maintain efficiency of this operation, per-keyPyDict_EVENT_ADDED events are not issued in this case; instead asinglePyDict_EVENT_CLONED is issued, andkey will be the sourcedictionary.

The callback may inspect but must not modifydict; doing so could haveunpredictable effects, including infinite recursion. Do not trigger Pythoncode execution in the callback, as it could modify the dict as a side effect.

Ifevent isPyDict_EVENT_DEALLOCATED, taking a new reference in thecallback to the about-to-be-destroyed dictionary will resurrect it andprevent it from being freed at this time. When the resurrected object isdestroyed later, any watcher callbacks active at that time will be calledagain.

Callbacks occur before the notified modification todict takes place, sothe prior state ofdict can be inspected.

If the callback sets an exception, it must return-1; this exception willbe printed as an unraisable exception usingPyErr_WriteUnraisable().Otherwise it should return0.

There may already be a pending exception set on entry to the callback. Inthis case, the callback should return0 with the same exception stillset. This means the callback may not call any other API that can set anexception unless it saves and clears the exception state first, and restoresit before returning.

在 3.12 版被加入.