字典对象¶
-
PyTypeObject PyDict_Type¶
- 属于 稳定 ABI.
Python 字典类型表示为
PyTypeObject的实例。这与 Python 层面的dict是相同的对象。
-
int PyDict_Check(PyObject *p)¶
- Thread safety: Atomic.
如果 p 是一个 dict 对象或者 dict 类型的子类型的实例则返回真值。此函数总是会成功执行。
-
int PyDict_CheckExact(PyObject *p)¶
- Thread safety: Atomic.
如果 p 是一个 dict 对象但不是 dict 类型的子类型的实例则返回真值。此函数总是会成功执行。
-
PyObject *PyDictProxy_New(PyObject *mapping)¶
- 返回值:新的引用。 属于 稳定 ABI.
返回
types.MappingProxyType对象,用于强制执行只读行为的映射。这通常用于创建视图以防止修改非动态类类型的字典。第一个参数可以是
dict,frozendict或映射。在 3.15 版本发生变更: 也接受
frozendict。
-
PyTypeObject PyDictProxy_Type¶
- 属于 稳定 ABI.
对应于由
PyDictProxy_New()创建的映射代理对象和许多内置类型的只读__dict__属性的类型对象。PyDictProxy_Type实例提供下层字典的动态、只读视图:对下层字典的修改将反映在代理中,但代理本身不支持修改操作。这对应于 Python 中的types.MappingProxyType。
-
void PyDict_Clear(PyObject *p)¶
- 属于 稳定 ABI. Thread safety: Atomic.
清空现有字典的所有键值对。
如果参数不是
dict或dict的子类则不做任何事。
-
int PyDict_Contains(PyObject *p, PyObject *key)¶
- 属于 稳定 ABI. Thread safety: Safe for concurrent use on the same object.
确定字典 p 是否包含 key。如果 p 中的某一项与 key 匹配,则返回
1,否则返回0。当出错时,返回-1。这等价于 Python 表达式key in p。第一个参数可以是
dict或frozendict。在 3.15 版本发生变更: 也接受
frozendict。
-
int PyDict_ContainsString(PyObject *p, const char *key)¶
- Thread safety: Atomic.
这与
PyDict_Contains()相同,但 key 被指定为一个 const char* UTF-8 编码的字节串,而不是 PyObject*。第一个参数可以是
dict或frozendict。在 3.13 版本加入.
在 3.15 版本发生变更: 也接受
frozendict。
-
int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)¶
- 属于 稳定 ABI. Thread safety: Safe for concurrent use on the same object.
将 val 插入到字典 p 中,以 key 作为键。 key 必须是 hashable;如果不是,则会引发
TypeError。 成功时返回0或者失败时返回-1。 此函数 不会 "steal" 对 val 的引用。
-
int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)¶
- 属于 稳定 ABI. Thread safety: Atomic.
这与
PyDict_SetItem()相同,但 key 被指定为 const char* UTF-8 编码的字节串,而不是 PyObject*。
-
int PyDict_DelItem(PyObject *p, PyObject *key)¶
- 属于 稳定 ABI. Thread safety: Safe for concurrent use on the same object.
移除字典 p 中键为 key 的条目。key 必须是 hashable;如果不是,则会引发
TypeError。如果字典中没有 key,则会引发KeyError。成功时返回0或者失败时返回-1。
-
int PyDict_DelItemString(PyObject *p, const char *key)¶
- 属于 稳定 ABI. Thread safety: Atomic.
这与
PyDict_DelItem()相同,但 key 被指定为 const char* UTF-8 编码的字节串,而不是 PyObject*。
-
int PyDict_GetItemRef(PyObject *p, PyObject *key, PyObject **result)¶
- 属于 稳定 ABI 自 3.13 版起. Thread safety: Safe for concurrent use on the same object.
返回一个新的指向字典 p 中对应键 key 的对象的 strong reference:
如果存在该键,则将 *result 设为一个新的指向该值的 strong reference 并返回
1。如果不存在该键,则将 *result 设为
NULL并返回0。发生错误时,引发一个异常,将 *result 设为
NULL并返回-1。
第一个参数可以是
dict或frozendict。在 3.13 版本加入.
在 3.15 版本发生变更: 也接受
frozendict。另请参阅
PyObject_GetItem()函数。
-
PyObject *PyDict_GetItem(PyObject *p, PyObject *key)¶
- 返回值:借入的引用。 属于 稳定 ABI. Thread safety: Safe to call from multiple threads with external synchronization only.
返回一个指向字典 p 中对应键 key 的对象的 borrowed reference。如果不存在键 key 则返回
NULL且 不会 设置异常。第一个参数可以是
dict或frozendict。备注
在调用
__hash__()和__eq__()方法时发生的异常将被静默地忽略。建议改用PyDict_GetItemWithError()函数。备注
In the free-threaded build, the returned borrowed reference may become invalid if another thread modifies the dictionary concurrently. Prefer
PyDict_GetItemRef(), which returns a strong reference.在 3.10 版本发生变更: 出于历史原因,曾经允许在没有附加线程状态 attached thread state 的情况下调用这个 API,但现在已经不再允许了。
在 3.15 版本发生变更: 也接受
frozendict。
-
PyObject *PyDict_GetItemWithError(PyObject *p, PyObject *key)¶
- 返回值:借入的引用。 属于 稳定 ABI. Thread safety: Safe to call from multiple threads with external synchronization only.
PyDict_GetItem()的变种,它不会屏蔽异常。当异常发生时将返回NULL并且 设置一个异常。如果键不存在则返回NULL并且不会 设置一个异常。备注
In the free-threaded build, the returned borrowed reference may become invalid if another thread modifies the dictionary concurrently. Prefer
PyDict_GetItemRef(), which returns a strong reference.在 3.15 版本发生变更: 也接受
frozendict。
-
PyObject *PyDict_GetItemString(PyObject *p, const char *key)¶
- 返回值:借入的引用。 属于 稳定 ABI. Thread safety: Safe to call from multiple threads with external synchronization only.
这与
PyDict_GetItem()一样,但 key 是由一个 const char* UTF-8 编码的字节串来指定的,而不是 PyObject*。备注
在调用
__hash__()和__eq__()方法时或者在创建临时str对象期间发生的异常将被静默地忽略。建议改用PyDict_GetItemWithError()函数并附带你自己的PyUnicode_FromString()key。备注
In the free-threaded build, the returned borrowed reference may become invalid if another thread modifies the dictionary concurrently. Prefer
PyDict_GetItemStringRef(), which returns a strong reference.在 3.15 版本发生变更: 也接受
frozendict。
-
int PyDict_GetItemStringRef(PyObject *p, const char *key, PyObject **result)¶
- 属于 稳定 ABI 自 3.13 版起. Thread safety: Atomic.
类似于
PyDict_GetItemRef(),但 key 被指定为一个 const char* UTF-8 编码的字节串,而不是 PyObject*。在 3.13 版本加入.
在 3.15 版本发生变更: 也接受
frozendict。
-
PyObject *PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *defaultobj)¶
- 返回值:借入的引用。 Thread safety: Safe to call from multiple threads with external synchronization only.
这跟 Python 层面的
dict.setdefault()一样。如果键 key 存在,它返回在字典 p 里面对应的值。如果键不存在,它会和值 defaultobj 一起插入并返回 defaultobj 。这个函数只计算 key 的哈希函数一次,而不是在查找和插入时分别计算它。在 3.4 版本加入.
备注
In the free-threaded build, the returned borrowed reference may become invalid if another thread modifies the dictionary concurrently. Prefer
PyDict_SetDefaultRef(), which returns a strong reference.
-
int PyDict_SetDefaultRef(PyObject *p, PyObject *key, PyObject *default_value, PyObject **result)¶
- 属于 稳定 ABI 自 3.15 版起. Thread safety: Safe for concurrent use on the same object.
如果键 key 在字典 p 中尚不存在则将该键和值 default_value 插入到该字典中。如果 result 不为
NULL,那么当该键不存在时将 *result 设为指向 default_value 的 strong reference,或者当 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)¶
- Thread safety: Safe for concurrent use on the same object.
将 key 从字典 p 中移除并可选择返回被移除的值。当键不存在时不会引发
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)¶
- Thread safety: Atomic.
类似于
PyDict_Pop(),但 key 是以一个 const char* UTF-8 编码的字节串形式指定的,而不是 PyObject*。在 3.13 版本加入.
-
PyObject *PyDict_Items(PyObject *p)¶
- 返回值:新的引用。 属于 稳定 ABI. Thread safety: Atomic.
返回一个包含字典中所有键值项的
PyListObject。第一个参数可以是
dict或frozendict。在 3.15 版本发生变更: 也接受
frozendict。
-
PyObject *PyDict_Keys(PyObject *p)¶
- 返回值:新的引用。 属于 稳定 ABI. Thread safety: Atomic.
返回一个包含字典中所有键 (keys) 的
PyListObject。第一个参数可以是
dict或frozendict。在 3.15 版本发生变更: 也接受
frozendict。
-
PyObject *PyDict_Values(PyObject *p)¶
- 返回值:新的引用。 属于 稳定 ABI. Thread safety: Atomic.
返回一个包含字典中所有值 (values) 的
PyListObject。第一个参数可以是
dict或frozendict。在 3.15 版本发生变更: 也接受
frozendict。
-
Py_ssize_t PyDict_Size(PyObject *p)¶
- 属于 稳定 ABI. Thread safety: Atomic.
返回字典中项目数,等价于对字典 p 使用
len(p)。The argument can be a
dictor afrozendict.在 3.15 版本发生变更: 也接受
frozendict。
-
Py_ssize_t PyDict_GET_SIZE(PyObject *p)¶
- Thread safety: Atomic.
类似于
PyDict_Size(),但是不带错误检查。在 3.15 版本发生变更: 也接受
frozendict。
-
int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)¶
- 属于 稳定 ABI. Thread safety: Safe to call from multiple threads with external synchronization only.
迭代字典 p 中的所有键值对。在第一次调用此函数开始迭代之前,由 ppos 所引用的
Py_ssize_t必须被初始化为0;该函数将为字典中的每个键值对返回真值,一旦所有键值对都报告完毕则返回假值。形参 pkey 和 pvalue 应当指向 PyObject* 变量,它们将分别使用每个键和值来填充,或者也可以为NULL。通过它们返回的任何引用都是暂借的。ppos 在迭代期间不应被更改。它的值表示内部字典结构中的偏移量,并且由于结构是稀疏的,因此偏移量并不连续。第一个参数可以是
dict或frozendict。例如:
PyObject *key, *value; Py_ssize_t pos = 0; while (PyDict_Next(self->dict, &pos, &key, &value)) { /* 用这些值做些有趣的事... */ ... }
字典 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); }
The function is not thread-safe in the free-threaded build without external synchronization for a mutable
dict. You can usePy_BEGIN_CRITICAL_SECTIONto lock the dictionary while iterating over it:Py_BEGIN_CRITICAL_SECTION(self->dict); while (PyDict_Next(self->dict, &pos, &key, &value)) { ... } Py_END_CRITICAL_SECTION();
The function is thread-safe on a
frozendict.备注
在自由线程构建版中,此函数可在关键节内部安全地使用。不过,针对 pkey 和 pvalue 返回的引用是 借入引用 并且仅在关键节被持有时有效。如果你需要在关键节之外或是在关键节可被挂起时使用这些对象,则要创建 强引用 (例如,使用
Py_NewRef())。在 3.15 版本发生变更: 也接受
frozendict。
-
int PyDict_Merge(PyObject *a, PyObject *b, int override)¶
- 属于 稳定 ABI. Thread safety: Safe for concurrent use on the same object.
对映射对象 b 进行迭代,将键值对添加到字典 a。b 可以是一个字典,或任何支持
PyMapping_Keys()和PyObject_GetItem()的对象。如果 override 为真值,则如果在 b 中找到相同的键则 a 中已存在的相应键值对将被替换,否则如果在 a 中没有相同的键则只是添加键值对。当成功时返回0或者当引发异常时返回-1。备注
In the free-threaded build, when b is a
dict(with the standard iterator), both a and b are locked for the duration of the operation. When b is a non-dict mapping, only a is locked; b may be concurrently modified by another thread.
-
int PyDict_Update(PyObject *a, PyObject *b)¶
- 属于 稳定 ABI. Thread safety: Safe for concurrent use on the same object.
This is the same as
PyDict_Merge(a, b, 1)in C.Similar to
a.update(b)in Python, except that this function does not fall back to the iterating over a sequence of key-value pairs if b is not a mapping. UsePyDict_MergeFromSeq2()for this case.Return
0on success or-1if an exception was raised.备注
In the free-threaded build, when b is a
dict(with the standard iterator), both a and b are locked for the duration of the operation. When b is a non-dict mapping, only a is locked; b may be concurrently modified by another thread.
-
int PyDict_MergeFromSeq2(PyObject *a, PyObject *seq2, int override)¶
- 属于 稳定 ABI. Thread safety: Safe for concurrent use on the same object.
将 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
备注
In the free-threaded build, only a is locked. The iteration over seq2 is not synchronized; seq2 may be concurrently modified by another thread.
-
PyObject *PyDict_AsFrozenDictAndClear(PyObject *dict)¶
Return a new
frozendictcreated from the existingdictinstance.Transfers all keys and values from dict to the newly allocated
frozendict. Clears the input dict on success. ReturnsNULLwith the exception set on error.This function is intended for building a
frozendictinstance via a temporary dict that is not exposed to user code. To "freeze" an arbitrary dictionary, for example one received from the user as an argument, preferPyFrozenDict_New()to leave the source intact.Does not work for dicts with embedded values.
CPython 实现细节: Works with O(1) complexity.
在 3.16 版本加入.
-
int PyDict_AddWatcher(PyDict_WatchCallback callback)¶
- Thread safety: Safe to call from multiple threads with external synchronization only.
在字典上注册 callback 来作为 watcher。返回值为非负数的整数 id,作为将来调用
PyDict_Watch()的时候使用。如果出现错误(比如没有足够的可用 watcher ID),返回-1并且设置异常。备注
This function is not internally synchronized. In the free-threaded build, callers should ensure no concurrent calls to
PyDict_AddWatcher()orPyDict_ClearWatcher()are in progress.在 3.12 版本加入.
-
int PyDict_ClearWatcher(int watcher_id)¶
- Thread safety: Safe to call from multiple threads with external synchronization only.
清空由之前从
PyDict_AddWatcher()返回的 watcher_id 所标识的 watcher。成功时返回0,出错时(例如当给定的 watcher_id 未被注册)返回-1。备注
This function is not internally synchronized. In the free-threaded build, callers should ensure no concurrent calls to
PyDict_AddWatcher()orPyDict_ClearWatcher()are in progress.在 3.12 版本加入.
-
int PyDict_Watch(int watcher_id, PyObject *dict)¶
- Thread safety: Safe to call without external synchronization on distinct objects.
将字典 dict 标记为已被监视。由
PyDict_AddWatcher()授权 watcher_id 对应的回调将在 dict 被修改或释放时被调用。成功时返回0,出错时返回-1。在 3.12 版本加入.
-
int PyDict_Unwatch(int watcher_id, PyObject *dict)¶
- Thread safety: Safe to call without external synchronization on distinct objects.
将字典 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 版本加入.
-
PY_FOREACH_DICT_EVENT(V)¶
Apply the macro V to each suffix of
PyDict_WatchEventconstants. Currently expands toV(ADDED) V(MODIFIED) V(DELETED) V(CLONED) V(CLEARED) V(DEALLOCATED). The macro V must accept one event name and supply any punctuation needed between expansions.
-
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 版本加入.
字典视图对象¶
-
int PyDictViewSet_Check(PyObject *op)¶
如果 op 是一个字典内集合的视图则返回真值。此函数目前等价于 PyDictKeys_Check(op) || PyDictItems_Check(op)。此函数总是会成功执行。
-
PyTypeObject PyDictKeys_Type¶
- 属于 稳定 ABI.
由字典键组成的视图的类型对象。在 Python 中,这就是由
dict.keys()返回的对象的类型。
-
PyTypeObject PyDictValues_Type¶
- 属于 稳定 ABI.
由字典值组成的视图的类型对象。在 Python 中,这就是由
dict.values()返回的对象的类型。
-
PyTypeObject PyDictItems_Type¶
- 属于 稳定 ABI.
由字典条目组成的视图的类型对象。在 Python 中,这就是由
dict.items()返回的对象的类型。
冻结字典对象¶
在 3.15 版本加入.
-
PyTypeObject PyFrozenDict_Type¶
This instance of
PyTypeObjectrepresents the Python frozen dictionary type. This is the same object asfrozendictin the Python layer.
-
int PyAnyDict_Check(PyObject *p)¶
Return true if p is a
dictobject, afrozendictobject, or an instance of a subtype of thedictorfrozendicttype. This function always succeeds.
-
int PyAnyDict_CheckExact(PyObject *p)¶
Return true if p is a
dictobject or afrozendictobject, but not an instance of a subtype of thedictorfrozendicttype. This function always succeeds.
-
int PyFrozenDict_Check(PyObject *p)¶
Return true if p is a
frozendictobject or an instance of a subtype of thefrozendicttype. This function always succeeds.
-
int PyFrozenDict_CheckExact(PyObject *p)¶
Return true if p is a
frozendictobject, but not an instance of a subtype of thefrozendicttype. This function always succeeds.
-
PyObject *PyFrozenDict_New(PyObject *iterable)¶
根据一个可迭代对象返回新的
frozendict,或者失败时返回NULL并设置一个异常。on failure with an exception set.如果 iterable 为
NULL则创建一个空字典。
有序字典¶
Python 的 C API 提供了针对来自 C 的 collections.OrderedDict 的接口。从 Python 3.7 开始,字典默认就是有序的,因此通常不需要使用这些函数;只要有可能就建议使用 PyDict*。
-
PyTypeObject PyODict_Type¶
有序字典的类型对象。它与 Python 层面的
collections.OrderedDict是相同的对象。
-
int PyODict_Check(PyObject *od)¶
如果 od 是一个有序字典对象或
OrderedDict类型的子类型的实例则返回真值。此函数总是会成功执行。
-
int PyODict_CheckExact(PyObject *od)¶
如果 od 是一个有序字典对象,但不是
OrderedDict类型的子类型的实例则返回真值。此函数总是会成功执行。
-
PyTypeObject PyODictKeys_Type¶
等同于针对有序字典的
PyDictKeys_Type。
-
PyTypeObject PyODictValues_Type¶
等同于针对有序字典的
PyDictValues_Type。
-
PyTypeObject PyODictItems_Type¶
等同于针对有序字典的
PyDictItems_Type。
-
PyObject *PyODict_New(void)¶
返回一个新的空有序字典,或在失败时返回
NULL。这等同于
PyDict_New()。
-
int PyODict_SetItem(PyObject *od, PyObject *key, PyObject *value)¶
将 value 插入到有序字典 od 并将键设为 key。成功时返回
0或在失败时返回-1并设置一个异常。这等同于
PyDict_SetItem()。
-
int PyODict_DelItem(PyObject *od, PyObject *key)¶
移除有序字典 od 中键为 key 的条目。成功时返回
0或在失败时返回-1并设置一个异常。这等同于
PyDict_DelItem()。
这些是已被设为 soft deprecated 状态的 PyDict API 的别名:
|
|
|---|---|
|
|
|
|
|
|
|
|
|
|
|