# Dictionary Objects

type PyDictObject

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

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 *PyDict_New()
  返回值：新的引用。 属于 稳定 ABI. Thread safety: Atomic.

  返回一个新的空字典，失败时返回 `NULL`。

PyObject *PyDictProxy_New(PyObject *mapping)
  返回值：新的引用。 属于 稳定 ABI.

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

PyTypeObject PyDictProxy_Type
  属于 稳定 ABI.

  对应于由 `PyDictProxy_New()` 创建的映射代理对象和许多内置类型的只读 `__dict__` 属性的类型对象。`PyDictProxy_Type` 实例提供下层字典的动态、只读视图：对下层字典的修改将反映在代理中，但代理本身不支持修改操作。这对应于 Python 中的 `types.MappingProxyType`。

void PyDict_Clear(PyObject *p)
  属于 稳定 ABI. Thread safety: Atomic.

  清空现有字典的所有键值对。

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`。

  备注

  The operation is atomic on free threading when key is `str`, `int`, `float`, `bool` or `bytes`.

int PyDict_ContainsString(PyObject *p, const char *key)
  Thread safety: Atomic.

  这与 `PyDict_Contains()` 相同，但 key 被指定为一个 const char* UTF-8 编码的字节串，而不是 PyObject*。

  Added in version 3.13.

PyObject *PyDict_Copy(PyObject *p)
  返回值：新的引用。 属于 稳定 ABI. Thread safety: Atomic.

  返回与 p 包含相同键值对的新字典。

int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)
  属于 稳定 ABI. Thread safety: Safe for concurrent use on the same object.

  使用 key 作为键将 val 插入字典 p。key 必须为 hashable；如果不是，则将引发 `TypeError`。成功时返回 `0`，失败时返回 `-1`。此函数 不会 窃取对 val 的引用。

  备注

  The operation is atomic on free threading when key is `str`, `int`, `float`, `bool` or `bytes`.

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`。

  备注

  The operation is atomic on free threading when key is `str`, `int`, `float`, `bool` or `bytes`.

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`。

  - On error, raise an exception, set *result to `NULL` and return `-1`.

  备注

  The operation is atomic on free threading when key is `str`, `int`, `float`, `bool` or `bytes`.

  Added in version 3.13.

  另请参阅 `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` 且 不会 设置异常。

  备注

  在调用 `__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，但现在已经不再允许了。

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.

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.

int PyDict_GetItemStringRef(PyObject *p, const char *key, PyObject **result)
  属于 稳定 ABI 自 3.13 版起. Thread safety: Atomic.

  类似于 `PyDict_GetItemRef()`，但 key 被指定为一个 const char* UTF-8 编码的字节串，而不是 PyObject*。

  Added in version 3.13.

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 的哈希函数一次，而不是在查找和插入时分别计算它。

  Added in version 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)
  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`) 的强引用。两者可能指向同一个对象：在此情况下你将持有两个指向它的单独引用。

  备注

  The operation is atomic on free threading when key is `str`, `int`, `float`, `bool` or `bytes`.

  Added in version 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`。

  备注

  The operation is atomic on free threading when key is `str`, `int`, `float`, `bool` or `bytes`.

  Added in version 3.13.

int PyDict_PopString(PyObject *p, const char *key, PyObject **result)
  Thread safety: Atomic.

  类似于 `PyDict_Pop()`，但 key 是以一个 const char* UTF-8 编码的字节串形式指定的，而不是 PyObject*。

  Added in version 3.13.

PyObject *PyDict_Items(PyObject *p)
  返回值：新的引用。 属于 稳定 ABI. Thread safety: Atomic.

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

PyObject *PyDict_Keys(PyObject *p)
  返回值：新的引用。 属于 稳定 ABI. Thread safety: Atomic.

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

PyObject *PyDict_Values(PyObject *p)
  返回值：新的引用。 属于 稳定 ABI. Thread safety: Atomic.

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

Py_ssize_t PyDict_Size(PyObject *p)
  属于 稳定 ABI. Thread safety: Atomic.

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

Py_ssize_t PyDict_GET_SIZE(PyObject *p)
  Thread safety: Atomic.

  类似于 `PyDict_Size()`，但是不带错误检查。

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 在迭代期间不应被更改。它的值表示内部字典结构中的偏移量，并且由于结构是稀疏的，因此偏移量并不连续。

  例如:

      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. You can use `Py_BEGIN_CRITICAL_SECTION` to 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();

  备注

  在自由线程构建版中，此函数可在关键节内部安全地使用。不过，针对 pkey 和 pvalue 返回的引用是 借入引用 并且仅在关键节被持有时有效。如果你需要在关键节之外或是在关键节可被挂起时使用这些对象，则要创建 强引用 (例如，使用 `Py_NewRef()`)。

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.

  这与 C 中的 `PyDict_Merge(a, b, 1)` 一样，也类似于 Python 中的 `a.update(b)`，差别在于 `PyDict_Update()` 在第二个参数没有 "keys" 属性时不会回退到迭代键值对的序列。当成功时返回 `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_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.

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()` or `PyDict_ClearWatcher()` are in progress.

  Added in version 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()` or `PyDict_ClearWatcher()` are in progress.

  Added in version 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`。

  Added in version 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`。

  Added in version 3.12.

type PyDict_WatchEvent

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

  Added in version 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 除非它先保存并清空异常状态，并在返回之前恢复它。

  Added in version 3.12.

## Dictionary View Objects

int PyDictViewSet_Check(PyObject *op)

  如果 op 是一个字典内集合的视图则返回真值。此函数目前等价于 PyDictKeys_Check(op) || PyDictItems_Check(op)。此函数总是会成功执行。

PyTypeObject PyDictKeys_Type
  属于 稳定 ABI.

  由字典键组成的视图的类型对象。在 Python 中，这就是由 `dict.keys()` 返回的对象的类型。

int PyDictKeys_Check(PyObject *op)

  如果 op 是一个字典键视图的实例则返回真值。此函数总是会成功执行。

PyTypeObject PyDictValues_Type
  属于 稳定 ABI.

  由字典值组成的视图的类型对象。在 Python 中，这就是由 `dict.values()` 返回的对象的类型。

int PyDictValues_Check(PyObject *op)

  如果 op 是一个字典值视图的实例则返回真值。此函数总是会成功执行。

PyTypeObject PyDictItems_Type
  属于 稳定 ABI.

  由字典条目组成的视图的类型对象。在 Python 中，这就是由 `dict.items()` 返回的对象的类型。

int PyDictItems_Check(PyObject *op)

  如果 op 是一个字典条目视图的实例则返回真值。此函数总是会成功执行。

## Ordered Dictionaries

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 的别名：

`PyODict` | `PyDict`
--- | ---
PyODict_GetItem(od, key) | `PyDict_GetItem()`
PyODict_GetItemWithError(od, key) | `PyDict_GetItemWithError()`
PyODict_GetItemString(od, key) | `PyDict_GetItemString()`
PyODict_Contains(od, key) | `PyDict_Contains()`
PyODict_Size(od) | `PyDict_Size()`
PyODict_SIZE(od) | `PyDict_GET_SIZE()`