Die Sehr Hochstufige Schicht

Die Funktionen in diesem Kapitel ermöglichen es Ihnen, Python-Quellcode aus einer Datei oder einem Puffer auszuführen, aber sie bieten Ihnen keine Möglichkeit, auf detailliertere Weise mit dem Interpreter zu interagieren.

Mehrere dieser Funktionen akzeptieren ein Startsymbol aus der Grammatik als Parameter. Die verfügbaren Startsymbole sind Py_eval_input, Py_file_input und Py_single_input. Diese werden nach den Funktionen beschrieben, die sie als Parameter akzeptieren.

Beachten Sie auch, dass mehrere dieser Funktionen FILE*-Parameter akzeptieren. Ein besonderes Problem, das sorgfältig behandelt werden muss, ist, dass die FILE-Struktur für verschiedene C-Bibliotheken unterschiedlich und inkompatibel sein kann. Unter Windows (zumindest) ist es möglich, dass dynamisch verknüpfte Erweiterungen tatsächlich unterschiedliche Bibliotheken verwenden. Daher sollte darauf geachtet werden, dass FILE*-Parameter nur an diese Funktionen übergeben werden, wenn sicher ist, dass sie von derselben Bibliothek erstellt wurden, die auch von der Python-Laufzeitumgebung verwendet wird.

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

Dies ist eine vereinfachte Schnittstelle zu PyRun_AnyFileExFlags() unten, wobei closeit auf 0 und flags auf NULL gesetzt bleiben.

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

Dies ist eine vereinfachte Schnittstelle zu PyRun_AnyFileExFlags() unten, wobei das Argument closeit auf 0 gesetzt bleibt.

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

Dies ist eine vereinfachte Schnittstelle zu PyRun_AnyFileExFlags() unten, wobei das Argument flags auf NULL gesetzt bleibt.

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

Wenn fp sich auf eine Datei bezieht, die mit einem interaktiven Gerät (Konsolen- oder Terminaleingabe oder Unix-Pseudoterminal) verbunden ist, gibt diese Funktion den Wert von PyRun_InteractiveLoop() zurück, andernfalls gibt sie das Ergebnis von PyRun_SimpleFile() zurück. filename wird aus der Dateisystemkodierung dekodiert (sys.getfilesystemencoding()). Wenn filename NULL ist, verwendet diese Funktion "???" als Dateinamen. Wenn closeit wahr ist, wird die Datei vor der Rückgabe von PyRun_SimpleFileExFlags() geschlossen.

int PyRun_SimpleString(const char *command)

Dies ist eine vereinfachte Schnittstelle zu PyRun_SimpleStringFlags() unten, wobei das Argument PyCompilerFlags* auf NULL gesetzt bleibt.

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

Führt den Python-Quellcode aus command im Modul __main__ gemäß dem Argument flags aus. Wenn __main__ noch nicht existiert, wird es erstellt. Gibt 0 bei Erfolg zurück oder -1, wenn eine Ausnahme ausgelöst wurde. Wenn ein Fehler aufgetreten ist, gibt es keine Möglichkeit, die Ausnahmeinformationen zu erhalten. Die Bedeutung von flags finden Sie unten.

Beachten Sie, dass diese Funktion die Verarbeitung beendet, wenn eine ansonsten unbehandelte SystemExit-Ausnahme ausgelöst wird, und nicht mit -1 zurückkehrt, solange PyConfig.inspect null ist.

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

Dies ist eine vereinfachte Schnittstelle zu PyRun_SimpleFileExFlags() unten, wobei closeit auf 0 und flags auf NULL gesetzt bleiben.

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

Dies ist eine vereinfachte Schnittstelle zu PyRun_SimpleFileExFlags() unten, wobei flags auf NULL gesetzt bleibt.

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

Ähnlich wie PyRun_SimpleStringFlags(), aber der Python-Quellcode wird aus fp anstelle eines In-Memory-Strings gelesen. filename sollte der Name der Datei sein, er wird aus der Dateisystemkodierung und Fehlerbehandlung dekodiert. Wenn closeit wahr ist, wird die Datei geschlossen, bevor PyRun_SimpleFileExFlags() zurückkehrt.

Hinweis

Unter Windows sollte fp im Binärmodus geöffnet werden (z. B. fopen(filename, "rb")). Andernfalls kann Python ein Skript mit Zeilenumbrüchen vom Typ LF möglicherweise nicht korrekt verarbeiten.

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

Dies ist eine vereinfachte Schnittstelle zu PyRun_InteractiveOneFlags() unten, wobei flags auf NULL gesetzt bleibt.

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

Liest und führt eine einzelne Anweisung aus einer Datei aus, die mit einem interaktiven Gerät verbunden ist, gemäß dem Argument flags. Der Benutzer wird mit sys.ps1 und sys.ps2 aufgefordert. filename wird aus der Dateisystemkodierung und Fehlerbehandlung dekodiert.

Gibt 0 zurück, wenn die Eingabe erfolgreich ausgeführt wurde, -1, wenn eine Ausnahme ausgelöst wurde, oder einen Fehlercode aus der errcode.h-Datei, die als Teil von Python verteilt wird, wenn ein Parsing-Fehler aufgetreten ist. (Beachten Sie, dass errcode.h nicht von Python.h inkludiert wird und daher spezifisch inkludiert werden muss, falls erforderlich.)

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

Dies ist eine vereinfachte Schnittstelle zu PyRun_InteractiveLoopFlags() unten, wobei flags auf NULL gesetzt bleibt.

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

Liest und führt Anweisungen aus einer Datei aus, die mit einem interaktiven Gerät verbunden ist, bis das Ende der Datei (EOF) erreicht ist. Der Benutzer wird mit sys.ps1 und sys.ps2 aufgefordert. filename wird aus der Dateisystemkodierung und Fehlerbehandlung dekodiert. Gibt 0 bei EOF oder eine negative Zahl bei einem Fehler zurück.

int (*PyOS_InputHook)(void)

Teil der Stable ABI.

Kann so gesetzt werden, dass er auf eine Funktion mit dem Prototyp int func(void) zeigt. Die Funktion wird aufgerufen, wenn die Eingabeaufforderung des Python-Interpreters kurz davor steht, inaktiv zu werden und auf Benutzereingaben vom Terminal zu warten. Der Rückgabewert wird ignoriert. Das Überschreiben dieses Hooks kann verwendet werden, um die Eingabeaufforderung des Interpreters mit anderen ereignisgesteuerten Schleifen zu integrieren, wie es in Modules/_tkinter.c im Python-Quellcode geschieht.

Geändert in Version 3.12: Diese Funktion wird nur vom Hauptinterpreter aufgerufen.

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

Kann so gesetzt werden, dass er auf eine Funktion mit dem Prototyp char *func(FILE *stdin, FILE *stdout, char *prompt) zeigt, um die Standardfunktion zum Lesen einer einzelnen Zeile Eingabe an der Eingabeaufforderung des Interpreters zu überschreiben. Die Funktion soll die Zeichenkette prompt ausgeben, falls sie nicht NULL ist, und dann eine Zeile Eingabe aus der angegebenen Standardeingabedatei lesen und die resultierende Zeichenkette zurückgeben. Beispielsweise setzt das Modul readline diesen Hook, um Zeilenbearbeitungs- und Tab-Vervollständigungsfunktionen bereitzustellen.

Das Ergebnis muss eine Zeichenkette sein, die von PyMem_RawMalloc() oder PyMem_RawRealloc() alloziert wurde, oder NULL, wenn ein Fehler aufgetreten ist.

Geändert in Version 3.4: Das Ergebnis muss von PyMem_RawMalloc() oder PyMem_RawRealloc() alloziert werden, anstatt von PyMem_Malloc() oder PyMem_Realloc().

Geändert in Version 3.12: Diese Funktion wird nur vom Hauptinterpreter aufgerufen.

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

Rückgabewert: Neue Referenz.

Dies ist eine vereinfachte Schnittstelle zu PyRun_StringFlags() unten, wobei flags auf NULL gesetzt bleibt.

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

Rückgabewert: Neue Referenz.

Führt Python-Quellcode aus str im Kontext aus, der durch die Objekte globals und locals spezifiziert wird, mit den durch flags spezifizierten Compiler-Flags. globals muss ein Dictionary sein; locals kann jedes Objekt sein, das das Mapping-Protokoll implementiert. Der Parameter start spezifiziert das Startsymbol und muss eines der folgenden sein: Py_eval_input, Py_file_input oder Py_single_input.

Gibt das Ergebnis der Ausführung des Codes als Python-Objekt zurück oder NULL, wenn eine Ausnahme ausgelöst wurde.

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

Rückgabewert: Neue Referenz.

Dies ist eine vereinfachte Schnittstelle zu PyRun_FileExFlags() unten, wobei closeit auf 0 und flags auf NULL gesetzt bleiben.

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

Rückgabewert: Neue Referenz.

Dies ist eine vereinfachte Schnittstelle zu PyRun_FileExFlags() unten, wobei flags auf NULL gesetzt bleibt.

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

Rückgabewert: Neue Referenz.

Dies ist eine vereinfachte Schnittstelle zu PyRun_FileExFlags() unten, wobei closeit auf 0 gesetzt bleibt.

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

Rückgabewert: Neue Referenz.

Ähnlich wie PyRun_StringFlags(), aber der Python-Quellcode wird aus fp anstelle eines In-Memory-Strings gelesen. filename sollte der Name der Datei sein, er wird aus der Dateisystemkodierung und Fehlerbehandlung dekodiert. Wenn closeit wahr ist, wird die Datei geschlossen, bevor PyRun_FileExFlags() zurückkehrt.

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

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.

Dies ist eine vereinfachte Schnittstelle zu Py_CompileStringFlags() unten, wobei flags auf NULL gesetzt wird.

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

Rückgabewert: Neue Referenz.

Dies ist eine vereinfachte Schnittstelle zu Py_CompileStringExFlags() unten, mit optimize auf -1 gesetzt.

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

Rückgabewert: Neue Referenz.

Parst und kompiliert den Python-Quellcode in str und gibt das resultierende Code-Objekt zurück. Das Startsymbol wird durch start angegeben; dies kann verwendet werden, um den zu kompilierenden Code einzuschränken, und sollte Py_eval_input, Py_file_input oder Py_single_input sein. Der durch filename angegebene Dateiname wird verwendet, um das Code-Objekt zu erstellen und kann in Tracebacks oder SyntaxError-Ausnahmemeldungen erscheinen. Dies gibt NULL zurück, wenn der Code nicht geparst oder kompiliert werden kann.

Die Ganzzahl optimize gibt die Optimierungsstufe des Compilers an; ein Wert von -1 wählt die Optimierungsstufe des Interpreters, wie durch -O-Optionen angegeben. Explizite Stufen sind 0 (keine Optimierung; __debug__ ist true), 1 (asserts werden entfernt, __debug__ ist false) oder 2 (docstrings werden ebenfalls entfernt).

Hinzugefügt in Version 3.4.

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

Rückgabewert: Neue Referenz.

Wie Py_CompileStringObject(), aber filename ist ein Byte-String, der aus der Dateisystem-Kodierung und dem Fehlerbehandler dekodiert wurde.

Hinzugefügt in Version 3.2.

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

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.

Dies ist eine vereinfachte Schnittstelle zu PyEval_EvalCodeEx(), nur mit dem Code-Objekt sowie globalen und lokalen Variablen. Die anderen Argumente werden auf NULL gesetzt.

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)

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.

Evaluiert ein vorcompiliertes Code-Objekt, gegeben eine bestimmte Umgebung für seine Auswertung. Diese Umgebung besteht aus einem Wörterbuch von globalen Variablen, einem Mapping-Objekt von lokalen Variablen, Arrays von Argumenten, Schlüsselwörtern und Standardwerten, einem Wörterbuch von Standardwerten für Keyword-only-Argumente und einem Closure-Tupel von Zellen.

PyObject *PyEval_EvalFrame(PyFrameObject *f)

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.

Evaluiert einen Ausführungs-Frame. Dies ist eine vereinfachte Schnittstelle zu PyEval_EvalFrameEx(), zur Abwärtskompatibilität.

PyObject *PyEval_EvalFrameEx(PyFrameObject *f, int throwflag)

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.

Dies ist die wichtigste, unverfälschte Funktion der Python-Interpretation. Das dem Ausführungs-Frame f zugeordnete Code-Objekt wird ausgeführt, Bytecodes interpretiert und Aufrufe nach Bedarf ausgeführt. Der zusätzliche Parameter throwflag kann größtenteils ignoriert werden – wenn er true ist, wird eine Ausnahme sofort ausgelöst; dies wird für die throw()-Methoden von Generator-Objekten verwendet.

Geändert in Version 3.4: Diese Funktion enthält jetzt eine Debug-Assertion, um sicherzustellen, dass sie keine aktive Ausnahme stillschweigend verwirft.

int PyEval_MergeCompilerFlags(PyCompilerFlags *cf)

Diese Funktion ändert die Flags des aktuellen Auswertungs-Frames und gibt bei Erfolg true, bei Fehlschlag false zurück.

int Py_eval_input

Das Startsymbol der Python-Grammatik für isolierte Ausdrücke; zur Verwendung mit Py_CompileString().

int Py_file_input

Das Startsymbol der Python-Grammatik für Anweisungssequenzen, wie sie aus einer Datei oder einer anderen Quelle gelesen werden; zur Verwendung mit Py_CompileString(). Dies ist das Symbol, das beim Kompilieren beliebig langer Python-Quelltexte verwendet werden sollte.

int Py_single_input

Das Startsymbol der Python-Grammatik für eine einzelne Anweisung; zur Verwendung mit Py_CompileString(). Dies ist das Symbol, das für die interaktive Interpreter-Schleife verwendet wird.

struct PyCompilerFlags

Dies ist die Struktur, die verwendet wird, um Compiler-Flags zu speichern. In Fällen, in denen nur Code kompiliert wird, wird sie als int flags übergeben, und in Fällen, in denen Code ausgeführt wird, wird sie als PyCompilerFlags *flags übergeben. In diesem Fall kann from __future__ import flags ändern.

Immer wenn PyCompilerFlags *flags NULL ist, wird cf_flags als gleich 0 behandelt, und jede Änderung aufgrund von from __future__ import wird verworfen.

int cf_flags

Compiler-Flags.

int cf_feature_version

cf_feature_version ist die Neben-Versionsnummer von Python. Sie sollte mit PY_MINOR_VERSION initialisiert werden.

Das Feld wird standardmäßig ignoriert. Es wird nur verwendet, wenn das Flag PyCF_ONLY_AST in cf_flags gesetzt ist.

Geändert in Version 3.8: Feld cf_feature_version hinzugefügt.

Die verfügbaren Compiler-Flags sind über Makros zugänglich

PyCF_ALLOW_TOP_LEVEL_AWAIT

PyCF_ONLY_AST

PyCF_OPTIMIZED_AST

PyCF_TYPE_COMMENTS

Siehe Compiler-Flags in der Dokumentation des Python-Moduls ast, das diese Konstanten unter denselben Namen exportiert.

Die oben genannten „PyCF“-Flags können mit „CO_FUTURE“-Flags wie CO_FUTURE_ANNOTATIONS kombiniert werden, um Funktionen zu aktivieren, die normalerweise über Future-Anweisungen auswählbar sind. Siehe Code-Objekt-Flags für eine vollständige Liste.