Dictionary Objects

type PyDictObject

Dieser Untertyp von PyObject repräsentiert ein Python-Dictionary-Objekt.

PyTypeObject PyDict_Type
Teil der Stable ABI.

Diese Instanz von PyTypeObject repräsentiert den Python-Dictionary-Typ. Dies ist dasselbe Objekt wie dict auf Python-Ebene.

int PyDict_Check(PyObject *p)

Gibt wahr zurück, wenn p ein Dictionary-Objekt oder eine Instanz eines Untertyps des Dictionary-Typs ist. Diese Funktion schlägt niemals fehl.

int PyDict_CheckExact(PyObject *p)

Gibt wahr zurück, wenn p ein Dictionary-Objekt ist, aber keine Instanz eines Untertyps des Dictionary-Typs. Diese Funktion schlägt niemals fehl.

PyObject *PyDict_New()
Rückgabewert: Neue Referenz. Teil der Stabilen ABI.

Gibt ein neues leeres Dictionary zurück oder NULL im Fehlerfall.

PyObject *PyDictProxy_New(PyObject *mapping)
Rückgabewert: Neue Referenz. Teil der Stabilen ABI.

Gibt ein types.MappingProxyType-Objekt für eine Zuordnung zurück, die schreibgeschütztes Verhalten erzwingt. Dies wird normalerweise verwendet, um eine Ansicht zu erstellen, die verhindert, dass das Dictionary für nicht-dynamische Klassentypen geändert wird.

void PyDict_Clear(PyObject *p)
Teil der Stable ABI.

Leert ein bestehendes Dictionary von allen Schlüssel-Wert-Paaren.

int PyDict_Contains(PyObject *p, PyObject *key)
Teil der Stable ABI.

Bestimmt, ob das Dictionary p den key enthält. Wenn ein Element in p mit key übereinstimmt, wird 1 zurückgegeben, andernfalls 0. Im Fehlerfall wird -1 zurückgegeben. Dies ist äquivalent zum Python-Ausdruck key in p.

int PyDict_ContainsString(PyObject *p, const char *key)

Dies ist dasselbe wie PyDict_Contains(), aber key ist als ein const char* UTF-8-kodierter Byte-String angegeben, anstatt als ein PyObject*.

Hinzugefügt in Version 3.13.

PyObject *PyDict_Copy(PyObject *p)
Rückgabewert: Neue Referenz. Teil der Stabilen ABI.

Gibt ein neues Dictionary zurück, das dieselben Schlüssel-Wert-Paare wie p enthält.

int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)
Teil der Stable ABI.

Fügt val in das Dictionary p mit dem Schlüssel key ein. key muss hashable sein; ist dies nicht der Fall, wird TypeError ausgelöst. Gibt 0 bei Erfolg oder -1 bei einem Fehler zurück. Diese Funktion stiehlt keine Referenz auf val.

int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)
Teil der Stable ABI.

Dies ist dasselbe wie PyDict_SetItem(), aber key ist als ein const char* UTF-8-kodierter Byte-String angegeben, anstatt als ein PyObject*.

int PyDict_DelItem(PyObject *p, PyObject *key)
Teil der Stable ABI.

Entfernt den Eintrag im Dictionary p mit dem Schlüssel key. key muss hashable sein; ist dies nicht der Fall, wird TypeError ausgelöst. Wenn key nicht im Dictionary vorhanden ist, wird KeyError ausgelöst. Gibt 0 bei Erfolg oder -1 bei einem Fehler zurück.

int PyDict_DelItemString(PyObject *p, const char *key)
Teil der Stable ABI.

Dies ist dasselbe wie PyDict_DelItem(), aber key ist als ein const char* UTF-8-kodierter Byte-String angegeben, anstatt als ein PyObject*.

int PyDict_GetItemRef(PyObject *p, PyObject *key, PyObject **result)
Teil des Stable ABI seit Version 3.13.

Gibt eine neue starke Referenz auf das Objekt aus dem Dictionary p zurück, das einen Schlüssel key hat.

  • Wenn der Schlüssel vorhanden ist, wird *result auf eine neue starke Referenz auf den Wert gesetzt und 1 zurückgegeben.

  • Wenn der Schlüssel fehlt, wird *result auf NULL gesetzt und 0 zurückgegeben.

  • Im Fehlerfall wird eine Ausnahme ausgelöst und -1 zurückgegeben.

Hinzugefügt in Version 3.13.

Siehe auch die Funktion PyObject_GetItem().

PyObject *PyDict_GetItem(PyObject *p, PyObject *key)
Rückgabewert: Ausgeliehene Referenz. Teil der Stable ABI.

Gibt eine geborgte Referenz auf das Objekt aus dem Dictionary p zurück, das einen Schlüssel key hat. Gibt NULL zurück, wenn der Schlüssel key fehlt, *ohne* eine Ausnahme zu setzen.

Hinweis

Ausnahmen, die auftreten, wenn diese Funktion die Methoden __hash__() und __eq__() aufruft, werden stillschweigend ignoriert. Bevorzugen Sie stattdessen die Funktion PyDict_GetItemWithError().

Geändert in Version 3.10: Das Aufrufen dieser API ohne eine angehängte Thread-Zustand war aus historischen Gründen erlaubt. Dies ist nicht mehr zulässig.

PyObject *PyDict_GetItemWithError(PyObject *p, PyObject *key)
Rückgabewert: Ausgeliehene Referenz. Teil der Stable ABI.

Variante von PyDict_GetItem(), die keine Ausnahmen unterdrückt. Gibt NULL *mit* einer gesetzten Ausnahme zurück, wenn eine Ausnahme aufgetreten ist. Gibt NULL *ohne* eine gesetzte Ausnahme zurück, wenn der Schlüssel nicht vorhanden war.

PyObject *PyDict_GetItemString(PyObject *p, const char *key)
Rückgabewert: Ausgeliehene Referenz. Teil der Stable ABI.

Dies ist dasselbe wie PyDict_GetItem(), aber key ist als ein const char* UTF-8-kodierter Byte-String angegeben, anstatt als ein PyObject*.

Hinweis

Ausnahmen, die auftreten, wenn diese Funktion die Methoden __hash__() und __eq__() aufruft oder beim Erstellen des temporären str-Objekts, werden stillschweigend ignoriert. Bevorzugen Sie stattdessen die Verwendung der Funktion PyDict_GetItemWithError() mit Ihrem eigenen PyUnicode_FromString() key.

int PyDict_GetItemStringRef(PyObject *p, const char *key, PyObject **result)
Teil des Stable ABI seit Version 3.13.

Ähnlich wie PyDict_GetItemRef(), aber key ist als ein const char* UTF-8-kodierter Byte-String angegeben, anstatt als ein PyObject*.

Hinzugefügt in Version 3.13.

PyObject *PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *defaultobj)
Rückgabewert: Entliehene Referenz.

Dies ist dasselbe wie die Python-Ebene dict.setdefault(). Wenn vorhanden, gibt es den Wert zurück, der key aus dem Dictionary p entspricht. Wenn der Schlüssel nicht im Dictionary vorhanden ist, wird er mit dem Wert defaultobj eingefügt und defaultobj zurückgegeben. Diese Funktion wertet die Hash-Funktion von key nur einmal aus, anstatt sie unabhängig für die Suche und das Einfügen auszuwerten.

Hinzugefügt in Version 3.4.

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

Fügt default_value in das Dictionary p mit dem Schlüssel key ein, wenn der Schlüssel noch nicht im Dictionary vorhanden ist. Wenn result nicht NULL ist, dann wird *result auf eine starke Referenz auf entweder default_value gesetzt (wenn der Schlüssel nicht vorhanden war) oder den vorhandenen Wert (wenn key bereits im Dictionary vorhanden war). Gibt 1 zurück, wenn der Schlüssel vorhanden war und default_value nicht eingefügt wurde, oder 0, wenn der Schlüssel nicht vorhanden war und default_value eingefügt wurde. Im Fehlerfall gibt die Funktion -1 zurück, setzt eine Ausnahme und setzt *result auf NULL.

Zur Klarstellung: Wenn Sie vor dem Aufruf dieser Funktion eine starke Referenz auf default_value haben, dann halten Sie nach der Rückgabe eine starke Referenz auf sowohl default_value als auch *result (wenn es nicht NULL ist). Diese können auf dasselbe Objekt verweisen: In diesem Fall halten Sie zwei separate Referenzen darauf.

Hinzugefügt in Version 3.13.

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

Entfernt key aus dem Dictionary p und gibt optional den entfernten Wert zurück. Löst keine KeyError aus, wenn der Schlüssel fehlt.

  • Wenn der Schlüssel vorhanden ist, wird *result auf eine neue Referenz auf den entfernten Wert gesetzt, wenn result nicht NULL ist, und es wird 1 zurückgegeben.

  • Wenn der Schlüssel fehlt, wird *result auf NULL gesetzt, wenn result nicht NULL ist, und es wird 0 zurückgegeben.

  • Im Fehlerfall wird eine Ausnahme ausgelöst und -1 zurückgegeben.

Ähnlich wie dict.pop(), aber ohne den Standardwert und ohne KeyError auszulösen, wenn der Schlüssel fehlt.

Hinzugefügt in Version 3.13.

int PyDict_PopString(PyObject *p, const char *key, PyObject **result)

Ähnlich wie PyDict_Pop(), aber key ist als ein const char* UTF-8-kodierter Byte-String angegeben, anstatt als ein PyObject*.

Hinzugefügt in Version 3.13.

PyObject *PyDict_Items(PyObject *p)
Rückgabewert: Neue Referenz. Teil der Stabilen ABI.

Gibt eine PyListObject mit allen Elementen aus dem Dictionary zurück.

PyObject *PyDict_Keys(PyObject *p)
Rückgabewert: Neue Referenz. Teil der Stabilen ABI.

Gibt eine PyListObject mit allen Schlüsseln aus dem Dictionary zurück.

PyObject *PyDict_Values(PyObject *p)
Rückgabewert: Neue Referenz. Teil der Stabilen ABI.

Gibt eine PyListObject mit allen Werten aus dem Dictionary p zurück.

Py_ssize_t PyDict_Size(PyObject *p)
Teil der Stable ABI.

Gibt die Anzahl der Elemente im Dictionary zurück. Dies ist äquivalent zu len(p) bei einem Dictionary.

int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)
Teil der Stable ABI.

Iterieren Sie über alle Schlüssel-Wert-Paare im Wörterbuch p. Die von ppos referenzierte Py_ssize_t muss vor dem ersten Aufruf dieser Funktion auf 0 initialisiert werden, um die Iteration zu starten. Die Funktion gibt für jedes Paar im Wörterbuch true zurück und false, sobald alle Paare gemeldet wurden. Die Parameter pkey und pvalue sollten entweder auf PyObject*-Variablen zeigen, die mit jedem Schlüssel und Wert gefüllt werden, oder können NULL sein. Alle über sie zurückgegebenen Referenzen sind ausgeliehen. ppos sollte während der Iteration nicht verändert werden. Sein Wert repräsentiert Offsets innerhalb der internen Wörterbuchstruktur, und da die Struktur spärlich ist, sind die Offsets nicht aufeinanderfolgend.

Zum Beispiel

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

while (PyDict_Next(self->dict, &pos, &key, &value)) {
    /* do something interesting with the values... */
    ...
}

Das Wörterbuch p sollte während der Iteration nicht verändert werden. Es ist sicher, die Werte der Schlüssel während der Iteration über das Wörterbuch zu ändern, aber nur solange sich die Menge der Schlüssel nicht ändert. Zum Beispiel

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);
}

Die Funktion ist in der free-threaded-Build ohne externe Synchronisation nicht threadsicher. Sie können Py_BEGIN_CRITICAL_SECTION verwenden, um das Wörterbuch während der Iteration zu sperren

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

Hinweis

In der Free-threaded-Build kann diese Funktion sicher innerhalb eines kritischen Abschnitts verwendet werden. Die für pkey und pvalue zurückgegebenen Referenzen sind jedoch ausgeliehen und nur gültig, solange der kritische Abschnitt gehalten wird. Wenn Sie diese Objekte außerhalb des kritischen Abschnitts verwenden müssen oder wenn der kritische Abschnitt unterbrochen werden kann, erstellen Sie eine starke Referenz (z.B. mit Py_NewRef()).

int PyDict_Merge(PyObject *a, PyObject *b, int override)
Teil der Stable ABI.

Iteriert über das Mapping-Objekt b und fügt Schlüssel-Wert-Paare zum Wörterbuch a hinzu. b kann ein Wörterbuch oder jedes Objekt sein, das PyMapping_Keys() und PyObject_GetItem() unterstützt. Wenn override true ist, werden vorhandene Paare in a ersetzt, wenn ein übereinstimmender Schlüssel in b gefunden wird, andernfalls werden Paare nur hinzugefügt, wenn kein übereinstimmender Schlüssel in a vorhanden ist. Gibt 0 bei Erfolg oder -1 zurück, wenn eine Ausnahme ausgelöst wurde.

int PyDict_Update(PyObject *a, PyObject *b)
Teil der Stable ABI.

Dies ist dasselbe wie PyDict_Merge(a, b, 1) in C und ähnelt a.update(b) in Python, mit der Ausnahme, dass PyDict_Update() nicht auf das Iterieren über eine Sequenz von Schlüssel-Wert-Paaren zurückgreift, wenn das zweite Argument kein "keys"-Attribut hat. Gibt 0 bei Erfolg oder -1 zurück, wenn eine Ausnahme ausgelöst wurde.

int PyDict_MergeFromSeq2(PyObject *a, PyObject *seq2, int override)
Teil der Stable ABI.

Aktualisiert oder mergt in das Wörterbuch a aus den Schlüssel-Wert-Paaren in seq2. seq2 muss ein iterierbares Objekt sein, das iterierbare Objekte der Länge 2 erzeugt, betrachtet als Schlüssel-Wert-Paare. Bei doppelten Schlüsseln gewinnt der letzte, wenn override true ist, andernfalls gewinnt der erste. Gibt 0 bei Erfolg oder -1 zurück, wenn eine Ausnahme ausgelöst wurde. Äquivalentes Python (außer dem Rückgabewert)

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)

Registriert callback als Wörterbuch-Watcher. Gibt eine nicht-negative Ganzzahl-ID zurück, die bei zukünftigen Aufrufen von PyDict_Watch() übergeben werden muss. Im Fehlerfall (z.B. keine weiteren Watcher-IDs verfügbar) gibt die Funktion -1 zurück und setzt eine Ausnahme.

Hinzugefügt in Version 3.12.

int PyDict_ClearWatcher(int watcher_id)

Löscht den von watcher_id identifizierten Watcher, der zuvor von PyDict_AddWatcher() zurückgegeben wurde. Gibt 0 bei Erfolg, -1 bei Fehler zurück (z.B. wenn die gegebene watcher_id nie registriert wurde).

Hinzugefügt in Version 3.12.

int PyDict_Watch(int watcher_id, PyObject *dict)

Markiert das Wörterbuch dict als zu beobachtendes Objekt. Der von PyDict_AddWatcher() vergebene Callback mit watcher_id wird aufgerufen, wenn dict geändert oder freigegeben wird. Gibt 0 bei Erfolg oder -1 bei Fehler zurück.

Hinzugefügt in Version 3.12.

int PyDict_Unwatch(int watcher_id, PyObject *dict)

Markiert das Wörterbuch dict als nicht mehr zu beobachtendes Objekt. Der von PyDict_AddWatcher() vergebene Callback mit watcher_id wird nicht mehr aufgerufen, wenn dict geändert oder freigegeben wird. Das Wörterbuch muss zuvor von diesem Watcher beobachtet worden sein. Gibt 0 bei Erfolg oder -1 bei Fehler zurück.

Hinzugefügt in Version 3.12.

type PyDict_WatchEvent

Aufzählung möglicher Wörterbuch-Watcher-Ereignisse: PyDict_EVENT_ADDED, PyDict_EVENT_MODIFIED, PyDict_EVENT_DELETED, PyDict_EVENT_CLONED, PyDict_EVENT_CLEARED oder PyDict_EVENT_DEALLOCATED.

Hinzugefügt in Version 3.12.

typedef int (*PyDict_WatchCallback)(PyDict_WatchEvent event, PyObject *dict, PyObject *key, PyObject *new_value)

Typ einer Dict-Watcher-Callback-Funktion.

Wenn event PyDict_EVENT_CLEARED oder PyDict_EVENT_DEALLOCATED ist, sind sowohl key als auch new_value NULL. Wenn event PyDict_EVENT_ADDED oder PyDict_EVENT_MODIFIED ist, ist new_value der neue Wert für key. Wenn event PyDict_EVENT_DELETED ist, wird key aus dem Wörterbuch gelöscht und new_value ist NULL.

PyDict_EVENT_CLONED tritt auf, wenn dict zuvor leer war und ein anderes Wörterbuch hinein gemergt wird. Um die Effizienz dieser Operation zu erhalten, werden hier keine PyDict_EVENT_ADDED-Ereignisse pro Schlüssel ausgegeben; stattdessen wird ein einzelnes PyDict_EVENT_CLONED ausgegeben, und key ist das Quellwörterbuch.

Der Callback kann dict inspizieren, darf es aber nicht ändern; dies könnte unvorhersehbare Auswirkungen haben, einschließlich unendlicher Rekursion. Lösen Sie keine Python-Codeausführung im Callback aus, da dies das Wörterbuch als Nebeneffekt ändern könnte.

Wenn event PyDict_EVENT_DEALLOCATED ist, wird durch die Annahme einer neuen Referenz im Callback auf das kurz vor der Zerstörung stehende Wörterbuch dieses wiederbelebt und daran gehindert, zu diesem Zeitpunkt freigegeben zu werden. Wenn das wiederbelebte Objekt später zerstört wird, werden alle zu diesem Zeitpunkt aktiven Watcher-Callbacks erneut aufgerufen.

Callbacks treten auf, bevor die benachrichtigte Änderung an dict stattfindet, sodass der vorherige Zustand von dict inspiziert werden kann.

Wenn der Callback eine Ausnahme setzt, muss er -1 zurückgeben; diese Ausnahme wird als nicht aufhebbare Ausnahme mit PyErr_WriteUnraisable() ausgegeben. Andernfalls sollte er 0 zurückgeben.

Es kann bereits eine ausstehende Ausnahme beim Eintritt in den Callback gesetzt sein. In diesem Fall sollte der Callback 0 zurückgeben, wobei die Ausnahme weiterhin gesetzt ist. Das bedeutet, der Callback darf keine andere API aufrufen, die eine Ausnahme setzen kann, es sei denn, er speichert und löscht zuerst den Ausnahmezustand und stellt ihn vor der Rückgabe wieder her.

Hinzugefügt in Version 3.12.