字典物件
********

type PyDictObject

   "PyObject" 子型態代表一個 Python 字典物件。

PyTypeObject PyDict_Type
    * Part of the Stable ABI.*

   "PyTypeObject" 實例代表一個 Python 字典型態。此與 Python 層中的
   "dict" 為同一個物件。

int PyDict_Check(PyObject *p)

   若 *p* 是一個字典物件或字典的子型態實例則會回傳 true。此函式每次都
   會執行成功。

int PyDict_CheckExact(PyObject *p)

   若 *p* 是一個字典物件但並不是一個字典子型態的實例，則回傳 true。此
   函式每次都會執行成功。

PyObject *PyDict_New()
    *Return value: New reference.** Part of the Stable ABI.*

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

PyObject *PyDictProxy_New(PyObject *mapping)
    *Return value: New reference.** Part of the Stable ABI.*

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

void PyDict_Clear(PyObject *p)
    * Part of the Stable ABI.*

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

int PyDict_Contains(PyObject *p, PyObject *key)
    * Part of the Stable ABI.*

   确定 *key* 是否包含在字典 *p* 中。如果 *key* 匹配上 *p* 的某一项，
   则返回 "1" ，否则返回 "0" 。返回 "-1" 表示出错。这等同于Python表达
   式 "key in p" 。

PyObject *PyDict_Copy(PyObject *p)
    *Return value: New reference.** Part of the Stable ABI.*

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

int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)
    * Part of the Stable ABI.*

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

int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)
    * Part of the Stable ABI.*

   Insert *val* into the dictionary *p* using *key* as a key. *key*
   should be a "const char*".  The key object is created using
   "PyUnicode_FromString(key)".  Return "0" on success or "-1" on
   failure.  This function *does not* steal a reference to *val*.

int PyDict_DelItem(PyObject *p, PyObject *key)
    * Part of the Stable ABI.*

   Remove the entry in dictionary *p* with key *key*. *key* must be
   *hashable*; if it isn't, "TypeError" is raised. If *key* is not in
   the dictionary, "KeyError" is raised. Return "0" on success or "-1"
   on failure.

int PyDict_DelItemString(PyObject *p, const char *key)
    * Part of the Stable ABI.*

   移除字典 *p* 中由字符串 *key* 指定的键的条目。 如果字典中没有 *key*
   ，则会引发 "KeyError"。 成功时返回 "0"，失败时返回 "-1"。

PyObject *PyDict_GetItem(PyObject *p, PyObject *key)
    *Return value: Borrowed reference.** Part of the Stable ABI.*

   从字典 *p* 中返回以 *key* 为键的对象。 如果键名 *key* 不存在但 *没
   有* 设置一个异常则返回 "NULL"。

   需要注意的是，调用 "__hash__()" 和 "__eq__()" 方法产生的异常不会被
   抛出。改用 "PyDict_GetItemWithError()" 获得错误报告。

   3.10 版更變: 在不保持 *GIL* 的情况下调用此 API 曾因历史原因而被允许
   。 现在已不再被允许。

PyObject *PyDict_GetItemWithError(PyObject *p, PyObject *key)
    *Return value: Borrowed reference.** Part of the Stable ABI.*

   "PyDict_GetItem()" 的变种，它不会屏蔽异常。 当异常发生时将返回
   "NULL" **并且** 设置一个异常。 如果键不存在则返回 "NULL" **并且不会
   ** 设置一个异常。

PyObject *PyDict_GetItemString(PyObject *p, const char *key)
    *Return value: Borrowed reference.** Part of the Stable ABI.*

   This is the same as "PyDict_GetItem()", but *key* is specified as a
   "const char*", rather than a "PyObject*".

   需要注意的是，调用 "__hash__()" 、 "__eq__()" 方法和创建一个临时的
   字符串对象时产生的异常不会被抛出。改用 "PyDict_GetItemWithError()"
   获得错误报告。

PyObject *PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *defaultobj)
    *Return value: Borrowed reference.*

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

   3.4 版新加入.

PyObject *PyDict_Items(PyObject *p)
    *Return value: New reference.** Part of the Stable ABI.*

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

PyObject *PyDict_Keys(PyObject *p)
    *Return value: New reference.** Part of the Stable ABI.*

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

PyObject *PyDict_Values(PyObject *p)
    *Return value: New reference.** Part of the Stable ABI.*

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

Py_ssize_t PyDict_Size(PyObject *p)
    * Part of the Stable ABI.*

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

int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)
    * Part of the Stable ABI.*

   Iterate over all key-value pairs in the dictionary *p*.  The
   "Py_ssize_t" referred to by *ppos* must be initialized to "0" prior
   to the first call to this function to start the iteration; the
   function returns true for each pair in the dictionary, and false
   once all pairs have been reported.  The parameters *pkey* and
   *pvalue* should either point to "PyObject*" variables that will be
   filled in with each key and value, respectively, or may be "NULL".
   Any references returned through them are borrowed.  *ppos* should
   not be altered during iteration. Its value represents offsets
   within the internal dictionary structure, and since the structure
   is sparse, the offsets are not consecutive.

   舉例來說：

      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);
      }

int PyDict_Merge(PyObject *a, PyObject *b, int override)
    * Part of the Stable ABI.*

   对映射对象 *b* 进行迭代，将键值对添加到字典 *a*。 *b* 可以是一个字
   典，或任何支持 "PyMapping_Keys()" 和 "PyObject_GetItem()" 的对象。
   如果 *override* 为真值，则如果在 *b* 中找到相同的键则 *a* 中已存在
   的相应键值对将被替换，否则如果在 *a* 中没有相同的键则只是添加键值对
   。 当成功时返回 "0" 或者当引发异常时返回 "-1"。

int PyDict_Update(PyObject *a, PyObject *b)
    * Part of the Stable 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)
    * Part of the Stable 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
