辞書オブジェクト (dictionary object)
************************************

type PyDictObject

   この "PyObject" のサブタイプは Python の辞書オブジェクトを表現しま
   す。

PyTypeObject PyDict_Type
    * Part of the Stable ABI.*

   この "PyTypeObject" のインスタンスは Python の辞書を表現します。こ
   のオブジェクトは、Python レイヤにおける "dict" と同じオブジェクトで
   す。

int PyDict_Check(PyObject *p)

   *p* が辞書オブジェクトか辞書型のサブタイプのインスタンスである場合
   に真を返します。この関数は常に成功します。

int PyDict_CheckExact(PyObject *p)

   *p* が辞書オブジェクトだが辞書型のサブタイプのインスタンスでない場
   合に真を返します。この関数は常に成功します。

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" オブジェクトを返します。通常、この関数は動
   的でないクラス型 (non-dynamic class type) のクラス辞書が変更されな
   いようにビューを作成するために使われます。

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

   現在辞書に入っている全てのキーと値のペアを除去して空にします。

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

   辞書 *p* に *key* が入っているか判定します。*p* の要素が *key* に一
   致した場合は "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.*

   辞書 *p* に、 *key* をキーとして値 *val* を挿入します。 *key* はハ
   ッシュ可能(*hashable*)でなければなりません。ハッシュ可能でない場合
   、 "TypeError" を送出します。 成功した場合には "0" を、失敗した場合
   には "-1" を返します。 この関数は *val* への参照を盗み取り *ません*
   。

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

   辞書 *p* に、 *key* をキーとして値 *val* を挿入します。 *key* は
   "const char*" 型でなければなりません。 キーオブジェクトは
   "PyUnicode_FromString(key)" で生成されます。 成功した場合には "0"
   を、失敗した場合には "-1" を返します。 この関数は *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 で変更: Calling this API without *GIL* held had
   been allowed for historical reason. It is no longer allowed.

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

   "PyDict_GetItem()" と同じですが、 *key* は "PyObject*" ではなく
   "const char*" で指定します。

   "__hash__()" メソッドや "__eq__()" メソッドの呼び出し中や、一時的な
   文字列オブジェクトの作成中に起こる例外は抑制されることに注意してく
   ださい。 エラーを報告させるには、代わりに
   "PyDict_GetItemWithError()" を使ってください。

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

   これは Python レベルの "dict.setdefault()" と同じです。 もしあれば
   、辞書 *p* から *key* に対応する値を返します。 キーが辞書になければ
   、値 *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.*

   辞書内の全てのキーが入った "PyListObject" を返します。

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

   辞書 *p* 内の全ての値が入った "PyListObject" を返します。

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

   辞書内の要素の数を返します。辞書に対して "len(p)" を実行するのと同
   じです。

int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)
    * Part of the Stable 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)) {
          /* 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* が真ならば、 *a* のキーと一致するキーが *b* にあ
   る際に、既存のペアを置き換えます。それ以外の場合は、 *b* のキーに一
   致するキーが *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 の反復可能オブジ
   ェクト(iterable object) を生成する反復可能オブジェクトでなければな
   りません。重複するキーが存在する場合、*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
