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

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

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

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

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

PyObject *PyDict_New()¶: 戻り値: 新しい参照。 次に属します: Stable ABI.
空の新たな辞書を返します。失敗すると NULL を返します。

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

PyTypeObject PyDictProxy_Type¶: 次に属します: Stable ABI.
The type object for mapping proxy objects created by PyDictProxy_New() and for the read-only __dict__ attribute of many built-in types. A PyDictProxy_Type instance provides a dynamic, read-only view of an underlying dictionary: changes to the underlying dictionary are reflected in the proxy, but the proxy itself does not support mutation operations. This corresponds to types.MappingProxyType in Python.

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

int PyDict_Contains(PyObject *p, PyObject *key)¶: 次に属します: Stable ABI.
Determine if dictionary p contains key. If an item in p matches key, return 1, otherwise return 0. On error, return -1. This is equivalent to the Python expression key in p.

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

Added in version 3.13.

PyObject *PyDict_Copy(PyObject *p)¶: 戻り値: 新しい参照。 次に属します: Stable ABI.
p と同じキーと値のペアが入った新たな辞書を返します。

int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)¶: 次に属します: Stable ABI.
Insert val into the dictionary p with a key of key. key must be hashable; if it isn't, TypeError will be raised. Return 0 on success or -1 on failure. This function does not "steal" a reference to val.

int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)¶: 次に属します: Stable ABI.
PyDict_SetItem() と同様ですが、key は PyObject* ではなく、UTF-8 でエンコードされた const char* のバイト文字列で指定します。

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

int PyDict_DelItemString(PyObject *p, const char *key)¶: 次に属します: Stable ABI.
PyDict_DelItem() と同様ですが、key は PyObject* ではなく、UTF-8 でエンコードされた const char* のバイト文字列で指定します。

int PyDict_GetItemRef(PyObject *p, PyObject *key, PyObject **result)¶

次に属します: Stable ABI (バージョン 3.13 より).

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

キーがあれば、*result にその値への新しい強参照を設定し、1 を返します。
キーがなければ、*result に NULL を設定し、0 を返します。
On error, raise an exception, set *result to NULL and return -1.

Added in version 3.13.

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

PyObject *PyDict_GetItem(PyObject *p, PyObject *key)¶: 戻り値: 借用参照。 次に属します: 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)¶: 戻り値: 借用参照。 次に属します: Stable ABI.
PyDict_GetItem() の変種で例外を隠しません。例外が発生した場合は、例外をセット した上で NULL を返します。キーが存在しなかった場合は、例外をセット せずに NULL を返します。

PyObject *PyDict_GetItemString(PyObject *p, const char *key)¶: 戻り値: 借用参照。 次に属します: Stable ABI.
PyDict_GetItem() と同様ですが、key は PyObject* ではなく、UTF-8 でエンコードされた const char* のバイト文字列で指定します。

注釈

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

int PyDict_GetItemStringRef(PyObject *p, const char *key, PyObject **result)¶: 次に属します: Stable ABI (バージョン 3.13 より).
PyDict_GetItemRef() と同様ですが、key は PyObject* ではなく、UTF-8 でエンコードされた const char* のバイト文字列で指定します。

Added in version 3.13.

PyObject *PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *defaultobj)¶: 戻り値: 借用参照。
これは Python レベルの dict.setdefault() と同じです。もしあれば、辞書 p から key に対応する値を返します。キーが辞書になければ、値 defaultobj を挿入し defaultobj を返します。この関数は、 key のハッシュ値を検索と挿入ごとに別々に評価するのではなく、一度だけしか評価しません。

Added in version 3.4.

int PyDict_SetDefaultRef(PyObject *p, PyObject *key, PyObject *default_value, PyObject **result)¶

辞書 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 つ持つことになります。

Added in version 3.13.

int PyDict_Pop(PyObject *p, PyObject *key, PyObject **result)¶

Remove key from dictionary p and optionally return the removed value. Do not raise KeyError if the key is missing.

キーがあれば、result が NULL でない場合には *result に削除した値への新しい参照を設定し、1 を返します。
キーがなければ、result が NULL でない場合には *result に NULL を設定し、0 を返します。
エラーの場合例外を送出し -1 を返します。

Similar to dict.pop(), but without the default value and not raising KeyError if the key is missing.

Added in version 3.13.

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

Added in version 3.13.

PyObject *PyDict_Items(PyObject *p)¶: 戻り値: 新しい参照。 次に属します: Stable ABI.
辞書内の全ての要素対が入った PyListObject を返します。

PyObject *PyDict_Keys(PyObject *p)¶: 戻り値: 新しい参照。 次に属します: Stable ABI.
辞書内の全てのキーが入った PyListObject を返します。

PyObject *PyDict_Values(PyObject *p)¶: 戻り値: 新しい参照。 次に属します: Stable ABI.
辞書 p 内の全ての値が入った PyListObject を返します。

Py_ssize_t PyDict_Size(PyObject *p)¶: 次に属します: Stable ABI.
辞書内の要素の数を返します。辞書に対して len(p) を実行するのと同じです。

Py_ssize_t PyDict_GET_SIZE(PyObject *p)¶: Similar to PyDict_Size(), but without error checking.

int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)¶

次に属します: 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)) {
    /* 値を使って何らかの処理を行う... */
    ...
}

反復処理中に辞書 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);
}

The function is not thread-safe in the free-threaded build without external synchronization. You can use Py_BEGIN_CRITICAL_SECTION to lock the dictionary while iterating over it:

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

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

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

次に属します: 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

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

Added in version 3.12.

int PyDict_ClearWatcher(int watcher_id)¶: 以前に PyDict_AddWatcher() が返した watcher_id で識別されるウォッチャーを解除します。成功すると 0、エラー時 (例えば指定した watcher_id が登録されていない場合) には -1 を返します。

Added in version 3.12.

int PyDict_Watch(int watcher_id, PyObject *dict)¶: 辞書 dict を監視対象にします。 dict が変更または解放されると、PyDict_AddWatcher() で watcher_id を割り当てられたコールバックを呼び出します。成功すると 0、エラー時には -1 を返します。

Added in version 3.12.

int PyDict_Unwatch(int watcher_id, PyObject *dict)¶: 辞書 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.

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.

Dictionary View Objects¶

int PyDictViewSet_Check(PyObject *op)¶: Return true if op is a view of a set inside a dictionary. This is currently equivalent to PyDictKeys_Check(op) || PyDictItems_Check(op). This function always succeeds.

PyTypeObject PyDictKeys_Type¶: 次に属します: Stable ABI.
Type object for a view of dictionary keys. In Python, this is the type of the object returned by dict.keys().

int PyDictKeys_Check(PyObject *op)¶: Return true if op is an instance of a dictionary keys view. This function always succeeds.

PyTypeObject PyDictValues_Type¶: 次に属します: Stable ABI.
Type object for a view of dictionary values. In Python, this is the type of the object returned by dict.values().

int PyDictValues_Check(PyObject *op)¶: Return true if op is an instance of a dictionary values view. This function always succeeds.

PyTypeObject PyDictItems_Type¶: 次に属します: Stable ABI.
Type object for a view of dictionary items. In Python, this is the type of the object returned by dict.items().

int PyDictItems_Check(PyObject *op)¶: Return true if op is an instance of a dictionary items view. This function always succeeds.

Ordered Dictionaries¶

Python's C API provides interface for collections.OrderedDict from C. Since Python 3.7, dictionaries are ordered by default, so there is usually little need for these functions; prefer PyDict* where possible.

PyTypeObject PyODict_Type¶: Type object for ordered dictionaries. This is the same object as collections.OrderedDict in the Python layer.

int PyODict_Check(PyObject *od)¶: Return true if od is an ordered dictionary object or an instance of a subtype of the OrderedDict type. This function always succeeds.

int PyODict_CheckExact(PyObject *od)¶: Return true if od is an ordered dictionary object, but not an instance of a subtype of the OrderedDict type. This function always succeeds.

PyTypeObject PyODictKeys_Type¶: Analogous to PyDictKeys_Type for ordered dictionaries.

PyTypeObject PyODictValues_Type¶: Analogous to PyDictValues_Type for ordered dictionaries.

PyTypeObject PyODictItems_Type¶: Analogous to PyDictItems_Type for ordered dictionaries.

PyObject *PyODict_New(void)¶

Return a new empty ordered dictionary, or NULL on failure.

This is analogous to PyDict_New().

int PyODict_SetItem(PyObject *od, PyObject *key, PyObject *value)¶

Insert value into the ordered dictionary od with a key of key. Return 0 on success or -1 with an exception set on failure.

This is analogous to PyDict_SetItem().

int PyODict_DelItem(PyObject *od, PyObject *key)¶

Remove the entry in the ordered dictionary od with key key. Return 0 on success or -1 with an exception set on failure.

This is analogous to PyDict_DelItem().

These are soft deprecated aliases to PyDict APIs:

`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()`

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

Dictionary View Objects¶

Ordered Dictionaries¶

目次

前のトピックへ

次のトピックへ

このページ