字典对象
********

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" 对象，用于强制执行只读行为的映射。这
   通常用于创建视图以防止修改非动态类类型的字典。

PyTypeObject PyDictProxy_Type
    * 属于 稳定 ABI.*

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

   Added in version 3.13.

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

int PyDict_GetItemRef(PyObject *p, PyObject *key, PyObject **result)
    * 属于 稳定 ABI 自 3.13 版起.*

   返回一个新的指向字典 *p* 中对应键 *key* 的对象的 *strong
   reference*:

   * 如果存在该键，则将 **result* 设为一个新的指向该值的 *strong
     reference* 并返回 "1"。

   * 如果不存在该键，则将 **result* 设为 "NULL" 并返回 "0"。

   * 发生错误时，将引发异常并返回 "-1"。

   Added in version 3.13.

   另请参阅 "PyObject_GetItem()" 函数。

PyObject *PyDict_GetItem(PyObject *p, PyObject *key)
    *返回值：借入的引用。** 属于 稳定 ABI.*

   返回一个指向字典 *p* 中对应键 *key* 的对象的 *borrowed reference*。
   如果不存在键 *key* 则返回 "NULL" 且 *不会* 设置异常。

   备注:

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

   在 3.10 版本发生变更: 出于历史原因，曾经允许在没有附加线程状态
   *attached thread state* 的情况下调用这个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)
    * 属于 稳定 ABI 自 3.13 版起.*

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

   Added in version 3.13.

PyObject *PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *defaultobj)
    *返回值：借入的引用。*

   这跟Python层面的 "dict.setdefault()" 一样。如果键 *key* 存在，它返
   回在字典 *p* 里面对应的值。如果键不存在，它会和值 *defaultobj* 一起
   插入并返回 *defaultobj* 。这个函数只计算 *key* 的哈希函数一次，而不
   是在查找和插入时分别计算它。

   Added in version 3.4.

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

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

   Added in version 3.13.

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

   将 *key* 从字典 *p* 中移除并可选择返回被移除的值。 当键不存在时不会
   引发 "KeyError"。

   * 如果键存在，则在 *result* 不为 "NULL" 时将 **result* 设为一个新的
     指向被移除值的引用，并返回 "1"。

   * 如果不存在该键，则在 *result* 不为 "NULL" 时将 **result* 设为
     "NULL"，并返回 "0"。

   * 发生错误时，将引发异常并返回 "-1"。

   类似于 "dict.pop()"，但没有默认值并且当键不存在时不会引发
   "KeyError"。

   Added in version 3.13.

int PyDict_PopString(PyObject *p, const char *key, PyObject **result)

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

   Added in version 3.13.

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)"。

Py_ssize_t PyDict_GET_SIZE(PyObject *p)

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

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)) {
          /* 用这些值做些有趣的事... */
          ...
      }

   字典 *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* 为真值，则如果在 *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" 并且设置异常。

   Added in version 3.12.

int PyDict_ClearWatcher(int watcher_id)

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

   Added in version 3.12.

int PyDict_Watch(int watcher_id, PyObject *dict)

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

   Added in version 3.12.

int PyDict_Unwatch(int watcher_id, PyObject *dict)

   将字典 *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.


字典视图对象
============

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* 是一个字典条目视图的实例则返回真值。 此函数总是会成功执行
   。


有序字典
========

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()"                                |
+----------------------------------------------------+----------------------------------------------------+
