Ordboksobjekt

type PyDictObject

Denna subtyp av PyObject representerar ett Python-ordboksobjekt.

PyTypeObject PyDict_Type

En del av Stabil ABI.

Denna instans av PyTypeObject representerar Pythons ordbokstyp. Detta är samma objekt som dict i Python-lagret.

int PyDict_Check(PyObject *p)

Returnerar true om p är ett dict-objekt eller en instans av en subtyp av dict-typen. Denna funktion lyckas alltid.

int PyDict_CheckExact(PyObject *p)

Returnerar true om p är ett dict-objekt, men inte en instans av en subtyp av dict-typen. Denna funktion lyckas alltid.

PyObject *PyDict_New()

Returnera värde: Ny referens. En del av Stabil ABI.

Returnerar en ny tom ordbok, eller NULL om den misslyckas.

PyObject *PyDictProxy_New(PyObject *mapping)

Returnera värde: Ny referens. En del av Stabil ABI.

Returnerar ett types.MappingProxyType-objekt för en mappning som kräver skrivskyddad läsning. Detta används normalt för att skapa en vy som förhindrar ändring av ordlistan för icke-dynamiska klasstyper.

void PyDict_Clear(PyObject *p)

En del av Stabil ABI.

Tömmer en befintlig ordbok på alla nyckel-värde-par.

int PyDict_Contains(PyObject *p, PyObject *key)

En del av Stabil ABI.

Bestäm om ordlistan p innehåller nyckel. Om ett objekt i p matchar nyckel, returneras 1, annars returneras 0. Vid fel returneras -1. Detta motsvarar Python-uttrycket key in p.

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

Detta är samma sak som PyDict_Contains(), men key anges som en const char* UTF-8-kodad bytessträng, i stället för ett PyObject*.

Tillagd i version 3.13.

PyObject *PyDict_Copy(PyObject *p)

Returnera värde: Ny referens. En del av Stabil ABI.

Returnerar en ny dictionary som innehåller samma nyckel-värde-par som p.

int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)

En del av Stabil ABI.

Infogar val i ordlistan p med nyckeln key. key måste vara hashable; om den inte är det kommer TypeError att returneras. Returnerar 0 vid framgång eller -1 vid misslyckande. Denna funktion stjäl inte en referens till val.

int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)

En del av Stabil ABI.

Detta är samma sak som PyDict_SetItem(), men key anges som en const char* UTF-8-kodad bytessträng, i stället för en PyObject*.

int PyDict_DelItem(PyObject *p, PyObject *key)

En del av Stabil ABI.

Tar bort posten i ordlistan p med nyckeln key. key måste vara hashable; om den inte är det, TypeError. Om key inte finns i ordlistan, KeyError. Returnerar 0 vid framgång eller -1 vid misslyckande.

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

En del av Stabil ABI.

Detta är samma sak som PyDict_DelItem(), men key anges som en const char* UTF-8-kodad bytessträng, istället för en PyObject*.

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

En del av Stabil ABI sedan version 3.13.

Returnerar en ny strong reference till det objekt från ordlistan p som har nyckeln key:

• Om nyckeln finns, sätt *result till en ny strong reference till värdet och returnera 1.

• Om nyckeln saknas, sätt *result till NULL och returnera 0.

• Vid fel, skapa ett undantag och returnera -1.

Tillagd i version 3.13.

Se även funktionen PyObject_GetItem().

PyObject *PyDict_GetItem(PyObject *p, PyObject *key)

Returnera värde: Lånad referens. En del av Stabil ABI.

Returnerar en lånad referens till det objekt från ordlistan p som har nyckeln key. Returnerar NULL om nyckeln key saknas utan att ett undantag anges.

Anteckning

Undantag som inträffar när detta anropar metoderna __hash__() och __eq__() ignoreras tyst. Föredra funktionen PyDict_GetItemWithError() istället.

Ändrad i version 3.10: Att anropa detta API utan en attached thread state hade varit tillåtet av historiska skäl. Det är inte längre tillåtet.

PyObject *PyDict_GetItemWithError(PyObject *p, PyObject *key)

Returnera värde: Lånad referens. En del av Stabil ABI.

Variant av PyDict_GetItem() som inte undertrycker undantag. Returnerar NULL med en undantagsuppsättning om ett undantag inträffade. Returnerar NULL utan en undantagsuppsättning om nyckeln inte fanns.

PyObject *PyDict_GetItemString(PyObject *p, const char *key)

Returnera värde: Lånad referens. En del av Stabil ABI.

Detta är samma sak som PyDict_GetItem(), men key anges som en const char* UTF-8-kodad bytessträng, i stället för en PyObject*.

Anteckning

Undantag som inträffar när detta anropar metoderna __hash__() och __eq__() eller när det tillfälliga str-objektet skapas ignoreras i tysthet. Använd hellre funktionen PyDict_GetItemWithError() med din egen PyUnicode_FromString() key istället.

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

En del av Stabil ABI sedan version 3.13.

Liknar PyDict_GetItemRef(), men key anges som en const char* UTF-8-kodad bytessträng, i stället för en PyObject*.

Tillagd i version 3.13.

PyObject *PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *defaultobj)

Returnera värde: Lånad referens.

Detta är samma sak som Python-nivå dict.setdefault(). Om den finns returnerar den värdet som motsvarar key från ordlistan p. Om nyckeln inte finns i dict, infogas den med värdet defaultobj och defaultobj returneras. Denna funktion utvärderar hashfunktionen för key endast en gång, i stället för att utvärdera den oberoende av varandra för uppslagning och infogning.

Tillagd i version 3.4.

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

Lägger till default_value i ordlistan p med nyckeln key om nyckeln inte redan finns i ordlistan. Om result inte är NULL, sätts *result till en strong reference till antingen default_value, om nyckeln inte fanns, eller det befintliga värdet, om key redan fanns i ordlistan. Returnerar 1 om nyckeln fanns och default_value inte infogades, eller 0 om nyckeln inte fanns och default_value infogades. Vid misslyckande returneras -1, ett undantag skapas och *result sätts till NULL.

För tydlighetens skull: om du har en stark referens till default_value innan du anropar den här funktionen, så har du en stark referens till både default_value och *result (om det inte är NULL) efter att den har returnerat. Dessa kan referera till samma objekt: i så fall har du två separata referenser till det.

Tillagd i version 3.13.

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

Tar bort nyckel från ordlistan p och returnerar eventuellt det borttagna värdet. Ge inte KeyError om nyckeln saknas.

• Om nyckeln finns, sätt *result till en ny referens till det borttagna värdet om result inte är NULL, och returnera 1.

• Om nyckeln saknas, sätt *result till NULL om result inte är NULL, och returnera 0.

• Vid fel, skapa ett undantag och returnera -1.

Liknar dict.pop(), men utan standardvärde och utan att ge upphov till KeyError om nyckeln saknas.

Tillagd i version 3.13.

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

Liknar PyDict_Pop(), men key anges som en const char* UTF-8-kodad bytessträng, i stället för ett PyObject*.

Tillagd i version 3.13.

PyObject *PyDict_Items(PyObject *p)

Returnera värde: Ny referens. En del av Stabil ABI.

Returnerar ett PyListObject som innehåller alla objekt från ordlistan.

PyObject *PyDict_Keys(PyObject *p)

Returnera värde: Ny referens. En del av Stabil ABI.

Returnerar ett PyListObject som innehåller alla nycklar från ordlistan.

PyObject *PyDict_Values(PyObject *p)

Returnera värde: Ny referens. En del av Stabil ABI.

Returnerar ett PyListObject som innehåller alla värden från ordlistan p.

Py_ssize_t PyDict_Size(PyObject *p)

En del av Stabil ABI.

Returnerar antalet objekt i ordlistan. Detta är likvärdigt med len(p) för en ordbok.

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

En del av Stabil ABI.

Iterera över alla nyckel-värde-par i ordlistan p. Den Py_ssize_t som hänvisas till av ppos måste initialiseras till 0 före det första anropet till denna funktion för att starta iterationen; funktionen returnerar true för varje par i ordlistan och false när alla par har rapporterats. Parametrarna pkey och pvalue ska antingen peka på PyObject*-variabler som kommer att fyllas i med varje nyckel respektive värde, eller vara NULL. Alla referenser som returneras genom dem lånas. ppos bör inte ändras under iterationen. Dess värde representerar offsets inom den interna ordboksstrukturen, och eftersom strukturen är gles är offseten inte konsekutiva.

Till exempel:

PyObject *nyckel, *värde;
Py_ssize_t pos = 0;

while (PyDict_Next(self->dict, &pos, &key, &value)) {
    /* gör något intressant med värdena... */
    ...
}

Ordboken p ska inte ändras under iterationen. Det är säkert att ändra värdena på nycklarna när du itererar över ordlistan, men bara så länge som uppsättningen nycklar inte ändras. Till exempel:

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

Funktionen är inte trådsäker i free-threaded-byggnaden utan extern synkronisering. Du kan använda Py_BEGIN_CRITICAL_SECTION för att låsa ordlistan medan du itererar över den:

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

Anteckning

I det fritt trådade bygget kan denna funktion användas säkert inom en kritisk sektion. Referenserna som returneras för pkey och pvalue är dock lånade och är endast giltiga vid den kritiska sektionen. Om du behöver använda dessa objekt utanför den kritiska sektionen eller när den kritiska sektionen kan avbrytas, skapa en strong reference (till exempel med Py_NewRef()).

int PyDict_Merge(PyObject *a, PyObject *b, int override)

En del av Stabil ABI.

Iterera över mappningsobjektet b och lägg till nyckel-värdepar i ordboken a. b kan vara en ordbok eller ett objekt som stöder PyMapping_Keys() och PyObject_GetItem(). Om override är true kommer befintliga par i a att ersättas om en matchande nyckel hittas i b, annars kommer par endast att läggas till om det inte finns någon matchande nyckel i a. Returnerar 0 vid framgång eller -1 om ett undantag har uppstått.

int PyDict_Update(PyObject *a, PyObject *b)

En del av Stabil ABI.

Detta är samma sak som PyDict_Merge(a, b, 1) i C, och liknar a.update(b) i Python förutom att PyDict_Update() inte faller tillbaka till att iterera över en sekvens av nyckel-värde-par om det andra argumentet inte har något ”keys”-attribut. Returnerar 0 vid framgång eller -1 om ett undantag uppstod.

int PyDict_MergeFromSeq2(PyObject *a, PyObject *seq2, int override)

En del av Stabil ABI.

Uppdatera eller sammanfoga till ordboken a, från nyckelvärdeparen i seq2. seq2 måste vara ett itererbart objekt som producerar itererbara objekt med längden 2, betraktade som nyckel-värdepar. Vid duplicerade nycklar vinner den sista om override är sant, annars vinner den första. Returnerar 0 vid framgång eller -1 om ett undantag uppstod. Motsvarande Python (förutom returvärdet):

def PyDict_MergeFromSeq2(a, seq2, override):
    för nyckel, värde i seq2:
        om override eller key inte finns i a:
            a[nyckel] = värde

int PyDict_AddWatcher(PyDict_WatchCallback callback)

Registrera callback som en dictionary watcher. Returnera ett icke-negativt heltals-id som måste skickas till framtida anrop till PyDict_Watch(). I händelse av fel (t.ex. inga fler bevaknings-IDs tillgängliga), returnera -1 och sätt ett undantag.

Tillagd i version 3.12.

int PyDict_ClearWatcher(int watcher_id)

Rensa bevakare identifierad av watcher_id som tidigare returnerats från PyDict_AddWatcher(). Returnerar 0 vid framgång, -1 vid fel (t.ex. om det givna watcher_id aldrig registrerades)

Tillagd i version 3.12.

int PyDict_Watch(int watcher_id, PyObject *dict)

Markera ordboken dict som bevakad. Återkallelsen som tilldelats watcher_id av PyDict_AddWatcher() kommer att anropas när dict ändras eller avallokeras. Returnerar 0 vid framgång eller -1 vid fel.

Tillagd i version 3.12.

int PyDict_Unwatch(int watcher_id, PyObject *dict)

Markera ordboken dict som inte längre bevakad. Återkallelsen som tilldelades watcher_id av PyDict_AddWatcher() kommer inte längre att anropas när dict ändras eller avallokeras. Dict måste tidigare ha bevakats av denna bevakare. Returnerar 0 vid framgång eller -1 vid fel.

Tillagd i version 3.12.

type PyDict_WatchEvent

Uppräkning av möjliga händelser för ordboksövervakare: PyDict_EVENT_ADDED, PyDict_EVENT_MODIFIED, PyDict_EVENT_DELETED, PyDict_EVENT_CLONED, PyDict_EVENT_CLEARED eller PyDict_EVENT_DEALLOCATED.

Tillagd i version 3.12.

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

Typ av återuppringningsfunktion för en dict watcher.

Om event är PyDict_EVENT_CLEARED eller PyDict_EVENT_DEALLOCATED kommer både key och new_value att vara NULL. Om event är PyDict_EVENT_ADDED eller PyDict_EVENT_MODIFIED, kommer new_value att vara det nya värdet för key. Om event är PyDict_EVENT_DELETED raderas key från ordlistan och new_value blir NULL.

PyDict_EVENT_CLONED inträffar när dict tidigare var tomt och en annan dict har slagits samman med det. För att upprätthålla effektiviteten i denna operation utfärdas inte händelser per nyckel PyDict_EVENT_ADDED i detta fall. Istället utfärdas en enda PyDict_EVENT_CLONED, och key blir källordlistan.

Callbacken kan inspektera men får inte modifiera dict; att göra det kan få oförutsägbara effekter, inklusive oändlig rekursion. Utlös inte exekvering av Python-kod i återuppringningen, eftersom det kan ändra dict som en bieffekt.

Om event är PyDict_EVENT_DEALLOCATED kommer en ny referens i återuppringningen till den ordbok som ska förstöras att återuppliva den och förhindra att den frigörs vid den här tidpunkten. När det återupplivade objektet förstörs senare, kommer alla watchers callbacks som är aktiva vid den tidpunkten att anropas igen.

Återkallelser sker innan den aviserade modifieringen av dict äger rum, så att dict tidigare tillstånd kan inspekteras.

Om callbacken anger ett undantag måste den returnera -1; detta undantag kommer att skrivas ut som ett undantag som inte kan bedömas med PyErr_WriteUnraisable(). Annars bör det returnera 0.

Det kan redan finnas ett väntande undantag inställt vid ingången till återuppringningen. I detta fall bör återuppringningen returnera 0 med samma undantag fortfarande inställt. Detta innebär att återuppringningen inte får anropa något annat API som kan ställa in ett undantag om det inte sparar och rensar undantagstillståndet först och återställer det innan det returneras.

Tillagd i version 3.12.