Objektprotokoll¶

PyObject *Py_GetConstant(unsigned int constant_id)¶

En del av Stabil ABI sedan version 3.13.

Få en strong reference till en konstant.

Ställ in ett undantag och returnera NULL om constant_id är ogiltig.

constant_id måste vara en av dessa konstantidentifierare:

Konstant identifierare	Värde	Återlämnat objekt
Py_CONSTANT_NONE¶	`0`	`None`
Py_CONSTANT_FALSE¶	`1`	`False`
Py_CONSTANT_TRUE¶	`2`	`True`
Py_CONSTANT_ELLIPSIS¶	`3`	`Ellipsis`
Py_CONSTANT_NOT_IMPLEMENTED¶	`4`	`NotImplemented`
Py_CONSTANT_ZERO¶	`5`	`0`
Py_CONSTANT_ONE¶	`6`	`1`
Py_CONSTANT_EMPTY_STR¶	`7`	`''`
Py_CONSTANT_EMPTY_BYTES¶	`8`	`b''`
Py_CONSTANT_EMPTY_TUPLE¶	`9`	`()`

Numeriska värden anges endast för projekt som inte kan använda de konstanta identifierarna.

Tillagd i version 3.13.

I CPython är alla dessa konstanter immortal.

PyObject *Py_GetConstantBorrowed(unsigned int constant_id)¶

En del av Stabil ABI sedan version 3.13.

Liknar Py_GetConstant(), men returnerar en lånad referens.

Denna funktion är främst avsedd för bakåtkompatibilitet: att använda Py_GetConstant() rekommenderas för ny kod.

Referensen lånas av tolken och gäller till dess att tolken har slutfört sitt uppdrag.

Tillagd i version 3.13.

PyObject *Py_NotImplemented¶: Singleton NotImplemented, används för att signalera att en operation inte är implementerad för den givna typkombinationen.

Py_RETURN_NOTIMPLEMENTED¶: Hantera korrekt returnering av Py_NotImplemented från en C-funktion (dvs. skapa en ny strong reference till NotImplemented och returnera den).

Py_PRINT_RAW¶: Flagga som ska användas med flera funktioner som skriver ut objektet (som PyObject_Print() och PyFile_WriteObject()). Om den godkänns kommer dessa funktioner att använda objektets str() istället för repr().

int PyObject_Print(PyObject *o, FILE *fp, int flags)¶: Skriv ut ett objekt o, på filen fp. Returnerar -1 vid fel. Argumentet flags används för att aktivera vissa utskriftsalternativ. Det enda alternativ som för närvarande stöds är Py_PRINT_RAW; om det anges skrivs objektets str() ut istället för repr().

int PyObject_HasAttrWithError(PyObject *o, PyObject *attr_name)¶: En del av Stabil ABI sedan version 3.13.
Returnerar 1 om o har attributet attr_name, och 0 annars. Detta är likvärdigt med Python-uttrycket hasattr(o, attr_name). Vid misslyckande returneras -1.

Tillagd i version 3.13.

int PyObject_HasAttrStringWithError(PyObject *o, const char *attr_name)¶: En del av Stabil ABI sedan version 3.13.
Detta är samma sak som PyObject_HasAttrWithError(), men attr_name anges som en const char* UTF-8-kodad bytessträng, i stället för en PyObject*.

Tillagd i version 3.13.

int PyObject_HasAttr(PyObject *o, PyObject *attr_name)¶: En del av Stabil ABI.
Returnerar 1 om o har attributet attr_name, och 0 annars. Denna funktion lyckas alltid.

Anteckning

Undantag som uppstår när detta anropar metoderna __getattr__() och __getattribute__() sprids inte, utan ges istället till sys.unraisablehook(). För korrekt felhantering, använd PyObject_HasAttrWithError(), PyObject_GetOptionalAttr() eller PyObject_GetAttr() istället.

int PyObject_HasAttrString(PyObject *o, const char *attr_name)¶: En del av Stabil ABI.
Detta är samma sak som PyObject_HasAttr(), men attr_name anges som en const char* UTF-8-kodad bytessträng, i stället för en PyObject*.

Anteckning

Undantag som uppstår när detta anropar metoderna __getattr__() och __getattribute__() eller när det tillfälliga str-objektet skapas ignoreras i tysthet. För korrekt felhantering, använd PyObject_HasAttrStringWithError(), PyObject_GetOptionalAttrString() eller PyObject_GetAttrString() istället.

PyObject *PyObject_GetAttr(PyObject *o, PyObject *attr_name)¶

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

Hämtar ett attribut med namnet attr_name från objektet o. Returnerar attributvärdet vid framgång, eller NULL vid misslyckande. Detta är motsvarigheten till Python-uttrycket o.attr_name.

Om det saknade attributet inte ska behandlas som ett fel kan du använda PyObject_GetOptionalAttr() istället.

PyObject *PyObject_GetAttrString(PyObject *o, const char *attr_name)¶

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

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

Om det saknade attributet inte ska behandlas som ett fel kan du använda PyObject_GetOptionalAttrString() istället.

int PyObject_GetOptionalAttr(PyObject *obj, PyObject *attr_name, PyObject **result);¶

En del av Stabil ABI sedan version 3.13.

Variant av PyObject_GetAttr() som inte ger upphov till AttributeError om attributet inte hittas.

Om attributet hittas returneras 1 och *result sätts till en ny strong reference till attributet. Om attributet inte hittas, returneras 0 och *result sätts till NULL; AttributeError tystas. Om ett annat fel än AttributeError uppstår, returneras -1 och *result sätts till NULL.

Tillagd i version 3.13.

int PyObject_GetOptionalAttrString(PyObject *obj, const char *attr_name, PyObject **result);¶: En del av Stabil ABI sedan version 3.13.
Detta är samma sak som PyObject_GetOptionalAttr(), men attr_name anges som en const char* UTF-8-kodad bytessträng, i stället för en PyObject*.

Tillagd i version 3.13.

PyObject *PyObject_GenericGetAttr(PyObject *o, PyObject *name)¶: Returnera värde: Ny referens. En del av Stabil ABI.
Generisk getterfunktion för attribut som är avsedd att placeras i ett typobjekts tp_getattro slot. Den letar efter en deskriptor i klassordboken i objektets MRO samt ett attribut i objektets __dict__ (om det finns). Som beskrivs i Implementering av deskriptorer, har datadeskriptorer företräde framför instansattribut, medan icke-datadeskriptorer inte har det. I annat fall uppstår ett AttributeError.

int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v)¶

En del av Stabil ABI.

Ställ in värdet på attributet med namnet attr_name, för objektet o, till värdet v. Utlös ett undantag och returnera -1 vid misslyckande; returnera 0 vid framgång. Detta är motsvarigheten till Python-satsen o.attr_name = v.

Om v är NULL tas attributet bort. Detta beteende är föråldrat till förmån för att använda PyObject_DelAttr(), men det finns för närvarande inga planer på att ta bort det.

int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v)¶

En del av Stabil ABI.

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

Om v är NULL tas attributet bort, men denna funktion är föråldrad till förmån för att använda PyObject_DelAttrString().

Antalet olika attributnamn som skickas till denna funktion bör hållas litet, vanligtvis genom att använda en statiskt allokerad sträng som attr_name. För attributnamn som inte är kända vid kompileringstillfället är det bättre att anropa PyUnicode_FromString() och PyObject_SetAttr() direkt. För mer information, se PyUnicode_InternFromString(), som kan användas internt för att skapa ett nyckelobjekt.

int PyObject_GenericSetAttr(PyObject *o, PyObject *name, PyObject *value)¶: En del av Stabil ABI.
Generisk attributsättnings- och borttagningsfunktion som är avsedd att placeras i ett typobjekts tp_setattro slot. Den letar efter en databeskrivare i klassordboken i objektets MRO, och om den hittas har den företräde framför att sätta eller ta bort attributet i instansordboken. I annat fall sätts eller tas attributet bort i objektets __dict__ (om det finns). Vid framgång returneras 0, annars genereras ett AttributeError och -1 returneras.

int PyObject_DelAttr(PyObject *o, PyObject *attr_name)¶: En del av Stabil ABI sedan version 3.13.
Ta bort attributet med namnet attr_name för objektet o. Returnerar -1 om det misslyckas. Detta är motsvarigheten till Python-satsen del o.attr_name.

int PyObject_DelAttrString(PyObject *o, const char *attr_name)¶

En del av Stabil ABI sedan version 3.13.

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

Antalet olika attributnamn som skickas till denna funktion bör hållas litet, vanligtvis genom att använda en statiskt allokerad sträng som attr_name. För attributnamn som inte är kända vid kompileringstillfället är det bättre att anropa PyUnicode_FromString() och PyObject_DelAttr() direkt. För mer information, se PyUnicode_InternFromString(), som kan användas internt för att skapa ett nyckelobjekt för uppslagning.

PyObject *PyObject_GenericGetDict(PyObject *o, void *context)¶

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

En generisk implementation för gettern för en __dict__ deskriptor. Den skapar ordlistan om det behövs.

Denna funktion kan också anropas för att få __dict__ för objektet o. Ange NULL för context när du anropar den. Eftersom den här funktionen kan behöva allokera minne för ordlistan kan det vara effektivare att anropa PyObject_GetAttr() när man vill komma åt ett attribut på objektet.

Vid misslyckande returneras NULL med en undantagsuppsättning.

Tillagd i version 3.3.

int PyObject_GenericSetDict(PyObject *o, PyObject *value, void *context)¶: En del av Stabil ABI sedan version 3.7.
En generisk implementation för en __dict__ descriptors setter. Den här implementationen tillåter inte att ordboken raderas.

Tillagd i version 3.3.

PyObject **_PyObject_GetDictPtr(PyObject *obj)¶

Returnerar en pekare till __dict__ för objektet obj. Om det inte finns någon __dict__, returneras NULL utan att ett undantag anges.

Denna funktion kan behöva allokera minne för ordlistan, så det kan vara mer effektivt att anropa PyObject_GetAttr() när man vill komma åt ett attribut på objektet.

PyObject *PyObject_RichCompare(PyObject *o1, PyObject *o2, int opid)¶: Returnera värde: Ny referens. En del av Stabil ABI.
Jämför värdena i o1 och o2 med den operation som anges av opid, som måste vara en av Py_LT, Py_LE, Py_EQ, Py_NE, Py_GT eller Py_GE, motsvarande <, <=, ==, !=, >, eller >= respektive. Detta är motsvarigheten till Python-uttrycket o1 op o2, där op är operatorn som motsvarar opid. Returnerar värdet av jämförelsen om den lyckas, eller NULL om den misslyckas.

int PyObject_RichCompareBool(PyObject *o1, PyObject *o2, int opid)¶: En del av Stabil ABI.
Jämför värdena på o1 och o2 med den operation som anges av opid, som PyObject_RichCompare(), men returnerar -1 vid fel, 0 om resultatet är falskt, 1 annars.

Anteckning

Om o1 och o2 är samma objekt kommer PyObject_RichCompareBool() alltid att returnera 1 för Py_EQ och 0 för Py_NE.

PyObject *PyObject_Format(PyObject *obj, PyObject *format_spec)¶

En del av Stabil ABI.

Formatera obj med hjälp av format_spec. Detta är likvärdigt med Python-uttrycket format(obj, format_spec).

format_spec kan vara NULL. I detta fall är anropet likvärdigt med format(obj). Returnerar den formaterade strängen vid framgång, NULL vid misslyckande.

PyObject *PyObject_Repr(PyObject *o)¶: Returnera värde: Ny referens. En del av Stabil ABI.
Beräknar en strängrepresentation av objektet o. Returnerar strängrepresentationen vid framgång, NULL vid misslyckande. Detta är motsvarigheten till Python-uttrycket repr(o). Anropas av den inbyggda funktionen repr().

Ändrad i version 3.4: Denna funktion innehåller nu ett debug-assertion för att säkerställa att den inte i tysthet kasserar ett aktivt undantag.

PyObject *PyObject_ASCII(PyObject *o)¶: Returnera värde: Ny referens. En del av Stabil ABI.
Som PyObject_Repr(), beräkna en strängrepresentation av objektet o, men escape icke-ASCII-tecken i strängen som returneras av PyObject_Repr() med \x, u eller U escapes. Detta genererar en sträng som liknar den som returneras av PyObject_Repr() i Python 2. Anropas av den inbyggda funktionen ascii().

PyObject *PyObject_Str(PyObject *o)¶: Returnera värde: Ny referens. En del av Stabil ABI.
Beräknar en strängrepresentation av objektet o. Returnerar strängrepresentationen vid framgång, NULL vid misslyckande. Detta är motsvarigheten till Python-uttrycket str(o). Anropas av den inbyggda funktionen str() och därför även av funktionen print().

Ändrad i version 3.4: Denna funktion innehåller nu ett debug-assertion för att säkerställa att den inte i tysthet kasserar ett aktivt undantag.

PyObject *PyObject_Bytes(PyObject *o)¶: Returnera värde: Ny referens. En del av Stabil ABI.
Beräkna en bytesrepresentation av objektet o. NULL returneras vid misslyckande och ett bytesobjekt vid framgång. Detta är likvärdigt med Python-uttrycket bytes(o), när o inte är ett heltal. Till skillnad från bytes(o) uppstår ett TypeError när o är ett heltal istället för ett nollinitialiserat bytesobjekt.

int PyObject_IsSubclass(PyObject *derived, PyObject *cls)¶

En del av Stabil ABI.

Returnerar 1 om klassen derived är identisk med eller härledd från klassen cls, annars returneras 0. Vid ett fel returneras -1.

Om cls är en tupel kommer kontrollen att göras mot varje post i cls. Resultatet blir 1 när minst en av kontrollerna returnerar 1, annars blir det 0.

Om cls har en __subclasscheck__()-metod, kommer den att anropas för att bestämma subklassstatusen enligt beskrivningen i PEP 3119. Annars är derived en underklass till cls om den är en direkt eller indirekt underklass, dvs. ingår i cls.__mro__.

Normalt betraktas endast klassobjekt, dvs. instanser av type eller en härledd klass, som klasser. Objekt kan dock åsidosätta detta genom att ha ett __bases__-attribut (som måste vara en tupel av basklasser).

int PyObject_IsInstance(PyObject *inst, PyObject *cls)¶

En del av Stabil ABI.

Returnerar 1 om inst är en instans av klassen cls eller en underklass av cls, eller 0 om inte. Vid fel returneras -1 och ett undantag anges.

Om cls är en tupel kommer kontrollen att göras mot varje post i cls. Resultatet blir 1 när minst en av kontrollerna returnerar 1, annars blir det 0.

Om cls har en __instancecheck__()-metod, kommer den att anropas för att bestämma underklassstatusen enligt beskrivningen i PEP 3119. Annars är inst en instans av cls om dess klass är en underklass av cls.

En instans inst kan åsidosätta vad som anses vara dess klass genom att ha ett __class__-attribut.

Ett objekt cls kan åsidosätta om det betraktas som en klass och vilka dess basklasser är genom att ha ett __bases__-attribut (som måste vara en tupel av basklasser).

Py_hash_t PyObject_Hash(PyObject *o)¶: En del av Stabil ABI.
Beräknar och returnerar hashvärdet för ett objekt o. Vid misslyckande returneras -1. Detta är motsvarigheten till Python-uttrycket hash(o).

Ändrad i version 3.2: Returtypen är nu Py_hash_t. Detta är ett signerat heltal av samma storlek som Py_ssize_t.

Py_hash_t PyObject_HashNotImplemented(PyObject *o)¶: En del av Stabil ABI.
Ställ in en TypeError som anger att type(o) inte är hashable och returnera -1. Denna funktion behandlas speciellt när den lagras i en tp_hash slot, vilket gör det möjligt för en typ att uttryckligen ange för tolkaren att den inte är hashbar.

int PyObject_IsTrue(PyObject *o)¶: En del av Stabil ABI.
Returnerar 1 om objektet o anses vara sant, och 0 annars. Detta är likvärdigt med Python-uttrycket not not o. Vid misslyckande returneras -1.

int PyObject_Not(PyObject *o)¶: En del av Stabil ABI.
Returnerar 0 om objektet o anses vara sant, och 1 annars. Detta är likvärdigt med Python-uttrycket not o. Vid misslyckande returneras -1.

PyObject *PyObject_Type(PyObject *o)¶: Returnera värde: Ny referens. En del av Stabil ABI.
När o är icke-NULL, returnerar ett typobjekt som motsvarar objekttypen för objektet o. Om det misslyckas, uppstår SystemError och returnerar NULL. Detta är likvärdigt med Python-uttrycket type(o). Denna funktion skapar en ny strong reference till returvärdet. Det finns egentligen ingen anledning att använda den här funktionen istället för Py_TYPE()-funktionen, som returnerar en pekare av typen PyTypeObject*, förutom när en ny strong reference behövs.

int PyObject_TypeCheck(PyObject *o, PyTypeObject *type)¶: Returnerar icke-noll om objektet o är av typen type eller en subtyp av type, och 0 annars. Båda parametrarna måste vara icke-NULL.

Py_ssize_t PyObject_Size(PyObject *o)¶
Py_ssize_t PyObject_Length(PyObject *o)¶: En del av Stabil ABI.
Returnerar längden på objektet o. Om objektet o tillhandahåller antingen sekvens- eller mappningsprotokollet returneras sekvenslängden. Vid fel returneras -1. Detta är motsvarigheten till Python-uttrycket len(o).

Py_ssize_t PyObject_LengthHint(PyObject *o, Py_ssize_t defaultvalue)¶: Returnerar en uppskattad längd för objektet o. Försök först att returnera dess faktiska längd, sedan en uppskattning med hjälp av __length_hint__(), och slutligen returnera standardvärdet. Vid fel returneras -1. Detta är motsvarigheten till Python-uttrycket operator.length_hint(o, defaultvalue).

Tillagd i version 3.4.

PyObject *PyObject_GetItem(PyObject *o, PyObject *key)¶: Returnera värde: Ny referens. En del av Stabil ABI.
Returnerar element av o som motsvarar objektet key eller NULL om det misslyckas. Detta är motsvarigheten till Python-uttrycket o[key].

int PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v)¶: En del av Stabil ABI.
Mappa objektet key till värdet v. Utlös ett undantag och returnera -1 vid misslyckande; returnera 0 vid framgång. Detta är motsvarigheten till Python-satsen o[key] = v. Den här funktionen stjäl inte en referens till v.

int PyObject_DelItem(PyObject *o, PyObject *key)¶: En del av Stabil ABI.
Ta bort mappningen för objektet key från objektet o. Returnerar -1 vid misslyckande. Detta är likvärdigt med Python-satsen del o[key].

int PyObject_DelItemString(PyObject *o, const char *key)¶: En del av Stabil ABI.
Detta är samma sak som PyObject_DelItem(), men key anges som en const char* UTF-8-kodad bytessträng, i stället för en PyObject*.

PyObject *PyObject_Dir(PyObject *o)¶: Returnera värde: Ny referens. En del av Stabil ABI.
Detta motsvarar Python-uttrycket dir(o), som returnerar en (eventuellt tom) lista med strängar som passar för objektargumentet, eller NULL om det uppstod ett fel. Om argumentet är NULL, är detta som Pythons dir(), som returnerar namnen på de aktuella lokala platserna; i detta fall, om ingen exekveringsram är aktiv, returneras NULL men PyErr_Occurred() kommer att returnera false.

PyObject *PyObject_GetIter(PyObject *o)¶: Returnera värde: Ny referens. En del av Stabil ABI.
Detta är likvärdigt med Python-uttrycket iter(o). Det returnerar en ny iterator för objektargumentet, eller själva objektet om objektet redan är en iterator. Utlöser TypeError och returnerar NULL om objektet inte kan itereras.

PyObject *PyObject_SelfIter(PyObject *obj)¶: Returnera värde: Ny referens. En del av Stabil ABI.
Detta motsvarar Python-metoden __iter__(self): return self. Den är avsedd för iterator-typer, som ska användas i PyTypeObject.tp_iter-slot.

PyObject *PyObject_GetAIter(PyObject *o)¶: Returnera värde: Ny referens. En del av Stabil ABI sedan version 3.10.
Detta är motsvarigheten till Python-uttrycket aiter(o). Tar ett AsyncIterable-objekt och returnerar en AsyncIterator för det. Detta är typiskt en ny iterator men om argumentet är en AsyncIterator returnerar den sig själv. Utlöser TypeError och returnerar NULL om objektet inte kan itereras.

Tillagd i version 3.10.

void *PyObject_GetTypeData(PyObject *o, PyTypeObject *cls)¶

En del av Stabil ABI sedan version 3.12.

Hämta en pekare till underklassspecifika data som reserverats för cls.

Objektet o måste vara en instans av cls, och cls måste ha skapats med negativa PyType_Spec.basicsize. Python kontrollerar inte detta.

Vid fel, sätt ett undantag och returnera NULL.

Tillagd i version 3.12.

Py_ssize_t PyType_GetTypeDataSize(PyTypeObject *cls)¶

En del av Stabil ABI sedan version 3.12.

Returnerar storleken på det instansminnesutrymme som reserverats för cls, dvs. storleken på det minne som PyObject_GetTypeData() returnerar.

Detta kan vara större än vad som begärdes med -PyType_Spec.basicsize; det är säkert att använda denna större storlek (t.ex. med memset()).

Typen cls måste ha skapats med negativ PyType_Spec.basicsize. Python kontrollerar inte detta.

Vid fel, skapa ett undantag och returnera ett negativt värde.

Tillagd i version 3.12.

void *PyObject_GetItemData(PyObject *o)¶

Hämta en pekare till data per artikel för en klass med Py_TPFLAGS_ITEMS_AT_END.

Vid fel, ställ in ett undantag och returnera NULL. TypeError uppstår om o inte har Py_TPFLAGS_ITEMS_AT_END inställt.

Tillagd i version 3.12.

int PyObject_VisitManagedDict(PyObject *obj, visitproc visit, void *arg)¶

Besök den hanterade ordlistan över obj.

Denna funktion får endast anropas i en traversefunktion av den typ som har flaggan Py_TPFLAGS_MANAGED_DICT inställd.

Tillagd i version 3.13.

void PyObject_ClearManagedDict(PyObject *obj)¶

Rensa den hanterade ordlistan för obj.

Denna funktion får endast anropas i en traversefunktion av den typ som har flaggan Py_TPFLAGS_MANAGED_DICT inställd.

Tillagd i version 3.13.

int PyUnstable_Object_EnableDeferredRefcount(PyObject *obj)¶

Detta är Instabilt API. Den kan ändras utan förvarning i mindre versioner.

Aktivera uppskjuten referensräkning på obj, om det stöds av körtiden. I free-threaded-versionen gör detta att tolken kan undvika referensräkningsjusteringar för obj, vilket kan förbättra prestanda för flera trådar. Avvägningen är att obj endast kommer att avallokeras av den spårande skräpsamlaren, och inte när tolken inte längre har några referenser till den.

Denna funktion returnerar 1 om uppskjuten referensräkning är aktiverad på obj och 0 om uppskjuten referensräkning inte stöds eller om tolken ignorerade tipset, t.ex. när uppskjuten referensräkning redan är aktiverad på obj. Denna funktion är trådsäker och kan inte misslyckas.

Den här funktionen gör ingenting på byggen med GIL aktiverat, som inte stöder uppskjuten referensräkning. Den gör inte heller något om obj inte är ett objekt som spåras av skräpsamlaren (se gc.is_tracked() och PyObject_GC_IsTracked()).

Denna funktion är avsedd att användas strax efter att obj har skapats, av den kod som skapar det, t.ex. i objektets tp_new slot.

Tillagd i version 3.14.

int PyUnstable_Object_IsUniqueReferencedTemporary(PyObject *obj)¶

Detta är Instabilt API. Den kan ändras utan förvarning i mindre versioner.

Kontrollerar om obj är ett unikt temporärt objekt. Returnerar 1 om det är känt att obj är ett unikt temporärt objekt, och 0 annars. Denna funktion kan inte misslyckas, men kontrollen är konservativ och kan returnera 0 i vissa fall även om obj är ett unikt temporärt objekt.

Om ett objekt är ett unikt temporärt objekt, är det garanterat att den aktuella koden har den enda referensen till objektet. För argument till C-funktioner bör detta användas istället för att kontrollera om referensräknaren är 1. Från och med Python 3.14 undviker tolken internt vissa ändringar av referensräknaren när objekt laddas till operandstacken genom att låna referenser när det är möjligt, vilket innebär att en referensräknare på 1 i sig inte garanterar att ett funktionsargument är unikt refererat.

I exemplet nedan anropas my_func med ett unikt temporärt objekt som argument:

my_func([1, 2, 3])

I exemplet nedan anropas my_func inte med ett unikt temporärt objekt som argument, även om dess refcount är 1:

min_lista = [1, 2, 3]
my_func(min_lista)

Se även funktionen Py_REFCNT().

Tillagd i version 3.14.

int PyUnstable_IsImmortal(PyObject *obj)¶: Detta är Instabilt API. Den kan ändras utan förvarning i mindre versioner.

Denna funktion returnerar icke-noll om obj är immortal, och noll annars. Denna funktion kan inte misslyckas.

Anteckning

Objekt som är odödliga i en CPython-version är inte garanterat odödliga i en annan.

Tillagd i version 3.14.

int PyUnstable_TryIncRef(PyObject *obj)¶

Detta är Instabilt API. Den kan ändras utan förvarning i mindre versioner.

Ökar referensantalet för obj om det inte är noll. Returnerar 1 om objektets referensantal har ökats framgångsrikt. Annars returnerar denna funktion 0.

PyUnstable_EnableTryIncRef() måste ha anropats tidigare på obj annars kan denna funktion felaktigt returnera 0 i free threading-bygget.

Denna funktion är logiskt ekvivalent med följande C-kod, förutom att den beter sig atomiskt i free threading build:

if (Py_REFCNT(op) > 0) {
   Py_INCREF(op);
   returnera 1;
}
return 0;

Detta är tänkt som en byggsten för att hantera svaga referenser utan att behöva använda Python svagt referensobjekt.

Normalt kräver korrekt användning av denna funktion stöd från obj:s deallokator (tp_dealloc). Följande skiss kan t.ex. anpassas för att implementera en ”weakmap” som fungerar som en WeakValueDictionary för en viss typ:

PyMutex mutex;

PyObjekt *
add_entry(weakmap_key_type *key, PyObject *value)
{
    PyUnstable_EnableTryIncRef(värde);
    weakmap_type weakmap = ...;
    PyMutex_Lock(&mutex);
    weakmap_add_entry(weakmap, nyckel, värde);
    PyMutex_Unlock(&mutex);
    Py_RETURN_NONE;
}

PyObject *
get_value(weakmap_key_type *key)
{
    weakmap_type weakmap = ...;
    PyMutex_Lock(&mutex);
    PyObject *result = weakmap_find(weakmap, nyckel);
    if (PyUnstable_TryIncRef(resultat)) {
        // `result` är säkert att använda
        PyMutex_Unlock(&mutex);
        returnera resultat;
    }
    // om vi kommer hit börjar `result` samlas in som skräp,
    // men har inte tagits bort från den svaga kartan ännu
    PyMutex_Unlock(&mutex);
    returnera NULL;
}

// tp_dealloc-funktion för svaga mappvärden
void
value_dealloc(PyObject *värde)
{
    weakmap_type weakmap = ...;
    PyMutex_Lock(&mutex);
    weakmap_remove_value(weakmap, värde);

    ...
    PyMutex_Unlock(&mutex);
}

Tillagd i version 3.14.

void PyUnstable_EnableTryIncRef(PyObject *obj)¶: Detta är Instabilt API. Den kan ändras utan förvarning i mindre versioner.

Möjliggör efterföljande användning av PyUnstable_TryIncRef() på obj. Den som anropar måste ha en strong reference till obj när detta anropas.

Tillagd i version 3.14.

int PyUnstable_Object_IsUniquelyReferenced(PyObject *op)¶

Detta är Instabilt API. Den kan ändras utan förvarning i mindre versioner.

Avgör om op endast har en referens.

På GIL-aktiverade byggsystem är den här funktionen likvärdig med Py_REFCNT(op) == 1.

På en fritt trådad byggnation kontrollerar detta om op:s reference count är lika med ett och kontrollerar dessutom om op endast används av denna tråd. Py_REFCNT(op) == 1 är inte trådsäker på fritt trådade byggnader; föredra denna funktion.

Den som anropar måste ha en attached thread state, trots att den här funktionen inte anropar Python-tolken. Denna funktion kan inte misslyckas.

Tillagd i version 3.14.

Objektprotokoll¶

Föregående ämne

Nästa ämne

Denna sidan