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

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

PyTypeObject PyDict_Type
この PyTypeObject のインスタンスは Python の辞書を表現します。 このオブジェクトは、Python プログラムには dict および types.DictType として公開されています。

int PyDict_Check(PyObject *p)
引数が PyDictObject のときに真を返します。

int PyDict_CheckExact(PyObject *p)
p が辞書型オブジェクトであり、かつ辞書型のサブクラスのインスタンス でない場合に真を返します。 バージョン 2.4 で 新たに追加 された仕様です。

PyObject* PyDict_New()
戻り値: 新たな参照.
p が辞書型オブジェクトで、かつ辞書型のサブタイプのインスタンス でない場合に真を返します。

PyObject* PyDictProxy_New(PyObject *dict)
戻り値: 新たな参照.
あるマップ型オブジェクトに対して、読み出し専用に制限されたプロキシ オブジェクト (proxy object) を返します。通常、この関数は 動的でないクラス型 (non-dynamic class type) のクラス辞書を 変更させないためにプロキシを作成するために使われます。 バージョン 2.2 で 新たに追加 された仕様です。

void PyDict_Clear(PyObject *p)
現在辞書に入っている全てのキーと値のペアを除去して空にします。

int PyDict_Contains(PyObject *p, PyObject *key)
辞書 pkey が入っているか判定します。 p の要素が key に一致した場合は 1 を返し、 それ以外の場合には 0 を返します。エラーの場合 -1 を返します。この関数は Python の式"key in p"と等価です。 バージョン 2.4 で 新たに追加 された仕様です。

PyObject* PyDict_Copy(PyObject *p)
戻り値: 新たな参照.
p と同じキーと値のペアが入った新たな辞書を返します。 バージョン 1.6 で 新たに追加 された仕様です。

int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)
辞書 p に、 key をキーとして値 value を 挿入します。 key はハッシュ可能でなければなりません; ハッシュ可能でない場合、 TypeError を送出します。 成功した場合には 0 を、失敗した場合には -1 を返します。

int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)
辞書 p に、 key をキーとして値 value を 挿入します。 keychar* 型でなければなりません。 キーオブジェクトはPyString_FromString(key) で生成 されます。 成功した場合には 0 を、失敗した場合には -1 を返します。

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

int PyDict_DelItemString(PyObject *p, char *key)
辞書 p から文字列 key をキーとするエントリを除去します。 成功した場合には 0 を、失敗した場合には -1 を返します。

PyObject* PyDict_GetItem(PyObject *p, PyObject *key)
戻り値: 借りた参照.
辞書p 内で key をキーとするオブジェクトを返します。 キー key が存在しない場合には NULL を返しますが、例外を セット しません

PyObject* PyDict_GetItemString(PyObject *p, const char *key)
戻り値: 借りた参照.
PyDict_GetItem() と同じですが、keyPyObject* ではなく char* で指定します。

PyObject* PyDict_Items(PyObject *p)
戻り値: 新たな参照.
辞書オブジェクトのメソッド item() のように、 辞書内の全ての要素対が入った PyListObject を返します。 (items() については Python ライブラリリファレンス を 参照してください。)

PyObject* PyDict_Keys(PyObject *p)
戻り値: 新たな参照.
辞書オブジェクトのメソッド keys() のように、 辞書内の全てのキーが入った PyListObject を返します。 (keys() については Python ライブラリリファレンス を 参照してください。)

PyObject* PyDict_Values(PyObject *p)
戻り値: 新たな参照.
辞書オブジェクトのメソッド values() のように、 辞書内の全ての値が入った PyListObject を返します。 (values() については Python ライブラリリファレンス を 参照してください。)

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

int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)
辞書 p 内の全てのキー/値のペアにわたる反復処理を行います。 ppos が参照している int 型は、この関数で反復処理 を開始する際に、最初に関数を呼び出すよりも前に 0 に 初期化しておかなければなりません; この関数は辞書内の各ペアを 取り上げるごとに真を返し、全てのペアを取り上げたことが分かると 偽を返します。パラメタ pkey および pvalue には、 それぞれ辞書の各々のキーと値を指すポインタか、または NULL が入ります。この関数から返される参照はすべて借りた参照になります。 反復処理中に ppos を変更してはなりません。この値は 内部的な辞書構造体のオフセットを表現しており、構造体はスパース なので、オフセットの値に一貫性がないためです。

以下に例を示します:

PyObject *key, *value;
int pos = 0;

while (PyDict_Next(self->dict, &pos, &key, &value)) {
    /* 取り出した値で何らかの処理を行う... */
    ...
}

反復処理中に辞書 p を変更してはなりません。 (Python 2.1 からは) 辞書を反復処理する際に、キーに対応する値を 変更しても大丈夫になりましたが、キーの集合を変更しないことが 前提です。以下に例を示します:

PyObject *key, *value;
int pos = 0;

while (PyDict_Next(self->dict, &pos, &key, &value)) {
    int i = PyInt_AS_LONG(value) + 1;
    PyObject *o = PyInt_FromLong(i);
    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)
マップ型オブジェクト b の全ての要素にわたって、反復的に キー/値のペアを辞書 a に追加します。 b は辞書か、PyMapping_Keys() または PyObject_GetItem() をサポートする何らかのオブジェクト にできます。 override が真ならば、a のキーと一致するキーが b にある際に、既存のペアを置き換えます。それ以外の場合は、b のキーに一致するキーが a にないときのみ追加を行います。 成功した場合には 0 を返し、例外が送出された場合には -1 を返します。 バージョン 2.2 で 新たに追加 された仕様です。

int PyDict_Update(PyObject *a, PyObject *b)
C で表せば PyDict_Merge(a, b, 1) と同じ、 Python で表せばa.update(b) と同じです。 成功した場合には 0 を返し、例外が送出された場合には -1 を返します。 バージョン 2.2 で 新たに追加 された仕様です。

int PyDict_MergeFromSeq2(PyObject *a, PyObject *seq2, int override)
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

バージョン 2.2 で 新たに追加 された仕様です。

ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。