Lagret på mycket hög nivå

Funktionerna i det här kapitlet låter dig exekvera Python-källkod som finns i en fil eller en buffert, men de låter dig inte interagera på ett mer detaljerat sätt med tolken.

Flera av dessa funktioner accepterar en startsymbol från grammatiken som en parameter. De tillgängliga startsymbolerna är Py_eval_input, Py_file_input och Py_single_input. Dessa beskrivs efter de funktioner som accepterar dem som parametrar.

Notera också att flera av dessa funktioner tar FILE* parametrar. En särskild fråga som måste hanteras noggrant är att FILE-strukturen för olika C-bibliotek kan vara olika och inkompatibla. Under Windows (åtminstone) är det möjligt för dynamiskt länkade tillägg att faktiskt använda olika bibliotek, så man bör vara noga med att FILE*-parametrar bara skickas till dessa funktioner om det är säkert att de skapades av samma bibliotek som Python-körtiden använder.

int PyRun_AnyFile(FILE *fp, const char *filename)

Detta är ett förenklat gränssnitt till PyRun_AnyFileExFlags() nedan, där closeit är satt till 0 och flags är satt till NULL.

int PyRun_AnyFileFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)

Detta är ett förenklat gränssnitt till PyRun_AnyFileExFlags() nedan, där closeit-argumentet är satt till 0.

int PyRun_AnyFileEx(FILE *fp, const char *filename, int closeit)

Detta är ett förenklat gränssnitt till PyRun_AnyFileExFlags() nedan, där argumentet flags är satt till NULL.

int PyRun_AnyFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)

Om fp hänvisar till en fil som är kopplad till en interaktiv enhet (konsol eller terminalinmatning eller Unix pseudoterminal), returneras värdet av PyRun_InteractiveLoop(), annars returneras resultatet av PyRun_SimpleFile(). filnamn avkodas från filsystemets kodning (sys.getfilesystemencoding()). Om filename är NULL använder den här funktionen "???" som filnamn. Om closeit är true, stängs filen innan PyRun_SimpleFileExFlags() returneras.

int PyRun_SimpleString(const char *command)

Detta är ett förenklat gränssnitt till PyRun_SimpleStringFlags() nedan, där argumentet PyCompilerFlags* är satt till NULL.

int PyRun_SimpleStringFlags(const char *command, PyCompilerFlags *flags)

Exekverar Python-källkoden från command i modulen __main__ i enlighet med argumentet flags. Om __main__ inte redan finns, skapas den. Returnerar 0 vid framgång eller -1 om ett undantag uppstod. Om det uppstod ett fel finns det inget sätt att få information om undantaget. För betydelsen av flags, se nedan.

Observera att om en annars ohanterad SystemExit uppstår, kommer denna funktion inte att returnera -1, utan avsluta processen, så länge som PyConfig.inspect är noll.

int PyRun_SimpleFile(FILE *fp, const char *filename)

Detta är ett förenklat gränssnitt till PyRun_SimpleFileExFlags() nedan, där closeit är satt till 0 och flags är satt till NULL.

int PyRun_SimpleFileEx(FILE *fp, const char *filename, int closeit)

Detta är ett förenklat gränssnitt till PyRun_SimpleFileExFlags() nedan, där flags är satt till NULL.

int PyRun_SimpleFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)

Liknar PyRun_SimpleStringFlags(), men Python-källkoden läses från fp istället för en sträng i minnet. filename ska vara namnet på filen, det avkodas från filesystem encoding and error handler. Om closeit är true, stängs filen innan PyRun_SimpleFileExFlags() returneras.

Anteckning

På Windows bör fp öppnas i binärt läge (t.ex. fopen(filename, "rb")). Annars kan det hända att Python inte hanterar skriptfiler med LF-radavslut korrekt.

int PyRun_InteractiveOne(FILE *fp, const char *filename)

Detta är ett förenklat gränssnitt till PyRun_InteractiveOneFlags() nedan, där flags är satt till NULL.

int PyRun_InteractiveOneFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)

Läs och kör ett enda uttalande från en fil som är kopplad till en interaktiv enhet enligt argumentet flags. Användaren kommer att uppmanas att använda sys.ps1 och sys.ps2. filnamn avkodas från filesystem encoding and error handler.

Returnerar 0 när indata exekverades framgångsrikt, -1 om det fanns ett undantag, eller en felkod från errcode.h include-filen som distribueras som en del av Python om det fanns ett parse-fel. (Observera att errcode.h inte inkluderas av Python.h, så den måste inkluderas specifikt om det behövs)

int PyRun_InteractiveLoop(FILE *fp, const char *filename)

Detta är ett förenklat gränssnitt till PyRun_InteractiveLoopFlags() nedan, där flags är satt till NULL.

int PyRun_InteractiveLoopFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)

Läs och kör satser från en fil som är kopplad till en interaktiv enhet tills EOF nås. Användaren kommer att uppmanas att använda sys.ps1 och sys.ps2. filnamn avkodas från filesystem encoding and error handler. Returnerar 0 vid EOF eller ett negativt tal vid misslyckande.

int (*PyOS_InputHook)(void)

En del av Stabil ABI.

Kan ställas in så att den pekar på en funktion med prototypen int func(void). Funktionen kommer att anropas när Pythons tolkprompt är på väg att bli inaktiv och väntar på användarinmatning från terminalen. Returvärdet ignoreras. Åsidosättande av denna hook kan användas för att integrera tolkens prompt med andra händelseslingor, vilket görs i Modules/_tkinter.c i Pythons källkod.

Ändrad i version 3.12: Denna funktion anropas endast från huvudtolken.

char *(*PyOS_ReadlineFunctionPointer)(FILE*, FILE*, const char*)

Kan sättas till att peka på en funktion med prototypen char *func(FILE *stdin, FILE *stdout, char *prompt), som åsidosätter standardfunktionen som används för att läsa en enda rad indata vid tolkens prompt. Funktionen förväntas mata ut strängen prompt om den inte är NULL, och sedan läsa en rad indata från den angivna standardinmatningsfilen och returnera den resulterande strängen. Exempel: Modulen readline sätter denna hook för att tillhandahålla funktioner för radredigering och tabbkomplettering.

Resultatet måste vara en sträng som allokerats av PyMem_RawMalloc() eller PyMem_RawRealloc(), eller NULL om ett fel inträffat.

Ändrad i version 3.4: Resultatet måste allokeras med PyMem_RawMalloc() eller PyMem_RawRealloc(), istället för att allokeras med PyMem_Malloc() eller PyMem_Realloc().

Ändrad i version 3.12: Denna funktion anropas endast från huvudtolken.

PyObject *PyRun_String(const char *str, int start, PyObject *globals, PyObject *locals)

Returnera värde: Ny referens.

Detta är ett förenklat gränssnitt till PyRun_StringFlags() nedan, där flags är satt till NULL.

PyObject *PyRun_StringFlags(const char *str, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)

Returnera värde: Ny referens.

Exekvera Python-källkod från str i det sammanhang som anges av objekten globals och locals med de kompilatorflaggor som anges av flags. globals måste vara en ordbok; locals kan vara vilket objekt som helst som implementerar mappningsprotokollet. Parametern start anger den starttoken som ska användas för att analysera källkoden.

Returnerar resultatet av att exekvera koden som ett Python-objekt, eller NULL om ett undantag uppstod.

PyObject *PyRun_File(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals)

Returnera värde: Ny referens.

Detta är ett förenklat gränssnitt till PyRun_FileExFlags() nedan, där closeit är satt till 0 och flags är satt till NULL.

PyObject *PyRun_FileEx(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit)

Returnera värde: Ny referens.

Detta är ett förenklat gränssnitt till PyRun_FileExFlags() nedan, där flags är satt till NULL.

PyObject *PyRun_FileFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)

Returnera värde: Ny referens.

Detta är ett förenklat gränssnitt till PyRun_FileExFlags() nedan, där closeit är satt till 0.

PyObject *PyRun_FileExFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit, PyCompilerFlags *flags)

Returnera värde: Ny referens.

Liknar PyRun_StringFlags(), men Python-källkoden läses från fp istället för en sträng i minnet. filename bör vara namnet på filen, det avkodas från filesystem encoding and error handler. Om closeit är true, stängs filen innan PyRun_FileExFlags() returneras.

PyObject *Py_CompileString(const char *str, const char *filename, int start)

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

Detta är ett förenklat gränssnitt till Py_CompileStringFlags() nedan, där flags är satt till NULL.

PyObject *Py_CompileStringFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags)

Returnera värde: Ny referens.

Detta är ett förenklat gränssnitt till Py_CompileStringExFlags() nedan, med optimize satt till -1.

PyObject *Py_CompileStringObject(const char *str, PyObject *filename, int start, PyCompilerFlags *flags, int optimize)

Returnera värde: Ny referens.

Analyserar och kompilerar Python-källkoden i str och returnerar det resulterande kodobjektet. Starttoken ges av start; detta kan användas för att begränsa den kod som kan kompileras och bör vara Py_eval_input, Py_file_input eller Py_single_input. Filnamnet som anges av filnamn används för att konstruera kodobjektet och kan visas i spårningar eller SyntaxError undantagsmeddelanden. Detta returnerar NULL om koden inte kan analyseras eller kompileras.

Heltalet optimize anger kompilatorns optimeringsnivå; ett värde på -1 väljer tolkens optimeringsnivå som anges i -O-alternativen. Explicita nivåer är 0 (ingen optimering; __debug__ är sant), 1 (asserts tas bort, __debug__ är falskt) eller 2 (docstrings tas också bort).

Tillagd i version 3.4.

PyObject *Py_CompileStringExFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags, int optimize)

Returnera värde: Ny referens.

Som Py_CompileStringObject(), men filnamn är en byte-sträng avkodad från filesystem encoding and error handler.

Tillagd i version 3.2.

PyObject *PyEval_EvalCode(PyObject *co, PyObject *globals, PyObject *locals)

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

Detta är ett förenklat gränssnitt till PyEval_EvalCodeEx(), med bara kodobjektet samt globala och lokala variabler. De andra argumenten sätts till NULL.

PyObject *PyEval_EvalCodeEx(PyObject *co, PyObject *globals, PyObject *locals, PyObject *const *args, int argcount, PyObject *const *kws, int kwcount, PyObject *const *defs, int defcount, PyObject *kwdefs, PyObject *closure)

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

Utvärdera ett förkompilerat kodobjekt, givet en viss miljö för dess utvärdering. Denna miljö består av en ordbok med globala variabler, ett mappningsobjekt med lokala variabler, matriser med argument, nyckelord och standardvärden, en ordbok med standardvärden för keyword-only-argument och en closure-tupel av celler.

PyObject *PyEval_EvalFrame(PyFrameObject *f)

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

Utvärderar en exekveringsram. Detta är ett förenklat gränssnitt till PyEval_EvalFrameEx(), för bakåtkompatibilitet.

PyObject *PyEval_EvalFrameEx(PyFrameObject *f, int throwflag)

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

Detta är den huvudsakliga, oförfalskade funktionen för Python-tolkning. Kodobjektet som är associerat med exekveringsramen f exekveras, tolkar bytekod och utför anrop efter behov. Den extra parametern throwflag kan för det mesta ignoreras - om den är sann leder den till att ett undantag omedelbart kastas; detta används för throw()-metoderna för generatorobjekt.

Ä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.

int PyEval_MergeCompilerFlags(PyCompilerFlags *cf)

Denna funktion ändrar flaggorna för den aktuella utvärderingsramen och returnerar true om den lyckas, false om den misslyckas.

int Py_eval_input

Startsymbolen från Pythons grammatik för isolerade uttryck; för användning med Py_CompileString().

int Py_file_input

Startsymbolen från Python-grammatiken för sekvenser av satser som läses från en fil eller annan källa; för användning med Py_CompileString(). Detta är den symbol som ska användas när man kompilerar godtyckligt lång Python-källkod.

int Py_single_input

Startsymbolen från Python-grammatiken för ett enda uttalande; för användning med Py_CompileString(). Detta är den symbol som används för den interaktiva tolkens loop.

struct PyCompilerFlags

Detta är den struktur som används för att hålla kompilatorflaggor. I fall där kod endast kompileras, skickas den som int flags, och i fall där kod exekveras, skickas den som PyCompilerFlags *flags. I det här fallet kan from __future__ import modifiera flags.

När PyCompilerFlags *flags är NULL, cf_flags behandlas som lika med 0, och alla ändringar på grund av from __future__ import kasseras.

int cf_flags

Flaggor för kompilator.

int cf_feature_version

cf_feature_version är den mindre Python-versionen. Den bör initialiseras till PY_MINOR_VERSION.

Fältet ignoreras som standard, det används endast om flaggan PyCF_ONLY_AST är inställd i cf_flags.

Ändrad i version 3.8: Fältet cf_feature_version har lagts till.

De tillgängliga kompilatorflaggorna är tillgängliga som makron:

PyCF_ALLOW_TOP_LEVEL_AWAIT

PyCF_ONLY_AST

PyCF_OPTIMIZED_AST

PyCF_TYPE_COMMENTS

Se compiler flags i dokumentationen av Python-modulen ast, som exporterar dessa konstanter under samma namn.

”PyCF”-flaggorna ovan kan kombineras med ”CO_FUTURE”-flaggor som CO_FUTURE_ANNOTATIONS för att aktivera funktioner som normalt kan väljas med future statements. Se Kod Objekt Flaggor för en fullständig lista.