Vanliga objektstrukturer

Det finns ett stort antal strukturer som används vid definitionen av objekttyper i Python. I detta avsnitt beskrivs dessa strukturer och hur de används.

Typer av basobjekt och makron

Alla Python-objekt delar i slutändan ett litet antal fält i början av objektets representation i minnet. Dessa representeras av typerna PyObject och PyVarObject, som i sin tur definieras av utvidgningarna av vissa makron som också används, direkt eller indirekt, i definitionen av alla andra Python-objekt. Ytterligare makron finns under referensräkning.

type PyObject

En del av Begränsat API. (Endast vissa medlemmar ingår i det stabila ABI.)

Alla objekttyper är utvidgningar av denna typ. Detta är en typ som innehåller den information som Python behöver för att behandla en pekare till ett objekt som ett objekt. I en normal ”release”-byggnad innehåller den bara objektets referensantal och en pekare till motsvarande typobjekt. Ingenting är faktiskt deklarerat att vara ett PyObject, men varje pekare till ett Python-objekt kan castas till ett PyObject*.

Medlemmarna får inte nås direkt; använd istället makron som Py_REFCNT och Py_TYPE.

Py_ssize_t ob_refcnt

En del av Stabil ABI.

Objektets referensantal, som returneras av Py_REFCNT. Använd inte detta fält direkt, utan använd istället funktioner och makron som Py_REFCNT, Py_INCREF() och Py_DecRef().

Fälttypen kan skilja sig från Py_ssize_t, beroende på byggkonfiguration och plattform.

PyTypeObject *ob_type

En del av Stabil ABI.

Objektets typ. Använd inte detta fält direkt; använd Py_TYPE och Py_SET_TYPE() istället.

type PyVarObject

En del av Begränsat API. (Endast vissa medlemmar ingår i det stabila ABI.)

En utökning av PyObject som lägger till fältet ob_size. Detta är avsett för objekt som har någon uppfattning om längd.

Precis som med PyObject får medlemmarna inte nås direkt; använd istället makron som Py_SIZE, Py_REFCNT och Py_TYPE.

Py_ssize_t ob_size

En del av Stabil ABI.

Ett storleksfält, vars innehåll bör betraktas som ett objekts interna implementeringsdetaljer.

Använd inte detta fält direkt utan använd istället Py_SIZE.

Objektskapande funktioner som PyObject_NewVar() kommer i allmänhet att sätta detta fält till den begärda storleken (antal objekt). Efter skapandet kan godtyckliga värden lagras i ob_size med hjälp av Py_SET_SIZE.

För att få ett objekts offentligt exponerade längd, som returneras av Python-funktionen len(), använder du istället PyObject_Length().

PyObject_HEAD

Detta är ett makro som används vid deklaration av nya typer som representerar objekt utan varierande längd. PyObject_HEAD-makrot expanderar till:

PyObject ob_base;

Se dokumentation av PyObject ovan.

PyObject_VAR_HEAD

Detta är ett makro som används vid deklaration av nya typer som representerar objekt med en längd som varierar från instans till instans. Makrot PyObject_VAR_HEAD expanderar till:

PyVarObject ob_base;

Se dokumentation av PyVarObject ovan.

PyTypeObject PyBaseObject_Type

En del av Stabil ABI.

Basklassen för alla andra objekt, samma sak som object i Python.

int Py_Is(PyObject *x, PyObject *y)

En del av Stabil ABI sedan version 3.10.

Testar om x-objektet är y-objektet, på samma sätt som x is y i Python.

Tillagd i version 3.10.

int Py_IsNone(PyObject *x)

En del av Stabil ABI sedan version 3.10.

Testar om ett objekt är singleton None, samma sak som x is None i Python.

Tillagd i version 3.10.

int Py_IsTrue(PyObject *x)

En del av Stabil ABI sedan version 3.10.

Testar om ett objekt är True singleton, på samma sätt som x is True i Python.

Tillagd i version 3.10.

int Py_IsFalse(PyObject *x)

En del av Stabil ABI sedan version 3.10.

Testar om ett objekt är False singleton, samma sak som x is False i Python.

Tillagd i version 3.10.

PyTypeObject *Py_TYPE(PyObject *o)

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

Hämta typen av Python-objekt o.

Den returnerade referensen är borrowed från o. Frigör den inte med Py_DECREF() eller liknande.

Ändrad i version 3.11: Py_TYPE() ändras till en inline statisk funktion. Parametertypen är inte längre const PyObject*.

int Py_IS_TYPE(PyObject *o, PyTypeObject *type)

Returnerar icke-noll om objektets o typ är type. Returnerar noll annars. Likvärdig med: Py_TYPE(o) == typ.

Tillagd i version 3.9.

void Py_SET_TYPE(PyObject *o, PyTypeObject *type)

Sätt typen av objekt o till typ, utan kontroll eller referensräkning.

Detta är en operation på mycket låg nivå. Överväg istället att ställa in Python-attributet __class__ med hjälp av PyObject_SetAttrString() eller liknande.

Observera att om du tilldelar en inkompatibel typ kan det leda till ett odefinierat beteende.

Om typ är en heap-typ, måste anroparen skapa en ny referens till den. På samma sätt, om den gamla typen av o är en heap-typ, måste den som anropar frigöra en referens till den typen.

Tillagd i version 3.9.

Py_ssize_t Py_SIZE(PyVarObject *o)

Hämta fältet ob_size för o.

Ändrad i version 3.11: Py_SIZE() är ändrad till en inline statisk funktion. Parametertypen är inte längre const PyVarObject*.

void Py_SET_SIZE(PyVarObject *o, Py_ssize_t size)

Sätt fältet ob_size i o till size.

Tillagd i version 3.9.

PyObject_HEAD_INIT(type)

Detta är ett makro som expanderar till initialiseringsvärden för en ny PyObject-typ. Detta makro expanderar till:

_PyObjekt_EXTRA_INIT
1, typ,

PyVarObject_HEAD_INIT(type, size)

Detta är ett makro som expanderar till initialiseringsvärden för en ny PyVarObject-typ, inklusive fältet ob_size. Detta makro expanderar till:

_PyObjekt_EXTRA_INIT
1, typ, storlek,

Implementering av funktioner och metoder

type PyCFunction

En del av Stabil ABI.

Typ av funktioner som används för att implementera de flesta Python-kallelser i C. Funktioner av denna typ tar två PyObject*-parametrar och returnerar ett sådant värde. Om returvärdet är NULL skall ett undantag ha ställts in. Om det inte är NULL tolkas returvärdet som returvärdet för funktionen som den exponeras i Python. Funktionen måste returnera en ny referens.

Funktionens signatur är:

PyObject *PyCFunction(PyObject *self,
                      PyObject *args);

type PyCFunctionWithKeywords

En del av Stabil ABI.

Typ av de funktioner som används för att implementera Python callables i C med signaturen METH_VARARGS | METH_KEYWORDS. Funktionssignaturen är:

PyObject *PyCFunctionWithKeywords(PyObject *self,
                                  PyObject *args,
                                  PyObject *kwargs);

type PyCFunctionFast

En del av Stabil ABI sedan version 3.13.

Typ av de funktioner som används för att implementera Python callables i C med signaturen METH_FASTCALL. Funktionens signatur är:

PyObject *PyCFunctionFast(PyObject *self,
                          PyObject *const *args,
                          Py_ssize_t nargs);

type PyCFunctionFastWithKeywords

En del av Stabil ABI sedan version 3.13.

Typ av de funktioner som används för att implementera Python callables i C med signaturen METH_FASTCALL | METH_KEYWORDS. Funktionssignaturen är:

PyObject *PyCFunctionFastWithKeywords(PyObject *self,
                                      PyObject *konst *args,
                                      Py_ssize_t nargs,
                                      PyObject *kwnamn);

type PyCMethod

Typ av de funktioner som används för att implementera Python callables i C med signaturen METH_METHOD | METH_FASTCALL | METH_KEYWORDS. Funktionssignaturen är:

PyObject *PyCMethod(PyObject *self,
                    PyTypeObject *definierande_klass,
                    PyObject *konst *args,
                    Py_ssize_t nargs,
                    PyObject *kwnamn)

Tillagd i version 3.9.

type PyMethodDef

En del av Stabil ABI (inklusive alla medlemmar).

Struktur som används för att beskriva en metod för en tilläggstyp. Denna struktur har fyra fält:

const char *ml_name

Namn på metoden.

PyCFunction ml_meth

Pekare till C-implementeringen.

int ml_flags

Flaggbitar som anger hur anropet ska konstrueras.

const char *ml_doc

Pekar på innehållet i dokumentsträngen.

ml_meth är en C-funktionspekare. Funktionerna kan vara av olika typer, men de returnerar alltid PyObject*. Om funktionen inte är av typen PyCFunction, kommer kompilatorn att kräva en cast i metodtabellen. Även om PyCFunction definierar den första parametern som PyObject*, är det vanligt att metodimplementeringen använder den specifika C-typen för self-objektet.

Fältet ml_flags är ett bitfält som kan innehålla följande flaggor. De enskilda flaggorna anger antingen en anropskonvention eller en bindningskonvention.

Det finns dessa samtalskonventioner:

METH_VARARGS

Detta är den typiska anropskonventionen, där metoderna har typen PyCFunction. Funktionen förväntar sig två PyObject*-värden. Det första är self-objektet för metoder; för modulfunktioner är det modulobjektet. Den andra parametern (ofta kallad args) är ett tuple-objekt som representerar alla argument. Den här parametern bearbetas vanligtvis med PyArg_ParseTuple() eller PyArg_UnpackTuple().

METH_KEYWORDS

Kan endast användas i vissa kombinationer med andra flaggor: METH_VARARGS | METH_KEYWORDS, METH_FASTCALL | METH_KEYWORDS och METH_METHOD | METH_FASTCALL | METH_KEYWORDS.

METH_VARARGS | METH_KEYWORDS

Metoder med dessa flaggor måste vara av typen PyCFunctionWithKeywords. Funktionen förväntar sig tre parametrar: self, args, kwargs där kwargs är en dictionary med alla nyckelordsargument eller eventuellt NULL om det inte finns några nyckelordsargument. Parametrarna bearbetas vanligtvis med PyArg_ParseTupleAndKeywords().

METH_FASTCALL

Snabb anropskonvention som endast stöder positionella argument. Metoderna har typen PyCFunctionFast. Den första parametern är self, den andra parametern är en C-array av PyObject*-värden som anger argumenten och den tredje parametern är antalet argument (längden på arrayen).

Tillagd i version 3.7.

Ändrad i version 3.10: METH_FASTCALL är nu en del av stable ABI.

METH_FASTCALL | METH_KEYWORDS

Utökning av METH_FASTCALL som även stöder nyckelordsargument, med metoder av typen PyCFunctionFastWithKeywords. Nyckelordsargument skickas på samma sätt som i vectorcall-protokollet: det finns en ytterligare fjärde PyObject*-parameter som är en tupel som representerar namnen på nyckelordsargumenten (som garanterat är strängar) eller eventuellt NULL om det inte finns några nyckelord. Värdena på nyckelordsargumenten lagras i args-arrayen, efter de positionella argumenten.

Tillagd i version 3.7.

METH_METHOD

Kan endast användas i kombination med andra flaggor: METH_METHOD | METH_FASTCALL | METH_KEYWORDS.

METH_METHOD | METH_FASTCALL | METH_KEYWORDS

Utökning av METH_FASTCALL | METH_KEYWORDS som stöder den definierande klassen, det vill säga den klass som innehåller metoden i fråga. Den definierande klassen kan vara en superklass av Py_TYPE(self).

Metoden måste vara av typen PyCMethod, på samma sätt som för METH_FASTCALL | METH_KEYWORDS med defining_class argumentet tillagt efter self.

Tillagd i version 3.9.

METH_NOARGS

Metoder utan parametrar behöver inte kontrollera om argument ges om de listas med flaggan METH_NOARGS. De måste vara av typen PyCFunction. Den första parametern har vanligtvis namnet self och innehåller en referens till modulen eller objektinstansen. I samtliga fall kommer den andra parametern att vara NULL.

Funktionen måste ha 2 parametrar. Eftersom den andra parametern är oanvänd kan Py_UNUSED användas för att förhindra en kompilatorvarning.

METH_O

Metoder med ett enda objektargument kan listas med flaggan METH_O, istället för att anropa PyArg_ParseTuple() med ett "O"-argument. De är av typen PyCFunction, med parametern self och en parameter av typen PyObject* som representerar det enda argumentet.

Dessa två konstanter används inte för att ange anropskonventionen utan bindningen när de används med metoder för klasser. De får inte användas för funktioner som definieras för moduler. Högst en av dessa flaggor får vara inställd för en viss metod.

METH_CLASS

Metoden kommer att få typobjektet som första parameter i stället för en instans av typen. Detta används för att skapa klassmetoder, liknande det som skapas när man använder den inbyggda funktionen classmethod().

METH_STATIC

Metoden får NULL som första parameter i stället för en instans av typen. Detta används för att skapa statiska metoder, liknande det som skapas när man använder den inbyggda funktionen staticmethod().

En annan konstant styr om en metod ska laddas i stället för en annan definition med samma metodnamn.

METH_COEXIST

Metoden kommer att laddas i stället för befintliga definitioner. Utan METH_COEXIST är standardinställningen att hoppa över upprepade definitioner. Eftersom slot-omslag laddas före metodtabellen, skulle till exempel förekomsten av en sq_contains slot generera en omslagsmetod med namnet __contains__() och förhindra laddning av en motsvarande PyCFunction med samma namn. Med flaggan definierad kommer PyCFunktionen att laddas i stället för omslutningsobjektet och kommer att samexistera med slotten. Detta är användbart eftersom anrop till PyCFunktioner optimeras mer än anrop till omslagsobjekt.

PyObject *PyCMethod_New(PyMethodDef *ml, PyObject *self, PyObject *module, PyTypeObject *cls)

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

Gör ml till ett Python callable-objekt. Den som anropar måste se till att ml överlever callable. Vanligtvis är ml definierad som en statisk variabel.

Parametern self kommer att skickas som argumentet self till C-funktionen i ml->ml_meth när den anropas. self kan vara NULL.

Attributet __module__ för objektet callable kan ställas in från det givna argumentet module. module bör vara en Python-sträng, som kommer att användas som namn på den modul som funktionen definieras i. Om den inte är tillgänglig kan den sättas till None eller NULL.

Se även

funktion.__modul__

Parametern cls kommer att skickas som argumentet defining_class till C-funktionen. Måste sättas om METH_METHOD är satt på ml->ml_flags.

Tillagd i version 3.9.

PyObject *PyCFunction_NewEx(PyMethodDef *ml, PyObject *self, PyObject *module)

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

Motsvarar PyCMethod_New(ml, self, module, NULL).

PyObject *PyCFunction_New(PyMethodDef *ml, PyObject *self)

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

Motsvarar PyCMethod_New(ml, self, NULL, NULL).

Tillgång till attribut för tilläggstyper

type PyMemberDef

En del av Stabil ABI (inklusive alla medlemmar).

Struktur som beskriver ett attribut av en typ som motsvarar en C struct-medlem. När du definierar en klass lägger du in en NULL-terminerad array av dessa strukturer i tp_members slot.

Dess fält är i tur och ordning:

const char *name

Namnet på medlemmen. Ett NULL-värde markerar slutet på en PyMemberDef[]-array.

Strängen ska vara statisk, ingen kopia görs av den.

int type

Typen av medlemmen i C-strukturen. Se Typer av medlemmar för de möjliga värdena.

Py_ssize_t offset

Den offset i bytes som medlemmen befinner sig på i typens objektstruktur.

int flags

Noll eller flera av Flaggor för medlemmar, kombinerade med bitvis OR.

const char *doc

Dokumentsträngen, eller NULL. Strängen ska vara statisk, ingen kopia görs av den. Vanligtvis definieras den med hjälp av PyDoc_STR.

Som standard (när flags är 0) tillåter medlemmar både läs- och skrivåtkomst. Använd flaggan Py_READONLY för skrivskyddad åtkomst. Vissa typer, som Py_T_STRING, innebär Py_READONLY. Endast Py_T_OBJECT_EX (och äldre T_OBJECT) medlemmar kan tas bort.

För heap-allokerade typer (skapade med PyType_FromSpec() eller liknande) kan PyMemberDef innehålla en definition för den speciella medlemmen "__vectorcalloffset__", motsvarande tp_vectorcall_offset i typobjekt. Denna medlem måste definieras med Py_T_PYSSIZET, och antingen Py_READONLY eller Py_READONLY | Py_RELATIVE_OFFSET. Till exempel:

static PyMemberDef spam_type_members[] = {
    {"__vectorcalloffset__", Py_T_PYSSIZET,
     offsetof(Spam_object, vectorcall), Py_READONLY},
    {NULL}  /* Sentinel */
};

(Du kan behöva #include <stddef.h> för offsetof().)

De äldre offseten tp_dictoffset och tp_weaklistoffset kan definieras på liknande sätt med hjälp av medlemmarna "__dictoffset__" och "__weaklistoffset__", men tillägg uppmuntras starkt att använda Py_TPFLAGS_MANAGED_DICT och Py_TPFLAGS_MANAGED_WEAKREF istället.

Ändrad i version 3.12: PyMemberDef är alltid tillgänglig. Tidigare krävdes det att man inkluderade "structmember.h".

Ändrad i version 3.14: Py_RELATIVE_OFFSET är nu tillåtet för "__vectorcalloffset__", "__dictoffset__" och "__weaklistoffset__".

PyObject *PyMember_GetOne(const char *obj_addr, struct PyMemberDef *m)

En del av Stabil ABI.

Hämtar ett attribut som tillhör objektet på adressen obj_addr. Attributet beskrivs av PyMemberDef m. Returnerar NULL vid fel.

Ändrad i version 3.12: PyMember_GetOne är alltid tillgänglig. Tidigare krävdes det att man inkluderade "structmember.h".

int PyMember_SetOne(char *obj_addr, struct PyMemberDef *m, PyObject *o)

En del av Stabil ABI.

Ställ in ett attribut som tillhör objektet på adressen obj_addr till objektet o. Attributet som ska ställas in beskrivs av PyMemberDef m. Returnerar 0 om det lyckas och ett negativt värde om det misslyckas.

Ändrad i version 3.12: PyMember_SetOne är alltid tillgänglig. Tidigare krävdes det att man inkluderade "structmember.h".

Flaggor för medlemmar

Följande flaggor kan användas med PyMemberDef.flags:

Py_READONLY

Ej skrivbar.

Py_AUDIT_READ

Skicka en object.__getattr__ audit event före läsning.

Py_RELATIVE_OFFSET

Indikerar att offset i denna PyMemberDef -post anger en förskjutning från den underklassspecifika datan, snarare än från PyObject.

Kan endast användas som en del av Py_tp_members slot när man skapar en klass med negativ basicsize. Det är obligatoriskt i det fallet.

Denna flagga används endast i PyType_Slot. När du ställer in tp_members under skapandet av klassen, rensar Python den och ställer in PyMemberDef.offset till offset från PyObject-strukturen.

Ändrad i version 3.10: Makron RESTRICTED, READ_RESTRICTED och WRITE_RESTRICTED som är tillgängliga med #include "structmember.h" är föråldrade. READ_RESTRICTED och RESTRICTED är likvärdiga med Py_AUDIT_READ; WRITE_RESTRICTED gör ingenting.

Ändrad i version 3.12: Makrot READONLY döptes om till Py_READONLY. Makrot PY_AUDIT_READ döptes om med prefixet Py_. De nya namnen är nu alltid tillgängliga. Tidigare krävde dessa #include "structmember.h". Headern är fortfarande tillgänglig och den innehåller de gamla namnen.

Typer av medlemmar

PyMemberDef.type kan vara ett av följande makron som motsvarar olika C-typer. När medlemmen används i Python konverteras den till motsvarande Python-typ. När den sätts från Python konverteras den tillbaka till C-typen. Om det inte är möjligt, kommer ett undantag som TypeError eller ValueError att uppstå.

Om inte markerat (D), kan attribut som definieras på detta sätt inte raderas med t.ex. del eller delattr().

Namn på makro	C-typ	Python-typ
Py_T_BYTE	char	int
Py_T_SHORT	short	int
Py_T_INT	int	int
Py_T_LONG	long	int
Py_T_LONGLONG	long long	int
Py_T_UBYTE	unsigned char	int
Py_T_UINT	unsigned int	int
Py_T_USHORT	unsigned short	int
Py_T_ULONG	unsigned long	int
Py_T_ULONGLONG	unsigned long long	int
Py_T_PYSSIZET	Py_ssize_t	int
Py_T_FLOAT	float	float
Py_T_DOUBLE	double	float
Py_T_BOOL	char (skrivs som 0 eller 1)	bool
Py_T_STRING	const char* (*)	str (RO)
Py_T_STRING_INPLACE	const char[] (*)	str (RO)
Py_T_CHAR	char (0-127)	str (**)
Py_T_OBJECT_EX	PyObject*	object (D)

(*): Nollavslutad, UTF8-kodad C-sträng. Med Py_T_STRING är C-representationen en pekare; med Py_T_STRING_INPLACE lagras strängen direkt i strukturen.

(**): Sträng med längden 1. Endast ASCII accepteras.

(RO): Innebär Py_READONLY.

(D): Kan raderas, i vilket fall pekaren sätts till NULL. Att läsa en NULL pekare ger upphov till AttributeError.

Tillagd i version 3.12: I tidigare versioner var makron endast tillgängliga med #include "structmember.h" och namngavs utan prefixet Py_ (t.ex. som T_INT). Headern är fortfarande tillgänglig och innehåller de gamla namnen, tillsammans med följande föråldrade typer:

T_OBJECT

Som Py_T_OBJECT_EX, men NULL konverteras till None. Detta resulterar i ett överraskande beteende i Python: att ta bort attributet sätter det effektivt till None.

T_NONE

Alltid None. Måste användas med Py_READONLY.

Definiera Getters och Setters

type PyGetSetDef

En del av Stabil ABI (inklusive alla medlemmar).

Struktur för att definiera egendomsliknande åtkomst för en typ. Se även beskrivning av PyTypeObject.tp_getset slot.

const char *name

attributets namn

getter get

C-funktion för att få fram attributet.

setter set

Valfri C-funktion för att ställa in eller ta bort attributet. Om NULL, är attributet skrivskyddat.

const char *doc

valfri dokumentsträng

void *closure

Valfri användardatapekare som tillhandahåller ytterligare data för getter och setter.

typedef PyObject *(*getter)(PyObject*, void*)

En del av Stabil ABI.

Funktionen get tar en PyObject*-parameter (instansen) och en användardatapekare (den tillhörande closure):

Den ska returnera en ny referens om den lyckas eller NULL med ett definierat undantag om den misslyckas.

typedef int (*setter)(PyObject*, PyObject*, void*)

En del av Stabil ABI.

set funktioner tar två PyObject* parametrar (instansen och värdet som ska ställas in) och en användardatapekare (den tillhörande closure):

Om attributet ska tas bort är den andra parametern NULL. Bör returnera 0 vid framgång eller -1 med ett angivet undantag vid misslyckande.