字典物件

type PyDictObject

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

PyTypeObject PyDict_Type
Part of the Stable ABI.

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

int PyDict_Check(PyObject *p)

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

int PyDict_CheckExact(PyObject *p)

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

PyObject *PyDict_New()
Return value: New reference. Part of the Stable ABI.

返回一个新的空字典,失败时返回 NULL

PyObject *PyDictProxy_New(PyObject *mapping)
Return value: New reference. Part of the Stable ABI.

返回 types.MappingProxyType 对象,用于强制执行只读行为的映射。这通常用于创建视图以防止修改非动态类类型的字典。

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 插入字典 pkey 必须为 hashable;如果不是,则将引发 TypeError。 成功时返回 0,失败时返回 -1。 此函数 不会 附带对 val 的引用。

int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)
Part of the Stable ABI.

使用 key 作为键将 val 插入到字典 pkey 应当为 const char*。 键对象是使用 PyUnicode_FromString(key) 创建的。 成功时返回 0,失败时返回 -1。 此函数 不会 附带对 val 的引用。

int PyDict_DelItem(PyObject *p, PyObject *key)
Part of the Stable ABI.

移除字典 p 中键为 key 的条目。 key 必须是可哈希的;如果不是,则会引发 TypeError。 如果字典中没有 key,则会引发 KeyError。 成功时返回 0,失败时返回 -1

int PyDict_DelItemString(PyObject *p, const char *key)
Part of the Stable ABI.

移除字典 p 中由字符串 key 指定的键的条目。 如果字典中没有 key,则会引发 KeyError。 成功时返回 0,失败时返回 -1

PyObject *PyDict_GetItem(PyObject *p, PyObject *key)
Return value: Borrowed reference. Part of the Stable ABI.

从字典 p 中返回以 key 为键的对象。 如果键名 key 不存在但 没有 设置一个异常则返回 NULL

需要注意的是,调用 __hash__()__eq__() 方法产生的异常不会被抛出。改用 PyDict_GetItemWithError() 获得错误报告。

3.10 版更變: 在不保持 GIL 的情况下调用此 API 曾因历史原因而被允许。 现在已不再被允许。

PyObject *PyDict_GetItemWithError(PyObject *p, PyObject *key)
Return value: Borrowed reference. Part of the Stable ABI.

PyDict_GetItem() 的变种,它不会屏蔽异常。 当异常发生时将返回 NULL 并且 设置一个异常。 如果键不存在则返回 NULL 并且不会 设置一个异常。

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__() 方法和创建一个临时的字符串对象时产生的异常不会被抛出。改用 PyDict_GetItemWithError() 获得错误报告。

PyObject *PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *defaultobj)
Return value: Borrowed reference.

这跟Python层面的 dict.setdefault() 一样。如果键 key 存在,它返回在字典 p 里面对应的值。如果键不存在,它会和值 defaultobj 一起插入并返回 defaultobj 。这个函数只计算 key 的哈希函数一次,而不是在查找和插入时分别计算它。

3.4 版新加入.

PyObject *PyDict_Items(PyObject *p)
Return value: New reference. Part of the Stable ABI.

返回一个包含字典中所有键值项的 PyListObject

PyObject *PyDict_Keys(PyObject *p)
Return value: New reference. Part of the Stable ABI.

返回一个包含字典中所有键(keys)的 PyListObject

PyObject *PyDict_Values(PyObject *p)
Return value: New reference. Part of the Stable ABI.

返回一个包含字典中所有值(values)的 PyListObject

Py_ssize_t PyDict_Size(PyObject *p)
Part of the Stable ABI.

返回字典中项目数,等价于对字典 p 使用 len(p)

int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)
Part of the Stable ABI.

迭代字典 p 中的所有键值对。 在第一次调用此函数开始迭代之前,由 ppos 所引用的 Py_ssize_t 必须被初始化为 0;该函数将为字典中的每个键值对返回真值,一旦所有键值对都报告完毕则返回假值。 形参 pkeypvalue 应当指向 PyObject* 变量,它们将分别使用每个键和值来填充,或者也可以为 NULL。 通过它们返回的任何引用都是暂借的。 ppos 在迭代期间不应被更改。 它的值表示内部字典结构中的偏移量,并且由于结构是稀疏的,因此偏移量并不连续。

舉例來說:

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

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

字典 p 不应该在遍历期间发生改变。在遍历字典时,改变键中的值是安全的,但仅限于键的集合不发生改变。例如:

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 进行迭代,将键值对添加到字典 ab 可以是一个字典,或任何支持 PyMapping_Keys()PyObject_GetItem() 的对象。 如果 override 为真值,则如果在 b 中找到相同的键则 a 中已存在的相应键值对将被替换,否则如果在 a 中没有相同的键则只是添加键值对。 当成功时返回 0 或者当引发异常时返回 -1

int PyDict_Update(PyObject *a, PyObject *b)
Part of the Stable ABI.

这与 C 中的 PyDict_Merge(a, b, 1) 一样,也类似于 Python 中的 a.update(b),差别在于 PyDict_Update() 在第二个参数没有 "keys" 属性时不会回退到迭代键值对的序列。 当成功时返回 0 或者当引发异常时返回 -1

int PyDict_MergeFromSeq2(PyObject *a, PyObject *seq2, int override)
Part of the Stable ABI.

seq2 中的键值对更新或合并到字典 aseq2 必须为产生长度为 2 的用作键值对的元素的可迭代对象。 当存在重复的键时,如果 override 真值则最后出现的键胜出。 当成功时返回 0 或者当引发异常时返回 -1。 等价的 Python 代码(返回值除外):

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