辞書オブジェクト
****************

type PyDictObject

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

PyTypeObject PyDict_Type
    * 次に属します: Stable ABI.*

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

int PyDict_Check(PyObject *p)
    * Thread safety: Atomic.*

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

int PyDict_CheckExact(PyObject *p)
    * Thread safety: Atomic.*

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

PyObject *PyDict_New()
    *戻り値: 新しい参照。** 次に属します: Stable ABI.** Thread safety:
   Atomic.*

   空の新たな辞書を返します。 失敗すると "NULL" を返します。

PyObject *PyDictProxy_New(PyObject *mapping)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

   あるマップ型オブジェクトに対して、読み出し専用に制限された
   "types.MappingProxyType" オブジェクトを返します。通常、この関数は動
   的でないクラス型 (non-dynamic class type) のクラス辞書が変更されな
   いようにビューを作成するために使われます。

   最初の引数には "dict"、"frozendict"、またはマッピングを指定できます
   。

   バージョン 3.15 で変更: "frozendict" も受け付けるようになりました。

PyTypeObject PyDictProxy_Type
    * 次に属します: Stable ABI.*

   "PyDictProxy_New()" が作成するマッピングプロキシオブジェクトや、多
   くの組み込み型の読み出し専用の "__dict__" 属性に使われる型オブジェ
   クトです。 "PyDictProxy_Type" のインスタンスは、元の辞書の動的な読
   み出し専用ビューを提供します。 元の辞書の変更はプロキシに反映されま
   すが、プロキシ自体は変更操作をサポートしません。 Python の
   "types.MappingProxyType" に対応します。

void PyDict_Clear(PyObject *p)
    * 次に属します: Stable ABI.** Thread safety: Atomic.*

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

   引数が "dict" または "dict" のサブクラスでない場合は何もしません。

int PyDict_Contains(PyObject *p, PyObject *key)
    * 次に属します: Stable ABI.** Thread safety: Safe for concurrent
   use on the same object.*

   辞書 *p* に *key* が含まれるか判定します。 *p* 内に *key* と一致す
   る要素があれば "1"、なければ "0" を返します。 エラー時には "-1" を
   返します。 Python の式 "key in p" と等価です。

   最初の引数には "dict" または "frozendict" を指定できます。

   注釈:

     *key* が "str"、"int"、"float"、"bool"、"bytes" のいずれかである
     場合、*フリースレッドビルド* でこの操作はアトミックです。

   バージョン 3.15 で変更: "frozendict" も受け付けるようになりました。

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

   "PyDict_Contains()" と同様ですが、*key* は PyObject* ではなく、
   UTF-8 でエンコードされた const char* のバイト文字列で指定します。

   最初の引数には "dict" または "frozendict" を指定できます。

   Added in version 3.13.

   バージョン 3.15 で変更: "frozendict" も受け付けるようになりました。

PyObject *PyDict_Copy(PyObject *p)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.** Thread safety:
   Atomic.*

   *p* と同じキーと値のペアが入った新たな辞書を返します。

int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)
    * 次に属します: Stable ABI.** Thread safety: Safe for concurrent
   use on the same object.*

   辞書 *p* に、キー *key* で *val* を挿入します。 *key* は *ハッシュ
   可能* でなければならず、そうでない場合は "TypeError" を送出します。
   成功すると "0"、失敗すると "-1" を返します。 この関数は *val* への
   参照を「*盗みません*」。

   注釈:

     *key* が "str"、"int"、"float"、"bool"、"bytes" のいずれかである
     場合、*フリースレッドビルド* でこの操作はアトミックです。

int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)
    * 次に属します: Stable ABI.** Thread safety: Atomic.*

   "PyDict_SetItem()" と同様ですが、*key* は PyObject* ではなく、UTF-8
   でエンコードされた const char* のバイト文字列で指定します。

int PyDict_DelItem(PyObject *p, PyObject *key)
    * 次に属します: Stable ABI.** Thread safety: Safe for concurrent
   use on the same object.*

   辞書 *p* から *key* をキーとするエントリを除去します。 *key* は *ハ
   ッシュ可能* でなければなりません;  ハッシュ可能でない場合、
   "TypeError" を送出します。*key* が辞書になければ、"KeyError" を送出
   します。成功した場合には "0" を、失敗した場合には "-1" を返します。

   注釈:

     *key* が "str"、"int"、"float"、"bool"、"bytes" のいずれかである
     場合、*フリースレッドビルド* でこの操作はアトミックです。

int PyDict_DelItemString(PyObject *p, const char *key)
    * 次に属します: Stable ABI.** Thread safety: Atomic.*

   "PyDict_DelItem()" と同様ですが、*key* は PyObject* ではなく、UTF-8
   でエンコードされた const char* のバイト文字列で指定します。

int PyDict_GetItemRef(PyObject *p, PyObject *key, PyObject **result)
    * 次に属します: Stable ABI (バージョン 3.13 より).** Thread
   safety: Safe for concurrent use on the same object.*

   辞書 *p* からキー *key* に対応するオブジェクトへの新しい *強参照*
   を返します:

   * キーがあれば、**result* にその値への新しい *強参照* を設定し、"1"
     を返します。

   * キーがなければ、**result* に "NULL" を設定し、"0" を返します。

   * エラー時には例外を送出し、**result* に "NULL" を設定して "-1" を
     返します。

   最初の引数には "dict" または "frozendict" を指定できます。

   注釈:

     *key* が "str"、"int"、"float"、"bool"、"bytes" のいずれかである
     場合、*フリースレッドビルド* でこの操作はアトミックです。

   Added in version 3.13.

   バージョン 3.15 で変更: "frozendict" も受け付けるようになりました。

   "PyObject_GetItem()" 関数も参照してください。

PyObject *PyDict_GetItem(PyObject *p, PyObject *key)
    *戻り値: 借用参照。** 次に属します: Stable ABI.** Thread safety:
   Safe to call from multiple threads with external synchronization
   only.*

   辞書 *p* からキー *key* に対応するオブジェクトへの *借用参照* を返
   します。 キー *key* がなければ、例外を設定 *せずに* "NULL" を返しま
   す。

   最初の引数には "dict" または "frozendict" を指定できます。

   注釈:

     この関数が "__hash__()" メソッドや "__eq__()" メソッドを呼び出す
     際に発生した例外は、通知せずに無視します。 代わりに
     "PyDict_GetItemWithError()" 関数を使うことを推奨します。

   注釈:

     *フリースレッドビルド* では、別のスレッドが同時に辞書を変更すると
     、返された *借用参照* が無効になる可能性があります。 *強参照* を
     返す "PyDict_GetItemRef()" を使うことを推奨します。

   バージョン 3.10 で変更: 歴史的な理由により、以前は *アタッチされた
   スレッド状態* なしでこの API を呼び出すことが認められていました。
   現在は認められていません。

   バージョン 3.15 で変更: "frozendict" も受け付けるようになりました。

PyObject *PyDict_GetItemWithError(PyObject *p, PyObject *key)
    *戻り値: 借用参照。** 次に属します: Stable ABI.** Thread safety:
   Safe to call from multiple threads with external synchronization
   only.*

   "PyDict_GetItem()" の変種で例外を隠しません。 例外が発生した場合は
   、例外をセット **した上で** "NULL" を返します。 キーが存在しなかっ
   た場合は、例外をセット **せずに** "NULL" を返します。

   注釈:

     *フリースレッドビルド* では、別のスレッドが同時に辞書を変更すると
     、返された *借用参照* が無効になる可能性があります。 *強参照* を
     返す "PyDict_GetItemRef()" を使うことを推奨します。

   バージョン 3.15 で変更: "frozendict" も受け付けるようになりました。

PyObject *PyDict_GetItemString(PyObject *p, const char *key)
    *戻り値: 借用参照。** 次に属します: Stable ABI.** Thread safety:
   Safe to call from multiple threads with external synchronization
   only.*

   "PyDict_GetItem()" と同様ですが、*key* は PyObject* ではなく、UTF-8
   でエンコードされた const char* のバイト文字列で指定します。

   注釈:

     この関数が "__hash__()" メソッドや "__eq__()" メソッドを呼び出す
     際、または一時的な "str" オブジェクトを作成する際に発生した例外は
     、通知せずに無視します。 代わりに、自分で
     "PyUnicode_FromString()" により *key* を作成し、
     "PyDict_GetItemWithError()" 関数を使うことを推奨します。

   注釈:

     *フリースレッドビルド* では、別のスレッドが同時に辞書を変更すると
     、返された *借用参照* が無効になる可能性があります。 *強参照* を
     返す "PyDict_GetItemStringRef()" を使うことを推奨します。

   バージョン 3.15 で変更: "frozendict" も受け付けるようになりました。

int PyDict_GetItemStringRef(PyObject *p, const char *key, PyObject **result)
    * 次に属します: Stable ABI (バージョン 3.13 より).** Thread
   safety: Atomic.*

   "PyDict_GetItemRef()" と同様ですが、*key* は PyObject* ではなく、
   UTF-8 でエンコードされた const char* のバイト文字列で指定します。

   Added in version 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()" と同じです。 もしあれば
   、辞書 *p* から *key* に対応する値を返します。 キーが辞書になければ
   、値 *defaultobj* を挿入し *defaultobj* を返します。 この関数は、
   *key* のハッシュ値を検索と挿入ごとに別々に評価するのではなく、一度
   だけしか評価しません。

   Added in version 3.4.

   注釈:

     *フリースレッドビルド* では、別のスレッドが同時に辞書を変更すると
     、返された *借用参照* が無効になる可能性があります。 *強参照* を
     返す "PyDict_SetDefaultRef()" を使うことを推奨します。

int PyDict_SetDefaultRef(PyObject *p, PyObject *key, PyObject *default_value, PyObject **result)
    * 次に属します: Stable ABI (バージョン 3.15 より).** Thread
   safety: Safe for concurrent use on the same object.*

   辞書 *p* にキー *key* がまだなければ、そのキーで *default_value* を
   挿入します。 *result* が "NULL" でなければ、**result* には *強参照*
   を設定します。 キーがなかった場合は *default_value* への参照、*key*
   がすでにあった場合は既存の値への参照です。 キーがすでにあり
   *default_value* を挿入しなかった場合は "1"、キーがなく
   *default_value* を挿入した場合は "0" を返します。 失敗すると "-1"
   を返し、例外を設定し、"*result" に "NULL" を設定します。

   明確にすると、この関数を呼び出す前に *default_value* への強参照を持
   っていた場合、戻った後には *default_value* と **result* ("NULL" で
   ない場合) の両方への強参照を持つことになります。 これらが同じオブジ
   ェクトを参照している場合もあり、その場合はそのオブジェクトへの別々
   の参照を 2 つ持つことになります。

   注釈:

     *key* が "str"、"int"、"float"、"bool"、"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.*

   辞書 *p* から *key* を削除し、必要に応じて削除した値を返します。 キ
   ーがなくても "KeyError" を送出しません。

   * キーがあれば、*result* が "NULL" でない場合には **result* に削除
     した値への新しい参照を設定し、"1" を返します。

   * キーがなければ、*result* が "NULL" でない場合には **result* に
     "NULL" を設定し、"0" を返します。

   * エラーの場合例外を送出し "-1" を返します。

   "dict.pop()" と同様ですが、デフォルト値はなく、キーがない場合も
   "KeyError" を送出しません。

   注釈:

     *key* が "str"、"int"、"float"、"bool"、"bytes" のいずれかである
     場合、*フリースレッドビルド* でこの操作はアトミックです。

   Added in version 3.13.

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

   "PyDict_Pop()" と同様ですが、*key* は PyObject* ではなく、UTF-8 で
   エンコードされた const char* のバイト文字列で指定します。

   Added in version 3.13.

PyObject *PyDict_Items(PyObject *p)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.** Thread safety:
   Atomic.*

   辞書内の全ての要素対が入った "PyListObject" を返します。

   最初の引数には "dict" または "frozendict" を指定できます。

   バージョン 3.15 で変更: "frozendict" も受け付けるようになりました。

PyObject *PyDict_Keys(PyObject *p)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.** Thread safety:
   Atomic.*

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

   最初の引数には "dict" または "frozendict" を指定できます。

   バージョン 3.15 で変更: "frozendict" も受け付けるようになりました。

PyObject *PyDict_Values(PyObject *p)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.** Thread safety:
   Atomic.*

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

   最初の引数には "dict" または "frozendict" を指定できます。

   バージョン 3.15 で変更: "frozendict" も受け付けるようになりました。

Py_ssize_t PyDict_Size(PyObject *p)
    * 次に属します: Stable ABI.** Thread safety: Atomic.*

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

   引数には "dict" または "frozendict" を指定できます。

   バージョン 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)
    * 次に属します: Stable 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);
      }

   *フリースレッド* ビルドでは、外部で同期を行わない限り、ミュータブル
   な "dict" に対してこの関数はスレッドセーフではありません。
   "Py_BEGIN_CRITICAL_SECTION" を使って、反復処理中に辞書をロックでき
   ます。

      Py_BEGIN_CRITICAL_SECTION(self->dict);
      while (PyDict_Next(self->dict, &pos, &key, &value)) {
          ...
      }
      Py_END_CRITICAL_SECTION();

   "frozendict" に対してこの関数はスレッドセーフです。

   注釈:

     フリースレッドビルドでは、この関数はクリティカルセクション内で安
     全に使えます。 ただし、*pkey* と *pvalue* に返される参照は *借用
     参照* であり、クリティカルセクションを保持している間だけ有効です
     。 クリティカルセクションの外で、またはクリティカルセクションが中
     断される可能性がある状況でこれらのオブジェクトを使う必要がある場
     合は、*強参照* を作成してください (例えば "Py_NewRef()" を使いま
     す)。

   バージョン 3.15 で変更: "frozendict" も受け付けるようになりました。

int PyDict_Merge(PyObject *a, PyObject *b, int override)
    * 次に属します: Stable ABI.** Thread safety: Safe for concurrent
   use on the same object.*

   マッピングオブジェクト *b* を反復処理し、キーと値のペアを辞書 *a*
   に追加します。 *b* は辞書、または "PyMapping_Keys()" と
   "PyObject_GetItem()" の両方をサポートするオブジェクトであれば構いま
   せん。 *override* が真の場合、*b* に一致するキーがあれば *a* の既存
   のペアを置き換えます。 偽の場合は、*a* に一致するキーがないペアだけ
   を追加します。 成功すると "0"、例外が送出された場合は "-1" を返しま
   す。

   注釈:

     *フリースレッドビルド* では、*b* が (標準のイテレータを使う)
     "dict" の場合、操作中は *a* と *b* の両方をロックします。 *b* が
     dict 以外のマッピングの場合は *a* だけをロックし、*b* は別のスレ
     ッドによって同時に変更される可能性があります。

int PyDict_Update(PyObject *a, PyObject *b)
    * 次に属します: Stable 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" を返します。

   注釈:

     *フリースレッドビルド* では、*b* が (標準のイテレータを使う)
     "dict" の場合、操作中は *a* と *b* の両方をロックします。 *b* が
     dict 以外のマッピングの場合は *a* だけをロックし、*b* は別のスレ
     ッドによって同時に変更される可能性があります。

int PyDict_MergeFromSeq2(PyObject *a, PyObject *seq2, int override)
    * 次に属します: Stable 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

   注釈:

     *フリースレッド* ビルドでは、*a* だけをロックします。 *seq2* の反
     復処理は同期されないため、別のスレッドが同時に *seq2* を変更する
     可能性があります。

int PyDict_AddWatcher(PyDict_WatchCallback callback)
    * Thread safety: Safe to call from multiple threads with external
   synchronization only.*

   *callback* を辞書ウォッチャーとして登録します。 非負の整数の ID を
   返します。この ID は以降の "PyDict_Watch()" 呼び出しに渡す必要があ
   ります。 エラー時 (例えばウォッチャー ID に空きがない場合) には
   "-1" を返し、例外を設定します。

   注釈:

     この関数は内部で同期を行いません。 *フリースレッド* ビルドでは、
     呼び出し側が "PyDict_AddWatcher()" や "PyDict_ClearWatcher()" の
     呼び出しが同時に行われないことを保証する必要があります。

   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* で識別されるウォ
   ッチャーを解除します。 成功すると "0"、エラー時 (例えば指定した
   *watcher_id* が登録されていない場合) には "-1" を返します。

   注釈:

     この関数は内部で同期を行いません。 *フリースレッド* ビルドでは、
     呼び出し側が "PyDict_AddWatcher()" や "PyDict_ClearWatcher()" の
     呼び出しが同時に行われないことを保証する必要があります。

   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* を監視対象にします。 *dict* が変更または解放されると、
   "PyDict_AddWatcher()" で *watcher_id* を割り当てられたコールバック
   を呼び出します。 成功すると "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* を監視対象から外します。 *dict* が変更または解放されて
   も、"PyDict_AddWatcher()" で *watcher_id* を割り当てられたコールバ
   ックは呼び出されなくなります。 この辞書は、それまでこのウォッチャー
   に監視されている必要があります。 成功すると "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.

PY_FOREACH_DICT_EVENT(V)

   "PyDict_WatchEvent" の各定数の接尾部にマクロ *V* を適用します。 現
   在は "V(ADDED) V(MODIFIED) V(DELETED) V(CLONED) V(CLEARED)
   V(DEALLOCATED)" に展開されます。 マクロ *V* はイベント名を 1 つ受け
   取り、展開結果の間に必要な区切り記号を補う必要があります。

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" が 1 回発生し、*key* はマージ元の辞書になりま
   す。

   コールバックは *dict* の内容を調べることはできますが、変更してはい
   けません。 変更すると、無限再帰などの予測できない影響が生じる可能性
   があります。 副作用で辞書を変更する可能性があるため、コールバック内
   で Python コードを実行しないでください。

   *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
    * 次に属します: Stable ABI.*

   辞書のキーのビューの型オブジェクトです。 Python では "dict.keys()"
   が返すオブジェクトの型です。

int PyDictKeys_Check(PyObject *op)

   *op* が辞書のキーのビューのインスタンスであれば真を返します。 この
   関数は常に成功します。

PyTypeObject PyDictValues_Type
    * 次に属します: Stable ABI.*

   辞書の値のビューの型オブジェクトです。 Python では "dict.values()"
   が返すオブジェクトの型です。

int PyDictValues_Check(PyObject *op)

   *op* が辞書の値のビューのインスタンスであれば真を返します。 この関
   数は常に成功します。

PyTypeObject PyDictItems_Type
    * 次に属します: Stable ABI.*

   辞書の要素対のビューの型オブジェクトです。 Python では
   "dict.items()" が返すオブジェクトの型です。

int PyDictItems_Check(PyObject *op)

   *op* が辞書の要素対のビューのインスタンスであれば真を返します。 こ
   の関数は常に成功します。


凍結された辞書オブジェクト
==========================

Added in version 3.15.

PyTypeObject PyFrozenDict_Type

   この "PyTypeObject" のインスタンスは Python の凍結された辞書の型を
   表します。 Python レイヤの "frozendict" と同じオブジェクトです。

int PyAnyDict_Check(PyObject *p)

   *p* が "dict" オブジェクト、"frozendict" オブジェクト、または
   "dict" 型か "frozendict" 型のサブタイプのインスタンスであれば真を返
   します。 この関数は常に成功します。

int PyAnyDict_CheckExact(PyObject *p)

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

int PyFrozenDict_Check(PyObject *p)

   *p* が "frozendict" オブジェクトまたは "frozendict" 型のサブタイプ
   のインスタンスであれば真を返します。 この関数は常に成功します。

int PyFrozenDict_CheckExact(PyObject *p)

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

PyObject *PyFrozenDict_New(PyObject *iterable)

   イテラブルから新しい "frozendict" を作成して返します。 失敗すると例
   外を設定して "NULL" を返します。

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

   順序付き辞書 *od* に、キー *key* で *value* を挿入します。 成功する
   と "0"、失敗すると例外を設定して "-1" を返します。

   "PyDict_SetItem()" に相当します。

int PyODict_DelItem(PyObject *od, PyObject *key)

   順序付き辞書 *od* から、キー *key* のエントリーを削除します。 成功
   すると "0"、失敗すると例外を設定して "-1" を返します。

   "PyDict_DelItem()" に相当します。

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