Kodobjekt

Kodobjekt är en detalj på låg nivå i CPython-implementeringen. Var och en representerar en bit körbar kod som ännu inte har bundits till en funktion.

type PyCodeObject

C-strukturen för de objekt som används för att beskriva kodobjekt. Fälten av denna typ kan ändras när som helst.

PyTypeObject PyCode_Type

Detta är en instans av PyTypeObject som representerar Python code object.

int PyCode_Check(PyObject *co)

Returnerar true om co är ett kodobjekt. Denna funktion lyckas alltid.

Py_ssize_t PyCode_GetNumFree(PyCodeObject *co)

Returnera antalet fria (stängda) variabler i ett kodobjekt.

int PyUnstable_Code_GetFirstFree(PyCodeObject *co)

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

Returnerar positionen för den första fria (stängda) variabeln i ett kodobjekt.

Ändrad i version 3.13: Bytt namn från PyCode_GetFirstFree som en del av Instabilt C API. Det gamla namnet är föråldrat, men kommer att finnas kvar tills signaturen ändras igen.

PyCodeObject *PyUnstable_Code_New(int argcount, int kwonlyargcount, int nlocals, int stacksize, int flags, PyObject *code, PyObject *consts, PyObject *names, PyObject *varnames, PyObject *freevars, PyObject *cellvars, PyObject *filename, PyObject *name, PyObject *qualname, int firstlineno, PyObject *linetable, PyObject *exceptiontable)

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

Returnerar ett nytt kodobjekt. Om du behöver ett dummy-kodobjekt för att skapa en ram, använd PyCode_NewEmpty() istället.

Eftersom definitionen av bytekoden ändras ofta kan ett direkt anrop av PyUnstable_Code_New() binda dig till en exakt Python-version.

De många argumenten i denna funktion är beroende av varandra på ett komplext sätt, vilket innebär att små förändringar av värdena sannolikt leder till felaktigt utförande eller VM-krascher. Använd denna funktion endast med yttersta försiktighet.

Ändrad i version 3.11: Lagt till parametrarna qualname och exceptiontable.

Ändrad i version 3.12: Bytt namn från PyCode_New som en del av Instabilt C API. Det gamla namnet är föråldrat, men kommer att finnas kvar tills signaturen ändras igen.

PyCodeObject *PyUnstable_Code_NewWithPosOnlyArgs(int argcount, int posonlyargcount, int kwonlyargcount, int nlocals, int stacksize, int flags, PyObject *code, PyObject *consts, PyObject *names, PyObject *varnames, PyObject *freevars, PyObject *cellvars, PyObject *filename, PyObject *name, PyObject *qualname, int firstlineno, PyObject *linetable, PyObject *exceptiontable)

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

Liknar PyUnstable_Code_New(), men med ett extra ”posonlyargcount” för enbart positionella argument. Samma varningar som gäller för PyUnstable_Code_New gäller också för denna funktion.

Tillagd i version 3.8: som PyCode_NewWithPosOnlyArgs

Ändrad i version 3.11: Lagt till parametrarna qualname och exceptiontable.

Ändrad i version 3.12: Bytt namn till PyUnstable_Code_NewWithPosOnlyArgs. Det gamla namnet är föråldrat, men kommer att finnas kvar tills signaturen ändras igen.

PyCodeObject *PyCode_NewEmpty(const char *filename, const char *funcname, int firstlineno)

Returnera värde: Ny referens.

Returnerar ett nytt tomt kodobjekt med angivet filnamn, funktionsnamn och första radnummer. Det resulterande kodobjektet kommer att ge upphov till ett Exception om det körs.

int PyCode_Addr2Line(PyCodeObject *co, int byte_offset)

Returnerar radnumret för den instruktion som börjar på eller före byte_offset och slutar efter den. Om du bara behöver radnumret för en frame, använd PyFrame_GetLineNumber() istället.

För effektiv iterering över radnumren i ett kodobjekt, använd det API som beskrivs i PEP 626.

int PyCode_Addr2Location(PyObject *co, int byte_offset, int *start_line, int *start_column, int *end_line, int *end_column)

Ställer in de överlämnade int-pekarna till källkodens rad- och kolumnnummer för instruktionen vid byte_offset. Sätter värdet till 0 när information inte är tillgänglig för något särskilt element.

Returnerar 1 om funktionen lyckas och 0 annars.

Tillagd i version 3.11.

PyObject *PyCode_GetCode(PyCodeObject *co)

Motsvarar Python-koden getattr(co, 'co_code'). Returnerar en stark referens till ett PyBytesObject som representerar bytekoden i ett kodobjekt. Vid fel returneras NULL och ett undantag tas upp.

Detta PyBytesObject kan skapas på begäran av tolken och representerar inte nödvändigtvis den bytekod som faktiskt exekveras av CPython. Det primära användningsområdet för denna funktion är debuggers och profilerare.

Tillagd i version 3.11.

PyObject *PyCode_GetVarnames(PyCodeObject *co)

Motsvarar Python-koden getattr(co, 'co_varnames'). Returnerar en ny referens till ett PyTupleObject som innehåller namnen på de lokala variablerna. Vid fel returneras NULL och ett undantag tas upp.

Tillagd i version 3.11.

PyObject *PyCode_GetCellvars(PyCodeObject *co)

Motsvarar Python-koden getattr(co, 'co_cellvars'). Returnerar en ny referens till ett PyTupleObject som innehåller namnen på de lokala variabler som refereras av nästlade funktioner. Vid fel returneras NULL och ett undantag tas upp.

Tillagd i version 3.11.

PyObject *PyCode_GetFreevars(PyCodeObject *co)

Motsvarar Python-koden getattr(co, 'co_freevars'). Returnerar en ny referens till ett PyTupleObject som innehåller namnen på free (closure) variables. Vid fel returneras NULL och ett undantag tas upp.

Tillagd i version 3.11.

int PyCode_AddWatcher(PyCode_WatchCallback callback)

Registrera callback som en kodobjektsövervakare för den aktuella tolken. Returnerar ett ID som kan skickas till PyCode_ClearWatcher(). I händelse av fel (t.ex. inga fler ID:n tillgängliga), returnera -1 och sätt ett undantag.

Tillagd i version 3.12.

int PyCode_ClearWatcher(int watcher_id)

Rensa en övervakare identifierad av watcher_id som tidigare returnerats från PyCode_AddWatcher() för den aktuella tolken. Returnerar 0 vid framgång, eller -1 och anger ett undantag vid fel (t.ex. om det givna watcher_id aldrig registrerades)

Tillagd i version 3.12.

type PyCodeEvent

Uppräkning av möjliga händelser för kodobjektsövervakare: - PY_CODE_EVENT_CREATE - PY_CODE_EVENT_DESTROY - PY_CODE_EVENT_DESTROY

Tillagd i version 3.12.

typedef int (*PyCode_WatchCallback)(PyCodeEvent event, PyCodeObject *co)

Typ av återuppringningsfunktion för en kodobjektsövervakare.

Om event är PY_CODE_EVENT_CREATE, anropas återuppringningen efter att co har initialiserats helt och hållet. I annat fall anropas återanrop innan co förstörs, så att co tidigare tillstånd kan inspekteras.

Om event är PY_CODE_EVENT_DESTROY kommer en referens i återuppringningen till det kodobjekt som ska förstöras att återuppliva det och förhindra att det 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.

Användare av detta API bör inte förlita sig på interna implementeringsdetaljer för körtiden. Sådana detaljer kan inkludera, men är inte begränsade till, den exakta ordningen och tidpunkten för skapande och förstörelse av kodobjekt. Även om ändringar i dessa detaljer kan resultera i skillnader som kan observeras av observatörer (inklusive om en återuppringning anropas eller inte), ändrar det inte semantiken i den Python-kod som exekveras.

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.

Kod Objekt Flaggor

Kodobjekt innehåller ett bitfält med flaggor, som kan hämtas som Python-attributet co_flags (till exempel med PyObject_GetAttrString()) och ställas in med ett flags-argument till PyUnstable_Code_New() och liknande funktioner.

Flaggor vars namn börjar med CO_FUTURE_ motsvarar funktioner som normalt kan väljas med future statements. Dessa flaggor kan användas i PyCompilerFlags.cf_flags. Observera att många CO_FUTURE_ -flaggor är obligatoriska i nuvarande versioner av Python, och att ange dem har ingen effekt.

Följande flaggor finns tillgängliga. För deras betydelse, se den länkade dokumentationen för deras Python-ekvivalenter.

Flagga	Betydelse
CO_OPTIMIZED	inspect.CO_OPTIMIZED
CO_NEWLOCALS	inspect.CO_NEWLOCALS
CO_VARARGS	inspect.CO_VARARGS
CO_VARKEYWORDS	inspect.CO_VARKEYWORDS
CO_NESTED	inspect.CO_NESTED
CO_GENERATOR	inspect.CO_GENERATOR
CO_COROUTINE	inspect.CO_COROUTINE
CO_ITERABLE_COROUTINE	inspect.CO_ITERABLE_COROUTINE
CO_ASYNC_GENERATOR	inspect.CO_ASYNC_GENERATOR
CO_HAS_DOCSTRING	inspect.CO_HAS_DOCSTRING
CO_METHOD	inspect.CO_METHOD
CO_FUTURE_DIVISION	ingen effekt (__future__.division)
CO_FUTURE_ABSOLUTE_IMPORT	ingen effekt (__future__.absolute_import)
CO_FUTURE_WITH_STATEMENT	ingen effekt (__future__.with_statement)
CO_FUTURE_PRINT_FUNCTION	ingen effekt (__future__.print_function)
CO_FUTURE_UNICODE_LITERALS	ingen effekt (__future__.unicode_literals)
CO_FUTURE_GENERATOR_STOP	ingen effekt (__future__.generator_stop)
CO_FUTURE_ANNOTATIONS	__future__.annotations

Extra information

För att stödja lågnivåtillägg till ramutvärdering, t.ex. externa just-in-time-kompilatorer, är det möjligt att bifoga godtyckliga extra data till kodobjekt.

Dessa funktioner är en del av den instabila C API-nivån: denna funktionalitet är en CPython-implementeringsdetalj, och API kan ändras utan varningar om avskrivning.

Py_ssize_t PyUnstable_Eval_RequestCodeExtraIndex(freefunc free)

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

Returnerar ett nytt opakt indexvärde som används för att lägga till data i kodobjekt.

Du anropar vanligtvis den här funktionen en gång (per tolk) och använder resultatet med PyCode_GetExtra och PyCode_SetExtra för att manipulera data på enskilda kodobjekt.

Om free inte är NULL: när ett kodobjekt avallokeras kommer free att anropas på data som inte är NULL och som lagras under det nya indexet. Använd Py_DecRef() när du lagrar PyObject.

Tillagd i version 3.6: som _PyEval_RequestCodeExtraIndex

Ändrad i version 3.12: Bytt namn till PyUnstable_Eval_RequestCodeExtraIndex. Det gamla privata namnet är föråldrat, men kommer att vara tillgängligt tills API ändras.

int PyUnstable_Code_GetExtra(PyObject *code, Py_ssize_t index, void **extra)

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

Ställ in extra till de extra data som lagras under det angivna indexet. Returnera 0 vid framgång. Ställ in ett undantag och returnera -1 vid misslyckande.

Om inga data har angetts under indexet, anges extra till NULL och returneras 0 utan att något undantag anges.

Tillagd i version 3.6: som _PyCode_GetExtra

Ändrad i version 3.12: Bytt namn till PyUnstable_Code_GetExtra. Det gamla privata namnet är föråldrat, men kommer att vara tillgängligt tills API:et ändras.

int PyUnstable_Code_SetExtra(PyObject *code, Py_ssize_t index, void *extra)

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

Ställ in de extra data som lagras under det angivna indexet till extra. Returnera 0 vid framgång. Ställ in ett undantag och returnera -1 vid misslyckande.

Tillagd i version 3.6: som _PyCode_SetExtra

Ändrad i version 3.12: Bytt namn till PyUnstable_Code_SetExtra. Det gamla privata namnet är föråldrat, men kommer att vara tillgängligt tills API ändras.