字典對象?

type PyDictObject?

這個(gè) PyObject 的子類(lèi)型代表一個(gè)Python字典對象。

PyTypeObject PyDict_Type?

Part of the Stable ABI.

Python字典類(lèi)型表示為 PyTypeObject 的實(shí)例。這與Python層面的 dict 是相同的對象。

int PyDict_Check(PyObject *p)?

如果 p 是一個(gè) dict 對象或者 dict 類(lèi)型的子類(lèi)型的實(shí)例則返回真值。 此函數總是會(huì )成功執行。

int PyDict_CheckExact(PyObject *p)?

如果 p 是一個(gè) dict 對象但不是 dict 類(lèi)型的子類(lèi)型的實(shí)例則返回真值。 此函數總是會(huì )成功執行。

PyObject *PyDict_New()?

Return value: New reference. Part of the Stable ABI.

返回一個(gè)新的空字典，失敗時(shí)返回 NULL。

PyObject *PyDictProxy_New(PyObject *mapping)?

Return value: New reference. Part of the Stable ABI.

返回 types.MappingProxyType 對象，用于強制執行只讀行為的映射。這通常用于創(chuàng )建視圖以防止修改非動(dòng)態(tài)類(lèi)類(lèi)型的字典。

void PyDict_Clear(PyObject *p)?

Part of the Stable ABI.

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

int PyDict_Contains(PyObject *p, PyObject *key)?

Part of the Stable ABI.

確定 key 是否包含在字典 p 中。如果 key 匹配上 p 的某一項，則返回 1 ，否則返回 0 。返回 -1 表示出錯。這等同于Python表達式 key in p 。

PyObject *PyDict_Copy(PyObject *p)?

Return value: New reference. Part of the Stable ABI.

返回與 p 包含相同鍵值對的新字典。

int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)?

Part of the Stable ABI.

使用 key 作為鍵將 val 插入字典 p。 key 必須為 hashable；如果不是，則將引發(fā) TypeError。 成功時(shí)返回 0，失敗時(shí)返回 -1。 此函數 不會(huì ) 附帶對 val 的引用。

int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)?

Part of the Stable ABI.

使用 key 作為鍵將 val 插入到字典 p。 key 應當為 const char*。 鍵對象是使用 PyUnicode_FromString(key) 創(chuàng )建的。 成功時(shí)返回 0，失敗時(shí)返回 -1。 此函數 不會(huì ) 附帶對 val 的引用。

int PyDict_DelItem(PyObject *p, PyObject *key)?

Part of the Stable ABI.

移除字典 p 中鍵為 key 的條目。 key 必須是可哈希的；如果不是，則會(huì )引發(fā) TypeError。 如果字典中沒(méi)有 key，則會(huì )引發(fā) KeyError。 成功時(shí)返回 0，失敗時(shí)返回 -1。

int PyDict_DelItemString(PyObject *p, const char *key)?

Part of the Stable ABI.

移除字典 p 中由字符串 key 指定的鍵的條目。 如果字典中沒(méi)有 key，則會(huì )引發(fā) KeyError。 成功時(shí)返回 0，失敗時(shí)返回 -1。

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

Return value: Borrowed reference. Part of the Stable ABI.

從字典 p 中返回以 key 為鍵的對象。 如果鍵名 key 不存在但 沒(méi)有 設置一個(gè)異常則返回 NULL。

需要注意的是，調用 __hash__() 和 __eq__() 方法產(chǎn)生的異常不會(huì )被拋出。改用 PyDict_GetItemWithError() 獲得錯誤報告。

在 3.10 版更改: 在不保持 GIL 的情況下調用此 API 曾因歷史原因而被允許。 現在已不再被允許。

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

Return value: Borrowed reference. Part of the Stable ABI.

PyDict_GetItem() 的變種，它不會(huì )屏蔽異常。 當異常發(fā)生時(shí)將返回 NULL 并且 設置一個(gè)異常。 如果鍵不存在則返回 NULL 并且不會(huì ) 設置一個(gè)異常。

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

Return value: Borrowed reference. Part of the Stable ABI.

這與 PyDict_GetItem() 一樣，但是 key 被指定為 const char*，而不是 PyObject*。

需要注意的是，調用 __hash__() 、 __eq__() 方法和創(chuàng )建一個(gè)臨時(shí)的字符串對象時(shí)產(chǎn)生的異常不會(huì )被拋出。改用 PyDict_GetItemWithError() 獲得錯誤報告。

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

Return value: Borrowed reference.

這跟Python層面的 dict.setdefault() 一樣。如果鍵 key 存在，它返回在字典 p 里面對應的值。如果鍵不存在，它會(huì )和值 defaultobj 一起插入并返回 defaultobj 。這個(gè)函數只計算 key 的哈希函數一次，而不是在查找和插入時(shí)分別計算它。

3.4 新版功能.

PyObject *PyDict_Items(PyObject *p)?

Return value: New reference. Part of the Stable ABI.

返回一個(gè)包含字典中所有鍵值項的 PyListObject。

PyObject *PyDict_Keys(PyObject *p)?

Return value: New reference. Part of the Stable ABI.

返回一個(gè)包含字典中所有鍵(keys)的 PyListObject。

PyObject *PyDict_Values(PyObject *p)?

Return value: New reference. Part of the Stable ABI.

返回一個(gè)包含字典中所有值(values)的 PyListObject。

Py_ssize_t PyDict_Size(PyObject *p)?

Part of the Stable ABI.

返回字典中項目數，等價(jià)于對字典 p 使用 len(p)。

int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)?

Part of the Stable ABI.

迭代字典 p 中的所有鍵值對。 在第一次調用此函數開(kāi)始迭代之前，由 ppos 所引用的 Py_ssize_t 必須被初始化為 0；該函數將為字典中的每個(gè)鍵值對返回真值，一旦所有鍵值對都報告完畢則返回假值。 形參 pkey 和 pvalue 應當指向 PyObject* 變量，它們將分別使用每個(gè)鍵和值來(lái)填充，或者也可以為 NULL。 通過(guò)它們返回的任何引用都是暫借的。 ppos 在迭代期間不應被更改。 它的值表示內部字典結構中的偏移量，并且由于結構是稀疏的，因此偏移量并不連續。

例如：

PyObject *key, *value;
Py_ssize_t pos = 0;

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

字典 p 不應該在遍歷期間發(fā)生改變。在遍歷字典時(shí)，改變鍵中的值是安全的，但僅限于鍵的集合不發(fā)生改變。例如:

PyObject *key, *value;
Py_ssize_t pos = 0;

while (PyDict_Next(self->dict, &pos, &key, &value)) {
    long i = 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);
}

int PyDict_Merge(PyObject *a, PyObject *b, int override)?

Part of the Stable ABI.

對映射對象 b 進(jìn)行迭代，將鍵值對添加到字典 a。 b 可以是一個(gè)字典，或任何支持 PyMapping_Keys() 和 PyObject_GetItem() 的對象。 如果 override 為真值，則如果在 b 中找到相同的鍵則 a 中已存在的相應鍵值對將被替換，否則如果在 a 中沒(méi)有相同的鍵則只是添加鍵值對。 當成功時(shí)返回 0 或者當引發(fā)異常時(shí)返回 -1。

int PyDict_Update(PyObject *a, PyObject *b)?

Part of the Stable ABI.

這與 C 中的 PyDict_Merge(a, b, 1) 一樣，也類(lèi)似于 Python 中的 a.update(b)，差別在于 PyDict_Update() 在第二個(gè)參數沒(méi)有 "keys" 屬性時(shí)不會(huì )回退到迭代鍵值對的序列。 當成功時(shí)返回 0 或者當引發(fā)異常時(shí)返回 -1。

int PyDict_MergeFromSeq2(PyObject *a, PyObject *seq2, int override)?

Part of the Stable ABI.

將 seq2 中的鍵值對更新或合并到字典 a。 seq2 必須為產(chǎn)生長(cháng)度為 2 的用作鍵值對的元素的可迭代對象。 當存在重復的鍵時(shí)，如果 override 真值則最后出現的鍵勝出。 當成功時(shí)返回 0 或者當引發(fā)異常時(shí)返回 -1。 等價(jià)的 Python 代碼（返回值除外）:

def PyDict_MergeFromSeq2(a, seq2, override):
    for key, value in seq2:
        if override or key not in a:
            a[key] = value