字典对象

xhz

type PyDictObject
这个 PyObject 的子类型代表一个Python字典对象。

PyTypeObject PyDict_Type
属于 稳定 ABI.
Python字典类型表示为 PyTypeObject 的实例。这与Python层面的 dict 是相同的对象。

int PyDict_Check(PyObject *p)
如果 p 是一个 dict 对象或者 dict 类型的子类型的实例则返回真值。 此函数总是会成功执行。

int PyDict_CheckExact(PyObject *p)
如果 p 是一个 dict 对象但不是 dict 类型的子类型的实例则返回真值。 此函数总是会成功执行。

PyObject *PyDict_New()
返回值：新的引用。 属于 稳定 ABI.
返回一个新的空字典，失败时返回 NULL。

PyObject *PyDictProxy_New(PyObject *mapping)
返回值：新的引用。 属于 稳定 ABI.
返回 types.MappingProxyType 对象，用于强制执行只读行为的映射。这通常用于创建视图以防止修改非动态类类型的字典。

void PyDict_Clear(PyObject *p)
属于 稳定 ABI.
清空现有字典的所有键值对。

int PyDict_Contains(PyObject *p, PyObject *key)
属于 稳定 ABI.
确定 key 是否包含在字典 p 中。如果 key 匹配上 p 的某一项，则返回 1 ，否则返回 0 。返回 -1 表示出错。这等同于Python表达式 key in p 。

PyObject *PyDict_Copy(PyObject *p)
返回值：新的引用。 属于 稳定 ABI.
返回与 p 包含相同键值对的新字典。

int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)
属于 稳定 ABI.
使用 key 作为键将 val 插入字典 p。 key 必须为 hashable；如果不是，则将引发 TypeError。 成功时返回 0，失败时返回 -1。 此函数 不会 附带对 val 的引用。

int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)
属于 稳定 ABI.
这与 PyDict_SetItem() 相同，但 key 被指定为 const char* UTF-8 编码的字节串，而不是 PyObject*。

int PyDict_DelItem(PyObject *p, PyObject *key)
属于 稳定 ABI.
移除字典 p 中键为 key 的条目。 key 必须是 hashable；如果不是，则会引发 TypeError。 如果字典中没有 key，则会引发 KeyError。 成功时返回 0 或者失败时返回 -1。

int PyDict_DelItemString(PyObject *p, const char *key)
属于 稳定 ABI.
这与 PyDict_DelItem() 相同，但 key 被指定为 const char* UTF-8 编码的字节串，而不是 PyObject*。

PyObject *PyDict_GetItem(PyObject *p, PyObject *key)
返回值：借入的引用。 属于 稳定 ABI.
从字典 p 中返回以 key 为键的对象。 如果键名 key 不存在但 没有 设置一个异常则返回 NULL。

备注 在调用 __hash__() 和 __eq__() 方法时发生的异常将被静默地忽略。 建议改用 PyDict_GetItemWithError() 函数。
在 3.10 版本发生变更: 在不保持 GIL 的情况下调用此 API 曾因历史原因而被允许。 现在已不再被允许。

PyObject *PyDict_GetItemWithError(PyObject *p, PyObject *key)
返回值：借入的引用。 属于 稳定 ABI.
PyDict_GetItem() 的变种，它不会屏蔽异常。 当异常发生时将返回 NULL 并且 设置一个异常。 如果键不存在则返回 NULL 并且不会 设置一个异常。

PyObject *PyDict_GetItemString(PyObject *p, const char *key)
返回值：借入的引用。 属于 稳定 ABI.
这与 PyDict_GetItem() 一样，但 key 是由一个 const char* UTF-8 编码的字节串来指定的，而不是 PyObject*。

备注 在调用 __hash__() 和 __eq__() 方法时或者在创建临时 str 对象期间发生的异常将被静默地忽略。 建议改用 PyDict_GetItemWithError() 函数并附带你自己的 PyUnicode_FromString() key。
PyObject *PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *defaultobj)
返回值：借入的引用。
这跟Python层面的 dict.setdefault() 一样。如果键 key 存在，它返回在字典 p 里面对应的值。如果键不存在，它会和值 defaultobj 一起插入并返回 defaultobj 。这个函数只计算 key 的哈希函数一次，而不是在查找和插入时分别计算它。

在 3.4 版本加入.

PyObject *PyDict_Items(PyObject *p)
返回值：新的引用。 属于 稳定 ABI.
返回一个包含字典中所有键值项的 PyListObject。

PyObject *PyDict_Keys(PyObject *p)
返回值：新的引用。 属于 稳定 ABI.
返回一个包含字典中所有键(keys)的 PyListObject。

PyObject *PyDict_Values(PyObject *p)
返回值：新的引用。 属于 稳定 ABI.
返回一个包含字典中所有值(values)的 PyListObject。

Py_ssize_t PyDict_Size(PyObject *p)
属于 稳定 ABI.
返回字典中项目数，等价于对字典 p 使用 len(p)。

int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)
属于 稳定 ABI.
迭代字典 p 中的所有键值对。 在第一次调用此函数开始迭代之前，由 ppos 所引用的 Py_ssize_t 必须被初始化为 0；该函数将为字典中的每个键值对返回真值，一旦所有键值对都报告完毕则返回假值。 形参 pkey 和 pvalue 应当指向 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)
属于 稳定 ABI.
对映射对象 b 进行迭代，将键值对添加到字典 a。 b 可以是一个字典，或任何支持 PyMapping_Keys() 和 PyObject_GetItem() 的对象。 如果 override 为真值，则如果在 b 中找到相同的键则 a 中已存在的相应键值对将被替换，否则如果在 a 中没有相同的键则只是添加键值对。 当成功时返回 0 或者当引发异常时返回 -1。

int PyDict_Update(PyObject *a, PyObject *b)
属于 稳定 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)
属于 稳定 ABI.
将 seq2 中的键值对更新或合并到字典 a。 seq2 必须为产生长度为 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
int PyDict_AddWatcher(PyDict_WatchCallback callback)
在字典上注册 callback 来作为 watcher。返回值为非负数的整数 id，作为将来调用 PyDict_Watch() 的时候使用。如果出现错误（比如没有足够的可用 watcher ID），返回 -1 并且设置异常。

在 3.12 版本加入.

int PyDict_ClearWatcher(int watcher_id)
清空由之前从 PyDict_AddWatcher() 返回的 watcher_id 所标识的 watcher。 成功时返回 0，出错时（例如当给定的 watcher_id 未被注册）返回 -1。

在 3.12 版本加入.

int PyDict_Watch(int watcher_id, PyObject *dict)
将字典 dict 标记为已被监视。 由 PyDict_AddWatcher() 授权 watcher_id 对应的回调将在 dict 被修改或释放时被调用。 成功时返回 0，出错时返回 -1。

在 3.12 版本加入.

int PyDict_Unwatch(int watcher_id, PyObject *dict)
将字典 dict 标记为不再被监视。 由 PyDict_AddWatcher() 授权 watcher_id 对应的回调在 dict 被修改或释放时将不再被调用。 该字典在此之前必须已被此监视器所监视。 成功时返回 0，出错时返回 -1。

在 3.12 版本加入.

type PyDict_WatchEvent
由以下可能的字典监视器事件组成的枚举: PyDict_EVENT_ADDED, PyDict_EVENT_MODIFIED, PyDict_EVENT_DELETED, PyDict_EVENT_CLONED, PyDict_EVENT_CLEARED 或 PyDict_EVENT_DEALLOCATED。

在 3.12 版本加入.

typedef int (*PyDict_WatchCallback)(PyDict_WatchEvent event, PyObject *dict, PyObject *key, PyObject *new_value)
字典监视器回调函数的类型。

如果 event 是 PyDict_EVENT_CLEARED 或 PyDict_EVENT_DEALLOCATED，则 key 和 new_value 都将为 NULL。 如果 event 是 PyDict_EVENT_ADDED 或 PyDict_EVENT_MODIFIED，则 new_value 将为 key 的新值。 如果 event 是 PyDict_EVENT_DELETED，则将从字典中删除 key 而 new_value 将为 NULL。

PyDict_EVENT_CLONED 会在另一个字典合并到之前为空的 dict 时发生。 为保证此操作的效率，该场景不会发出针对单个键的 PyDict_EVENT_ADDED 事件；而是发出单个 PyDict_EVENT_CLONED，而 key 将为源字典。

该回调可以检查但不能修改 dict；否则会产生不可预料的影响，包括无限递归。 请不要在该回调中触发 Python 代码的执行，因为它可能产生修改 dict 的附带影响。

如果 event 是 PyDict_EVENT_DEALLOCATED，则在回调中接受一个对即将销毁的字典的新引用将使其重生并阻止其在此时被释放。 当重生的对象以后再被销毁时，任何在当时已激活的监视器回调将再次被调用。

回调会在已通知的对 dict 的修改完成之前执行，这样在此之前的 dict 状态可以被检查。

如果该回调设置了一个异常，则它必须返回 -1；此异常将作为不可引发的异常使用 PyErr_WriteUnraisable() 打印出来。 在其他情况下它应当返回 0。

在进入回调时可能已经设置了尚未处理的异常。 在此情况下，回调应当返回 0 并仍然设置同样的异常。 这意味着该回调可能不会调用任何其他可设置异常的 API 除非它先保存并清空异常状态，并在返回之前恢复它。

在 3.12 版本加入.