辞書オブジェクト (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

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

前のトピックへ

次のトピックへ

このページ