字典对象 — Python 文档
字典对象
- type PyDictObject
- PyObject 的这个子类型表示一个 Python 字典对象。
- PyTypeObject PyDict_Type
- PyTypeObject 的这个实例表示 Python 字典类型。 这与 Python 层中的 dict 是同一个对象。
- int PyDict_Check(PyObject *p)
- 如果 p 是 dict 对象或 dict 类型的子类型的实例,则返回 true。
- int PyDict_CheckExact(PyObject *p)
- 如果 p 是 dict 对象,但不是 dict 类型的子类型的实例,则返回 true。
- PyObject *PyDict_New()
- 返回一个新的空字典,或者失败时返回
NULL
。
- 为强制执行只读行为的映射返回一个 types.MappingProxyType 对象。 这通常用于创建视图以防止修改非动态类类型的字典。
- void PyDict_Clear(PyObject *p)
- 清空所有键值对的现有字典。
- 确定字典 p 是否包含 key。 如果 p 中的一项与 key 匹配,则返回
1
,否则返回0
。 出错时,返回-1
。 这相当于 Python 表达式key in p
。
- 返回包含与 p 相同的键值对的新字典。
- 使用 key 作为键将 value 插入字典 p。 key 应该是
const char*
。 关键对象是使用PyUnicode_FromString(key)
创建的。 成功时返回0
,失败时返回-1
。
- 使用键 key 删除字典 p 中的条目。 key 必须是可散列的; 如果不是,则引发 TypeError。 成功时返回
0
,失败时返回-1
。
- int PyDict_DelItemString(PyObject *p, const char *key)
- 删除字典 p 中的条目,该条目具有由字符串 key 指定的键。 成功时返回
0
,失败时返回-1
。
- PyObject *PyDict_GetItem(PyObject *p, PyObject *key)
从字典 p 返回具有键 key 的对象。 如果键 key 不存在,则返回
NULL
,但 没有 设置异常。请注意,调用
__hash__()
和__eq__()
方法时发生的异常将被抑制。 要获得错误报告,请改用 PyDict_GetItemWithError()。
- PyDict_GetItem() 不抑制异常的变体。 如果发生异常,则返回
NULL
和 异常集。 如果密钥不存在,则返回NULL
不带 异常集。
- PyObject *PyDict_GetItemString(PyObject *p, const char *key)
这与 PyDict_GetItem() 相同,但 key 被指定为
const char*
,而不是PyObject*
。请注意,调用
__hash__()
和__eq__()
方法以及创建临时字符串对象时发生的异常将被抑制。 要获得错误报告,请改用 PyDict_GetItemWithError()。
- PyObject *PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *defaultobj)
这与 Python 级别的 dict.setdefault() 相同。 如果存在,它会从字典 p 中返回对应于 key 的值。 如果键不在 dict 中,则将其插入值 defaultobj 并返回 defaultobj。 该函数仅对 key 的哈希函数求值一次,而不是为查找和插入独立求值。
3.4 版中的新功能。
- 返回包含字典中所有项目的 PyListObject。
- 返回包含字典中所有键的 PyListObject。
- 返回包含字典 p 中所有值的 PyListObject。
- Py_ssize_t PyDict_Size(PyObject *p)
- 返回字典中的项目数。 这相当于字典上的
len(p)
。
- int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)
迭代字典 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); }
- 迭代映射对象 b,将键值对添加到字典 a。 b 可以是字典,或任何支持 PyMapping_Keys() 和 PyObject_GetItem() 的对象。 如果 override 为真,如果在 b 中找到匹配的键,则 a 中的现有对将被替换,否则仅在没有匹配键时才添加对a 中的匹配键。 成功时返回
0
,如果引发异常则返回-1
。
- 这与 C 中的
PyDict_Merge(a, b, 1)
相同,并且与 Python 中的a.update(b)
类似,除了 PyDict_Update() 不会回退到迭代键序列如果第二个参数没有“keys”属性,则值对。 成功时返回0
,如果引发异常则返回-1
。
- int PyDict_MergeFromSeq2(PyObject *a, PyObject *seq2, int override)
从 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_ClearFreeList()
清除空闲列表。 返回已释放项目的总数。
3.3 版中的新功能。