Modulobjekt

PyTypeObject PyModule_Type

En del av Stabil ABI.

Denna instans av PyTypeObject representerar Pythons modultyp. Detta exponeras för Python-program som types.ModuleType.

int PyModule_Check(PyObject *p)

Returnerar true om p är ett modulobjekt eller en subtyp av ett modulobjekt. Denna funktion lyckas alltid.

int PyModule_CheckExact(PyObject *p)

Returnerar true om p är ett modulobjekt, men inte en subtyp av PyModule_Type. Denna funktion lyckas alltid.

PyObject *PyModule_NewObject(PyObject *name)

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

Returnerar ett nytt modulobjekt med module.__name__ satt till name. Modulens attribut __name__, __doc__, __package__ och __loader__ fylls i (alla utom __name__ sätts till None). Den som anropar är ansvarig för att ange attributet __file__.

Returnerar NULL med ett undantag inställt på fel.

Tillagd i version 3.3.

Ändrad i version 3.4: __package__ och __loader__ är nu inställda på None.

PyObject *PyModule_New(const char *name)

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

Liknar PyModule_NewObject(), men namnet är en UTF-8-kodad sträng i stället för ett Unicode-objekt.

PyObject *PyModule_GetDict(PyObject *module)

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

Returnerar det ordboksobjekt som implementerar modul:s namnrymd; detta objekt är detsamma som __dict__-attributet för modulobjektet. Om module inte är ett modulobjekt (eller en subtyp av ett modulobjekt), avges SystemError och NULL returneras.

Det rekommenderas att använda andra PyModule_* och PyObject_* funktioner snarare än att direkt manipulera en moduls __dict__.

PyObject *PyModule_GetNameObject(PyObject *module)

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

Returnerar modul:s __name__-värde. Om modulen inte tillhandahåller något värde eller om det inte är en sträng, SystemError och NULL returneras.

Tillagd i version 3.3.

const char *PyModule_GetName(PyObject *module)

En del av Stabil ABI.

Liknar PyModule_GetNameObject() men returnerar namnet kodat till 'utf-8'.

void *PyModule_GetState(PyObject *module)

En del av Stabil ABI.

Returnerar modulens ”tillstånd”, det vill säga en pekare till det minnesblock som allokerades när modulen skapades, eller NULL. Se PyModuleDef.m_size.

PyModuleDef *PyModule_GetDef(PyObject *module)

En del av Stabil ABI.

Returnerar en pekare till PyModuleDef-strukturen från vilken modulen skapades, eller NULL om modulen inte skapades från en definition.

PyObject *PyModule_GetFilenameObject(PyObject *module)

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

Returnerar namnet på den fil som modul laddades från med hjälp av moduls attribut __file__. Om detta inte är definierat, eller om det inte är en sträng, uppstår SystemError och NULL returneras; annars returneras en referens till ett Unicode-objekt.

Tillagd i version 3.2.

const char *PyModule_GetFilename(PyObject *module)

En del av Stabil ABI.

Liknar PyModule_GetFilenameObject() men returnerar filnamnet kodat till ’utf-8’.

Föråldrad sedan version 3.2: PyModule_GetFilename() ger upphov till UnicodeEncodeError på okodbara filnamn, använd PyModule_GetFilenameObject() istället.

Definitioner av moduler

Funktionerna i föregående avsnitt fungerar på alla modulobjekt, inklusive moduler som importeras från Python-kod.

Moduler som definieras med hjälp av C API använder vanligtvis en moduldefinition, PyModuleDef – en statiskt allokerad, konstant ”beskrivning” av hur en modul ska skapas.

Definitionen används vanligtvis för att definiera ett tilläggs ”huvud”-modulobjekt (se Definiera tilläggsmoduler för detaljer). Den används också för att skapa tilläggsmoduler dynamiskt.

Till skillnad från PyModule_New() tillåter definitionen hantering av modultillstånd – en del av minnet som allokeras och rensas tillsammans med modulobjektet. Till skillnad från modulens Python-attribut kan Python-kod inte ersätta eller ta bort data som lagras i modulens tillstånd.

type PyModuleDef

En del av Stabil ABI (inklusive alla medlemmar).

Moduldefinitionsstrukturen, som innehåller all information som behövs för att skapa ett modulobjekt. Denna struktur måste vara statiskt allokerad (eller på annat sätt garanteras vara giltig så länge moduler som skapats från den existerar). Vanligtvis finns det bara en variabel av denna typ för varje tilläggsmodul.

PyModuleDef_Base m_base

Initialisera alltid denna medlem till PyModuleDef_HEAD_INIT.

const char *m_name

Namn för den nya modulen.

const char *m_doc

Docstring för modulen; vanligtvis används en docstring-variabel som skapats med PyDoc_STRVAR.

Py_ssize_t m_size

Modulstatus kan förvaras i ett minnesområde per modul som kan hämtas med PyModule_GetState(), i stället för i statiska globaler. Detta gör moduler säkra för användning i flera undertolkare.

Detta minnesområde allokeras baserat på m_size när modulen skapas och frigörs när modulobjektet avallokeras, efter att funktionen m_free har anropats, om den finns.

Om du anger ett icke-negativt värde innebär det att modulen kan initieras på nytt och anger den extra mängd minne som krävs för dess tillstånd.

Om m_size sätts till -1 innebär det att modulen inte stöder undertolkare, eftersom den har ett globalt tillstånd. Negativa m_size är endast tillåtet när man använder legacy single-phase initialization eller när man creating modules dynamically.

Se PEP 3121 för mer information.

PyMethodDef *m_methods

En pekare till en tabell med funktioner på modulnivå, beskrivna av PyMethodDef-värden. Kan vara NULL om inga funktioner finns.

PyModuleDef_Slot *m_slots

En rad slotdefinitioner för flerfasinitialisering, avslutad med en {0, NULL} -post. Vid användning av äldre enfasinitialisering måste m_slots vara NULL.

Ändrad i version 3.5: Före version 3.5 var denna medlem alltid inställd på NULL, och definierades som:

inquiry m_reload

traverseproc m_traverse

En traversalfunktion som ska anropas under GC-traversal av modulobjektet, eller NULL om den inte behövs.

Denna funktion anropas inte om modultillståndet begärdes men ännu inte har allokerats. Detta är fallet omedelbart efter att modulen skapats och innan modulen exekveras (Py_mod_exec funktion). Mer exakt anropas inte denna funktion om m_size är större än 0 och modultillståndet (som returneras av PyModule_GetState()) är NULL.

Ändrad i version 3.9: Anropas inte längre innan modultillståndet har allokerats.

inquiry m_clear

En clear-funktion som ska anropas vid GC-rensning av modulobjektet, eller NULL om den inte behövs.

Denna funktion anropas inte om modultillståndet begärdes men ännu inte har allokerats. Detta är fallet omedelbart efter att modulen skapats och innan modulen exekveras (Py_mod_exec funktion). Mer exakt anropas inte denna funktion om m_size är större än 0 och modultillståndet (som returneras av PyModule_GetState()) är NULL.

Precis som PyTypeObject.tp_clear anropas inte den här funktionen alltid innan en modul avallokeras. Till exempel, när referensräkning är tillräckligt för att avgöra att ett objekt inte längre används, är den cykliska skräpsamlaren inte inblandad och m_free anropas direkt.

Ändrad i version 3.9: Anropas inte längre innan modultillståndet har allokerats.

freefunc m_free

En funktion som ska anropas vid avallokering av modulobjektet, eller NULL om den inte behövs.

Denna funktion anropas inte om modultillståndet begärdes men ännu inte har allokerats. Detta är fallet omedelbart efter att modulen skapats och innan modulen exekveras (Py_mod_exec funktion). Mer exakt anropas inte denna funktion om m_size är större än 0 och modultillståndet (som returneras av PyModule_GetState()) är NULL.

Ändrad i version 3.9: Anropas inte längre innan modultillståndet har allokerats.

Modulplatser

type PyModuleDef_Slot

int slot

Ett slot-ID, som väljs bland de tillgängliga värden som beskrivs nedan.

void *value

Värde för slot, vars betydelse beror på slot-ID.

Tillagd i version 3.5.

De tillgängliga slot-typerna är:

Py_mod_create

Anger en funktion som anropas för att skapa själva modulobjektet. Poängaren value i denna slot måste peka på en funktion med samma signatur:

PyObject *create_module(PyObject *spec, PyModuleDef *def)

Funktionen tar emot en instans av ModuleSpec, enligt definitionen i PEP 451, och moduldefinitionen. Den bör returnera ett nytt modulobjekt, eller ange ett fel och returnera NULL.

Denna funktion bör hållas minimal. I synnerhet bör den inte anropa godtycklig Python-kod, eftersom försök att importera samma modul igen kan resultera i en oändlig loop.

Flera Py_mod_create-platser får inte anges i en moduldefinition.

Om Py_mod_create inte anges kommer importmaskineriet att skapa ett normalt modulobjekt med hjälp av PyModule_New(). Namnet är taget från spec, inte definitionen, för att göra det möjligt för tilläggsmoduler att dynamiskt anpassa sig till sin plats i modulhierarkin och importeras under olika namn genom symlinks, samtidigt som de delar en enda moduldefinition.

Det finns inget krav på att det returnerade objektet ska vara en instans av PyModule_Type. Vilken typ som helst kan användas, så länge den stöder inställning och hämtning av importrelaterade attribut. Dock kan endast PyModule_Type instanser returneras om PyModuleDef har icke-NULL m_traverse, m_clear, m_free; icke- noll m_size; eller andra slots än Py_mod_create.

Py_mod_exec

Specificerar en funktion som anropas för att exekvera modulen. Detta motsvarar att exekvera koden i en Python-modul: vanligtvis lägger denna funktion till klasser och konstanter i modulen. Funktionens signatur är:

int exec_module(PyObject *module)

Om flera Py_mod_exec-slots anges, behandlas de i den ordning de visas i m_slots-arrayen.

Py_mod_multiple_interpreters

Anger ett av följande värden:

Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED

Modulen stöder inte import i undertolkar.

Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED

Modulen kan importeras i undertolkar, men endast om de delar huvudtolkens GIL. (Se Isolering av tilläggsmoduler.)

Py_MOD_PER_INTERPRETER_GIL_SUPPORTED

Modulen stöder import i undertolkare, även när de har sin egen GIL. (Se Isolering av tilläggsmoduler.)

Denna plats avgör om import av denna modul i en subinterpreter kommer att misslyckas eller inte.

Flera Py_mod_multiple_interpreters-platser får inte anges i en moduldefinition.

Om Py_mod_multiple_interpreters inte anges, är standardvärdet för importmaskineriet Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED.

Tillagd i version 3.12.

Py_mod_gil

Anger ett av följande värden:

Py_MOD_GIL_USED

Modulen är beroende av att det globala tolklåset (GIL) finns och kan komma åt globala tillstånd utan synkronisering.

Py_MOD_GIL_NOT_USED

Modulen är säker att köra utan en aktiv GIL.

Denna slot ignoreras av Python-byggnader som inte konfigurerats med --disable-gil. Annars avgör den om import av denna modul kommer att orsaka att GIL aktiveras automatiskt. Se Fri trådad CPython för mer detaljer.

Flera Py_mod_gil-platser får inte anges i en moduldefinition.

Om Py_mod_gil inte anges, är standardvärdet för importmaskineriet Py_MOD_GIL_USED.

Tillagd i version 3.13.

Dynamiskt skapande av tilläggsmoduler

Följande funktioner kan användas för att skapa en modul utanför ett tilläggs initialiseringsfunktion. De används också i initialisering i en fas.

PyObject *PyModule_Create(PyModuleDef *def)

Returnera värde: Ny referens.

Skapa ett nytt modulobjekt, givet definitionen i def. Detta är ett makro som anropar PyModule_Create2() med module_api_version satt till PYTHON_API_VERSION, eller till PYTHON_ABI_VERSION om du använder limited API.

PyObject *PyModule_Create2(PyModuleDef *def, int module_api_version)

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

Skapa ett nytt modulobjekt med definitionen i def och API-versionen module_api_version. Om den versionen inte stämmer överens med versionen i den tolk som körs, skickas en RuntimeWarning ut.

Returnerar NULL med ett undantag inställt på fel.

Denna funktion stöder inte slots. Medlemmen m_slots i def måste vara NULL.

Anteckning

De flesta användningar av denna funktion bör använda PyModule_Create() istället; använd endast denna om du är säker på att du behöver den.

PyObject *PyModule_FromDefAndSpec(PyModuleDef *def, PyObject *spec)

Returnera värde: Ny referens.

Detta makro anropar PyModule_FromDefAndSpec2() med module_api_version satt till PYTHON_API_VERSION, eller till PYTHON_ABI_VERSION om man använder limited API.

Tillagd i version 3.5.

PyObject *PyModule_FromDefAndSpec2(PyModuleDef *def, PyObject *spec, int module_api_version)

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

Skapar ett nytt modulobjekt, givet definitionen i def och ModuleSpec spec, med API-versionen module_api_version. Om den versionen inte stämmer överens med versionen i den tolk som körs, skickas en RuntimeWarning ut.

Returnerar NULL med ett undantag inställt på fel.

Observera att detta inte behandlar exekveringsplatser (Py_mod_exec). Både PyModule_FromDefAndSpec och PyModule_ExecDef måste anropas för att initiera en modul fullständigt.

Anteckning

De flesta användningar av denna funktion bör använda PyModule_FromDefAndSpec() istället; använd endast denna om du är säker på att du behöver den.

Tillagd i version 3.5.

int PyModule_ExecDef(PyObject *module, PyModuleDef *def)

En del av Stabil ABI sedan version 3.7.

Behandla alla exekveringsplatser (Py_mod_exec) som anges i def.

Tillagd i version 3.5.

PYTHON_API_VERSION

C API-versionen. Definierad för bakåtkompatibilitet.

För närvarande uppdateras inte denna konstant i nya Python-versioner och är inte användbar för versionshantering. Detta kan komma att ändras i framtiden.

PYTHON_ABI_VERSION

Definierad som 3 för bakåtkompatibilitet.

För närvarande uppdateras inte denna konstant i nya Python-versioner och är inte användbar för versionshantering. Detta kan komma att ändras i framtiden.

Stödfunktioner

Följande funktioner finns för att initiera en moduls tillstånd. De är avsedda för en moduls exekveringsplatser (Py_mod_exec), initialiseringsfunktionen för äldre single-phase initialization, eller kod som skapar moduler dynamiskt.

int PyModule_AddObjectRef(PyObject *module, const char *name, PyObject *value)

En del av Stabil ABI sedan version 3.10.

Lägg till ett objekt till modul som namn. Detta är en bekvämlighetsfunktion som kan användas från modulens initialiseringsfunktion.

Vid framgång, returnera 0. Vid fel, skapa ett undantag och returnera -1.

Exempel på användning:

static int
add_spam(PyObject *module, int value)
{
    PyObject *obj = PyLong_FromLong(value);
    if (obj == NULL) {
        return -1;
    }
    int res = PyModule_AddObjectRef(module, "spam", obj);
    Py_DECREF(obj);
    return res;
 }

För att vara bekväm accepterar funktionen NULL värde med ett undantag. I detta fall returneras -1 och det undantag som skapats lämnas oförändrat.

Exemplet kan också skrivas utan att uttryckligen kontrollera om obj är NULL:

static int
add_spam(PyObject *module, int value)
{
    PyObject *obj = PyLong_FromLong(value);
    int res = PyModule_AddObjectRef(module, "spam", obj);
    Py_XDECREF(obj);
    return res;
 }

Observera att Py_XDECREF() bör användas i stället för Py_DECREF() i detta fall, eftersom obj kan vara NULL.

Antalet olika name-strängar som skickas till denna funktion bör hållas litet, vanligtvis genom att endast använda statiskt allokerade strängar som name. För namn som inte är kända vid kompileringstillfället är det bättre att anropa PyUnicode_FromString() och PyObject_SetAttr() direkt. För mer detaljer, se PyUnicode_InternFromString(), som kan användas internt för att skapa ett nyckelobjekt.

Tillagd i version 3.10.

int PyModule_Add(PyObject *module, const char *name, PyObject *value)

En del av Stabil ABI sedan version 3.13.

Liknar PyModule_AddObjectRef(), men ”stjäl” en referens till värde. Den kan anropas med ett resultat av en funktion som returnerar en ny referens utan att bry sig om att kontrollera resultatet eller ens spara det i en variabel.

Exempel på användning:

if (PyModule_Add(module, "spam", PyBytes_FromString(value)) < 0) {
    gå till fel;
}

Tillagd i version 3.13.

int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)

En del av Stabil ABI.

Liknar PyModule_AddObjectRef(), men stjäl en referens till värde vid framgång (om den returnerar 0).

De nya funktionerna PyModule_Add() eller PyModule_AddObjectRef() rekommenderas, eftersom det är lätt att införa referensläckor genom att missbruka funktionen PyModule_AddObject().

Anteckning

Till skillnad från andra funktioner som stjäl referenser, släpper PyModule_AddObject() bara referensen till värde vid framgång.

Detta innebär att dess returvärde måste kontrolleras, och anropande kod måste Py_XDECREF() värde manuellt vid fel.

Exempel på användning:

PyObject *obj = PyBytes_FromString(value);
if (PyModule_AddObject(module, "spam", obj) < 0) {
    // If 'obj' is not NULL and PyModule_AddObject() failed,
    // 'obj' strong reference must be deleted with Py_XDECREF().
    // If 'obj' is NULL, Py_XDECREF() does nothing.
    Py_XDECREF(obj);
    goto error;
}
// PyModule_AddObject() stole a reference to obj:
// Py_XDECREF(obj) is not needed here.

Föråldrad sedan version 3.13: PyModule_AddObject() är soft deprecated.

int PyModule_AddIntConstant(PyObject *module, const char *name, long value)

En del av Stabil ABI.

Lägg till en heltalskonstant till modul som namn. Denna bekvämlighetsfunktion kan användas från modulens initialiseringsfunktion. Returnerar -1 med ett undantag inställt vid fel, 0 vid framgång.

Detta är en bekvämlighetsfunktion som anropar PyLong_FromLong() och PyModule_AddObjectRef(); se deras dokumentation för detaljer.

int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value)

En del av Stabil ABI.

Lägg till en strängkonstant till modul som namn. Denna bekvämlighetsfunktion kan användas från modulens initialiseringsfunktion. Strängen värde måste vara NULL-terminerad. Returnerar -1 med en undantagsuppsättning vid fel, 0 vid framgång.

Detta är en bekvämlighetsfunktion som anropar PyUnicode_InternFromString() och PyModule_AddObjectRef(); se deras dokumentation för detaljer.

PyModule_AddIntMacro(module, macro)

Lägg till en int-konstant i modul. Namnet och värdet hämtas från macro. Till exempel PyModule_AddIntMacro(module, AF_INET) lägger till int-konstanten AF_INET med värdet AF_INET till modul. Returnerar -1 med en undantagsuppsättning vid fel, 0 vid framgång.

PyModule_AddStringMacro(module, macro)

Lägg till en strängkonstant i modul.

int PyModule_AddType(PyObject *module, PyTypeObject *type)

En del av Stabil ABI sedan version 3.10.

Lägg till ett typobjekt till modul. Typobjektet färdigställs genom att internt anropa PyType_Ready(). Namnet på typobjektet hämtas från den sista komponenten i tp_name efter punkt. Returnerar -1 med en exception set vid fel, 0 vid framgång.

Tillagd i version 3.9.

int PyModule_AddFunctions(PyObject *module, PyMethodDef *functions)

En del av Stabil ABI sedan version 3.7.

Lägg till funktionerna från den NULL avslutade functions-arrayen till module. Se PyMethodDef-dokumentationen för detaljer om enskilda poster (på grund av avsaknaden av ett delat modulnamnrum får ”funktioner” på modulnivå som implementeras i C vanligtvis modulen som sin första parameter, vilket gör att de liknar instansmetoder i Python-klasser).

Denna funktion anropas automatiskt när en modul skapas från PyModuleDef (t.ex. när Initialisering i flera faser, PyModule_Create eller PyModule_FromDefAndSpec används). Vissa modulförfattare kanske föredrar att definiera funktioner i flera PyMethodDef-arrayer; i så fall bör de anropa denna funktion direkt.

Tillagd i version 3.5.

int PyModule_SetDocString(PyObject *module, const char *docstring)

En del av Stabil ABI sedan version 3.7.

Ställ in docstring för modul till docstring. Denna funktion anropas automatiskt när du skapar en modul från PyModuleDef (t.ex. när du använder Initialisering i flera faser, PyModule_Create, eller PyModule_FromDefAndSpec).

Tillagd i version 3.5.

int PyUnstable_Module_SetGIL(PyObject *module, void *gil)

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

Ange att modul stöder eller inte stöder körning utan det globala tolklåset (GIL), med hjälp av ett av värdena från Py_mod_gil. Den måste anropas under modul:s initialiseringsfunktion när Legacy enfasig initialisering används. Om denna funktion inte anropas under modulinitialiseringen, antar importmaskineriet att modulen inte stöder körning utan GIL. Denna funktion är endast tillgänglig i Python-byggnader som konfigurerats med --disable-gil. Returnerar -1 med en undantagsuppsättning vid fel, 0 vid framgång.

Tillagd i version 3.13.

Moduluppslagning (enfasig initialisering)

Det äldre initialiseringsschemat single-phase initialization skapar singleton-moduler som kan sökas upp i den aktuella tolkens kontext. Detta gör att modulobjektet kan hämtas senare med endast en referens till moduldefinitionen.

Dessa funktioner fungerar inte på moduler som skapats med hjälp av flerfasinitialisering, eftersom flera sådana moduler kan skapas från en enda definition.

PyObject *PyState_FindModule(PyModuleDef *def)

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

Returnerar det modulobjekt som skapades från def för den aktuella tolken. Denna metod kräver att modulobjektet har kopplats till tolktillståndet med PyState_AddModule() i förväg. Om motsvarande modulobjekt inte hittas eller inte har kopplats till tolktillståndet ännu, returnerar den NULL.

int PyState_AddModule(PyObject *module, PyModuleDef *def)

En del av Stabil ABI sedan version 3.3.

Kopplar modulobjektet som skickas till funktionen till tolkens tillstånd. Detta gör att modulobjektet kan nås via PyState_FindModule().

Gäller endast för moduler som skapats med enfasinitialisering.

Python anropar automatiskt PyState_AddModule efter att ha importerat en modul som använder enfasinitialisering, så det är onödigt (men ofarligt) att anropa den från modulens initialiseringskod. Ett explicit anrop behövs endast om modulens egen init-kod därefter anropar PyState_FindModule. Funktionen är huvudsakligen avsedd för att implementera alternativa importmekanismer (antingen genom att anropa den direkt eller genom att hänvisa till dess implementering för detaljer om nödvändiga tillståndsuppdateringar).

Om en modul har bifogats tidigare med samma def, ersätts den av den nya modulen.

Den som anropar måste ha en attached thread state.

Returnerar -1 med en exception set vid fel, 0 vid framgång.

Tillagd i version 3.3.

int PyState_RemoveModule(PyModuleDef *def)

En del av Stabil ABI sedan version 3.3.

Tar bort modulobjektet som skapats från def från tolkens tillstånd. Returnerar -1 med en undantagsuppsättning vid fel, 0 vid framgång.

Den som anropar måste ha en attached thread state.

Tillagd i version 3.3.