字典对象¶

type PyDictObject¶: 此 PyObject 子类型表示一个 Python 字典对象。

PyTypeObject PyDict_Type¶: 作为稳定 ABI 的一部分。
此 PyTypeObject 实例表示 Python 字典类型。这与 Python 层中的 dict 对象相同。

int PyDict_Check(PyObject *p)¶: 如果 p 是一个字典对象或是字典类型子类的实例，则返回 true。此函数始终成功。

int PyDict_CheckExact(PyObject *p)¶: 如果 p 是一个字典对象，但不是字典类型子类的实例，则返回 true。此函数始终成功。

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 的一部分。
确定字典 p 是否包含 key。如果 p 中的某个项与 key 匹配，则返回 1，否则返回 0。发生错误时，返回 -1。这等价于 Python 表达式 key in p。

int PyDict_ContainsString(PyObject *p, const char *key)¶: 这与 PyDict_Contains() 相同，但 key 被指定为 const char* UTF-8 编码的字节字符串，而不是 PyObject*。

在 3.13 版本加入。

PyObject *PyDict_Copy(PyObject *p)¶: 返回值: 新引用。 稳定ABI 的一部分。
返回一个新字典，其中包含与 p 相同的键值对。

int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)¶: 作为稳定 ABI 的一部分。
使用 key 作为键将 val 插入到字典 p 中。key 必须是可哈希的；如果不是，将引发 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 必须是可哈希的；如果不是，将引发 TypeError。如果字典中不存在 key，将引发 KeyError。成功时返回 0，失败时返回 -1。

int PyDict_DelItemString(PyObject *p, const char *key)¶: 作为稳定 ABI 的一部分。
这与 PyDict_DelItem() 相同，但 key 被指定为 const char* UTF-8 编码的字节字符串，而不是 PyObject*。

int PyDict_GetItemRef(PyObject *p, PyObject *key, PyObject **result)¶

自 3.13 版本起成为稳定 ABI 的一部分。

返回对字典 p 中键为 key 的对象的新的强引用

如果键存在，则将 *result 设置为对该值的新强引用并返回 1。
如果键缺失，则将 *result 设置为 NULL 并返回 0。
如果发生错误，则引发异常并返回 -1。

在 3.13 版本加入。

另请参见 PyObject_GetItem() 函数。

PyObject *PyDict_GetItem(PyObject *p, PyObject *key)¶: 返回值: 借用引用。 稳定ABI 的一部分。
返回对字典 p 中键为 key 的对象的借用引用。如果键 key 缺失，则返回 NULL，不设置异常。

备注

此函数在调用 __hash__() 和 __eq__() 方法时发生的异常会被静默忽略。建议改用 PyDict_GetItemWithError() 函数。

3.10 版中已更改: 出于历史原因，此前允许在没有附加线程状态的情况下调用此 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。

int PyDict_GetItemStringRef(PyObject *p, const char *key, PyObject **result)¶: 自 3.13 版本起成为稳定 ABI 的一部分。
类似于 PyDict_GetItemRef()，但 key 被指定为 const char* UTF-8 编码的字节字符串，而不是 PyObject*。

在 3.13 版本加入。

PyObject *PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *defaultobj)¶: 返回值：借用引用。
这与 Python 级别的 dict.setdefault() 相同。如果存在，它返回字典 p 中与 key 对应的值。如果键不在字典中，则使用 defaultobj 插入该键，并返回 defaultobj。此函数只评估 key 的哈希函数一次，而不是对查找和插入分别评估。

在 3.4 版本加入。

int PyDict_SetDefaultRef(PyObject *p, PyObject *key, PyObject *default_value, PyObject **result)¶

如果键尚未在字典中，则将 default_value 插入到字典 p 中，键为 key。如果 result 不为 NULL，则将 *result 设置为对 default_value （如果键不存在）或现有值（如果 key 已存在于字典中）的强引用。如果键存在且未插入 default_value，则返回 1；如果键不存在且已插入 default_value，则返回 0。失败时，返回 -1，设置异常，并将 *result 设置为 NULL。

为了清楚起见：如果您在调用此函数之前持有对 default_value 的强引用，则在函数返回后，您将持有对 default_value 和 *result （如果它不为 NULL）的强引用。它们可能指向同一个对象：在这种情况下，您持有对它的两个独立引用。

在 3.13 版本加入。

int PyDict_Pop(PyObject *p, PyObject *key, PyObject **result)¶

从字典 p 中移除 key，并可选择返回移除的值。如果键缺失，则不引发 KeyError。

如果键存在，如果 result 不为 NULL，则将 *result 设置为对移除值的新引用，并返回 1。
如果键缺失，如果 result 不为 NULL，则将 *result 设置为 NULL，并返回 0。
如果发生错误，则引发异常并返回 -1。

类似于 dict.pop()，但没有默认值，并且如果键缺失，则不引发 KeyError。

在 3.13 版本加入。

int PyDict_PopString(PyObject *p, const char *key, PyObject **result)¶: 类似于 PyDict_Pop()，但 key 被指定为 const char* UTF-8 编码的字节字符串，而不是 PyObject*。

在 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_t PyDict_Size(PyObject *p)¶: 作为稳定 ABI 的一部分。
返回字典中的项数。这等价于对字典执行 len(p)。

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

作为稳定 ABI 的一部分。

迭代字典 p 中的所有键值对。ppos 所指的 Py_ssize_t 在首次调用此函数开始迭代之前必须初始化为 0；函数对字典中的每个对返回 true，一旦所有对都被报告，则返回 false。参数 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);
}

在自由线程构建中，此函数在没有外部同步的情况下不是线程安全的。您可以使用 Py_BEGIN_CRITICAL_SECTION 在迭代字典时锁定它。

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

备注

在自由线程构建中，此函数可以在临界区内安全使用。但是，为 pkey 和 pvalue 返回的引用是借用引用，仅在持有临界区时有效。如果您需要在临界区外或临界区可能被挂起时使用这些对象，请创建强引用（例如，使用 Py_NewRef()）。

int PyDict_Merge(PyObject *a, PyObject *b, int override)¶: 作为稳定 ABI 的一部分。
迭代映射对象 b，将键值对添加到字典 a 中。b 可以是字典，也可以是任何支持 PyMapping_Keys() 和 PyObject_GetItem() 的对象。如果 override 为 true，则如果 b 中找到匹配的键，则替换 a 中的现有对，否则只有当 a 中没有匹配的键时才添加对。成功时返回 0，如果引发异常则返回 -1。

int PyDict_Update(PyObject *a, PyObject *b)¶: 作为稳定 ABI 的一部分。
这与 C 中的 PyDict_Merge(a, b, 1) 相同，并且类似于 Python 中的 a.update(b)，不同之处在于，如果第二个参数没有“keys”属性，PyDict_Update() 不会退回到迭代键值对序列。成功时返回 0，如果引发异常则返回 -1。

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

作为稳定 ABI 的一部分。

从 seq2 中的键值对更新或合并到字典 a 中。seq2 必须是一个可迭代对象，产生长度为 2 的可迭代对象，并将其视为键值对。如果存在重复键，如果 override 为 true，则最后一个获胜，否则第一个获胜。成功时返回 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 注册为字典观察器。返回一个非负整数 ID，该 ID 必须传递给未来对 PyDict_Watch() 的调用。如果发生错误（例如，没有可用的观察器 ID），则返回 -1 并设置异常。

3.12 新版功能.

int PyDict_ClearWatcher(int watcher_id)¶: 清除之前从 PyDict_AddWatcher() 返回的由 watcher_id 标识的观察器。成功时返回 0，错误时返回 -1（例如，如果给定的 watcher_id 从未注册）。

3.12 新版功能.

int PyDict_Watch(int watcher_id, PyObject *dict)¶: 将字典 dict 标记为被监视。当 dict 被修改或解除分配时，PyDict_AddWatcher() 授予 watcher_id 的回调将被调用。成功时返回 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。

当 dict 之前为空并且另一个字典合并到其中时，会发生 PyDict_EVENT_CLONED。为了保持此操作的效率，在这种情况下不会发出按键的 PyDict_EVENT_ADDED 事件；而是发出单个 PyDict_EVENT_CLONED，并且 key 将是源字典。

回调可以检查但不得修改 dict；这样做可能会产生不可预测的影响，包括无限递归。不要在回调中触发 Python 代码执行，因为这可能会作为副作用修改字典。

如果 event 是 PyDict_EVENT_DEALLOCATED，在回调中获取对即将销毁的字典的新引用将使其复活并阻止它在此刻被释放。当复活的对象稍后被销毁时，当时处于活动状态的任何观察器回调将再次被调用。

回调发生在对 dict 的通知修改之前，因此可以检查 dict 的先前状态。

如果回调设置了异常，它必须返回 -1；此异常将使用 PyErr_WriteUnraisable() 打印为无法引发的异常。否则，它应该返回 0。

进入回调时可能已经设置了挂起异常。在这种情况下，回调应返回 0，并保持相同的异常设置。这意味着回调不能调用任何其他可能设置异常的 API，除非它首先保存并清除异常状态，并在返回之前恢复它。

3.12 新版功能.

字典对象¶

上一主题

下一主题

本页