最高層¶
本章中的函式將允許你執行檔案或緩衝區中給定的 Python 原始碼，但它們不允許你以更詳細的方式與直譯器進行互動。
這些函式中的幾個接受語法中的起始符號作為引數。 可用的起始符號是 Py_eval_input、Py_file_input 和 Py_single_input。 下面在接受它們作為引數的函式之後描述這些符號。
另請注意，這些函式中的幾個接受 FILE* 引數。 一個需要小心處理的特殊問題是，不同 C 庫的 FILE 結構可能不同且不相容。 在 Windows（至少）下，動態連結的擴充套件實際上可能使用不同的庫，因此應注意僅在確定 FILE* 引數是由 Python 執行時使用的同一庫建立時才將它們傳遞給這些函式。
-
int PyRun_AnyFile(FILE *fp, const char *filename)¶
這是下面
PyRun_AnyFileExFlags()的簡化介面，將 closeit 設定為0，將 flags 設定為NULL。
-
int PyRun_AnyFileFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)¶
這是下面
PyRun_AnyFileExFlags()的簡化介面，將 closeit 引數設定為0。
-
int PyRun_AnyFileEx(FILE *fp, const char *filename, int closeit)¶
這是下面
PyRun_AnyFileExFlags()的簡化介面，將 flags 引數設定為NULL。
-
int PyRun_AnyFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)¶
如果 fp 指的是與互動式裝置（控制檯或終端輸入或 Unix 偽終端）關聯的檔案，則返回
PyRun_InteractiveLoop()的值，否則返回PyRun_SimpleFile()的結果。 filename 從檔案系統編碼 (sys.getfilesystemencoding()) 解碼。如果 filename 為NULL，此函式使用"???"作為檔名。如果 closeit 為真，則在PyRun_SimpleFileExFlags()返回之前關閉檔案。
-
int PyRun_SimpleString(const char *command)¶
這是下面
PyRun_SimpleStringFlags()的簡化介面，將PyCompilerFlags* 引數設定為NULL。
-
int PyRun_SimpleStringFlags(const char *command, PyCompilerFlags *flags)¶
根據 flags 引數在
__main__模組中執行來自 command 的 Python 原始碼。如果__main__尚不存在，則會建立它。成功時返回0，如果引發異常則返回-1。如果發生錯誤，則無法獲取異常資訊。有關 flags 的含義，請參見下文。請注意，如果引發了未處理的
SystemExit，只要PyConfig.inspect為零，此函式將不返回-1，而是退出程序。
-
int PyRun_SimpleFile(FILE *fp, const char *filename)¶
這是下面
PyRun_SimpleFileExFlags()的簡化介面，將 closeit 設定為0，將 flags 設定為NULL。
-
int PyRun_SimpleFileEx(FILE *fp, const char *filename, int closeit)¶
這是下面
PyRun_SimpleFileExFlags()的簡化介面，將 flags 設定為NULL。
-
int PyRun_SimpleFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)¶
類似於
PyRun_SimpleStringFlags()，但是 Python 原始碼是從 fp 而不是記憶體中的字串讀取的。 filename 應該是檔名，它從檔案系統編碼和錯誤處理程式解碼。如果 closeit 為真，則在PyRun_SimpleFileExFlags()返回之前關閉檔案。備註
在 Windows 上，fp 應該以二進位制模式開啟（例如
fopen(filename, "rb")）。否則，Python 可能無法正確處理帶有 LF 行結束符的指令碼檔案。
-
int PyRun_InteractiveOne(FILE *fp, const char *filename)¶
這是下面
PyRun_InteractiveOneFlags()的簡化介面，將 flags 設定為NULL。
-
int PyRun_InteractiveOneFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)¶
根據 flags 引數從與互動式裝置關聯的檔案中讀取並執行單個語句。 使用者將使用
sys.ps1和sys.ps2獲得提示。 filename 從檔案系統編碼和錯誤處理程式解碼。輸入成功執行時返回
0，發生異常時返回-1，如果發生解析錯誤，則返回 Python 分發中的errcode.h標頭檔案中的錯誤程式碼。（請注意，errcode.h未包含在Python.h中，因此如果需要，必須專門包含它。）
-
int PyRun_InteractiveLoop(FILE *fp, const char *filename)¶
這是下面
PyRun_InteractiveLoopFlags()的簡化介面，將 flags 設定為NULL。
-
int PyRun_InteractiveLoopFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)¶
從與互動式裝置關聯的檔案中讀取並執行語句直到遇到 EOF。 使用者將使用
sys.ps1和sys.ps2獲得提示。 filename 從檔案系統編碼和錯誤處理程式解碼。 到達 EOF 時返回0，失敗時返回負數。
-
int (*PyOS_InputHook)(void)¶
- 作為 穩定 ABI 的一部分。
可以設定為指向具有原型
int func(void)的函式。當 Python 的直譯器提示符即將空閒並等待使用者從終端輸入時，將呼叫該函式。返回值被忽略。覆蓋此鉤子可用於將直譯器的提示符與其他事件迴圈整合，如 Python 原始碼中的Modules/_tkinter.c中所做的那樣。3.12 版本中的變化: 此函式僅從主直譯器呼叫。
-
char *(*PyOS_ReadlineFunctionPointer)(FILE*, FILE*, const char*)¶
可以設定為指向具有原型
char *func(FILE *stdin, FILE *stdout, char *prompt)的函式，它會覆蓋預設的用於在直譯器提示符處讀取單行輸入的函式。該函式應在 prompt 非NULL時輸出 prompt 字串，然後從提供的標準輸入檔案中讀取一行輸入，並返回結果字串。例如，readline模組設定此鉤子以提供行編輯和 Tab 補全功能。結果必須是
PyMem_RawMalloc()或PyMem_RawRealloc()分配的字串，如果發生錯誤則為NULL。3.4 版本中的變化: 結果必須由
PyMem_RawMalloc()或PyMem_RawRealloc()分配，而不是由PyMem_Malloc()或PyMem_Realloc()分配。3.12 版本中的變化: 此函式僅從主直譯器呼叫。
-
PyObject *PyRun_String(const char *str, int start, PyObject *globals, PyObject *locals)¶
- 返回值：新引用。
這是下面
PyRun_StringFlags()的簡化介面，將 flags 設定為NULL。
-
PyObject *PyRun_StringFlags(const char *str, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)¶
- 返回值：新引用。
在由 globals 和 locals 物件指定的上下文中，使用 flags 指定的編譯器標誌執行來自 str 的 Python 原始碼。globals 必須是一個字典；locals 可以是任何實現對映協議的物件。引數 start 指定起始符號，並且必須是以下之一：
Py_eval_input、Py_file_input或Py_single_input。以 Python 物件的形式返回程式碼執行的結果，如果引發異常則返回
NULL。
-
PyObject *PyRun_File(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals)¶
- 返回值：新引用。
這是下面
PyRun_FileExFlags()的簡化介面，將 closeit 設定為0，將 flags 設定為NULL。
-
PyObject *PyRun_FileEx(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit)¶
- 返回值：新引用。
這是下面
PyRun_FileExFlags()的簡化介面，將 flags 設定為NULL。
-
PyObject *PyRun_FileFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)¶
- 返回值：新引用。
這是下面
PyRun_FileExFlags()的簡化介面，將 closeit 設定為0。
-
PyObject *PyRun_FileExFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit, PyCompilerFlags *flags)¶
- 返回值：新引用。
類似於
PyRun_StringFlags()，但是 Python 原始碼是從 fp 而不是記憶體中的字串讀取的。filename 應該是檔名，它從檔案系統編碼和錯誤處理程式解碼。如果 closeit 為真，則在PyRun_FileExFlags()返回之前關閉檔案。
-
PyObject *Py_CompileString(const char *str, const char *filename, int start)¶
- 返回值: 新引用。 穩定ABI 的一部分。
這是下面
Py_CompileStringFlags()的簡化介面，將 flags 設定為NULL。
-
PyObject *Py_CompileStringFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags)¶
- 返回值：新引用。
這是下面
Py_CompileStringExFlags()的簡化介面，將 optimize 設定為-1。
-
PyObject *Py_CompileStringObject(const char *str, PyObject *filename, int start, PyCompilerFlags *flags, int optimize)¶
- 返回值：新引用。
解析並編譯 str 中的 Python 原始碼，返回生成的程式碼物件。 起始符號由 start 給出；這可用於限制可以編譯的程式碼，並且應該為
Py_eval_input、Py_file_input或Py_single_input。 filename 指定的檔名用於構造程式碼物件，並可能出現在回溯或SyntaxError異常訊息中。 如果程式碼無法解析或編譯，則返回NULL。整數 optimize 指定編譯器的最佳化級別；值
-1選擇直譯器由-O選項給出的最佳化級別。明確的級別是0(不最佳化；__debug__為真)、1(斷言被移除，__debug__為假) 或2(文件字串也被移除)。在 3.4 版本加入。
-
PyObject *Py_CompileStringExFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags, int optimize)¶
- 返回值：新引用。
類似於
Py_CompileStringObject()，但是 filename 是從檔案系統編碼和錯誤處理程式解碼的位元組字串。在 3.2 版本加入。
-
PyObject *PyEval_EvalCode(PyObject *co, PyObject *globals, PyObject *locals)¶
- 返回值: 新引用。 穩定ABI 的一部分。
這是
PyEval_EvalCodeEx()的簡化介面，僅包含程式碼物件以及全域性變數和區域性變數。其他引數設定為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)¶
- 返回值: 新引用。 穩定ABI 的一部分。
計算預編譯的程式碼物件，給定其求值的特定環境。此環境由全域性變數字典、區域性變數的對映物件、引數、關鍵字和預設值的陣列、僅限關鍵字引數的預設值字典以及閉包元組的單元組成。
-
PyObject *PyEval_EvalFrame(PyFrameObject *f)¶
- 返回值: 新引用。 穩定ABI 的一部分。
求值一個執行幀。這是
PyEval_EvalFrameEx()的簡化介面，用於向後相容。
-
PyObject *PyEval_EvalFrameEx(PyFrameObject *f, int throwflag)¶
- 返回值: 新引用。 穩定ABI 的一部分。
這是 Python 解釋的主要、未修飾的函式。與執行幀 f 關聯的程式碼物件將被執行，解釋位元組碼並根據需要執行呼叫。額外的 throwflag 引數基本上可以忽略——如果為真，它會導致立即丟擲異常；這用於生成器物件的
throw()方法。3.4 版本中的變化: 此函式現在包含一個除錯斷言，以幫助確保它不會靜默丟棄活動的異常。
-
int PyEval_MergeCompilerFlags(PyCompilerFlags *cf)¶
此函式更改當前求值幀的標誌，成功時返回 true，失敗時返回 false。
-
int Py_eval_input¶
用於獨立表示式的 Python 語法中的起始符號；與
Py_CompileString()結合使用。
-
int Py_file_input¶
用於從檔案或其他來源讀取的語句序列的 Python 語法中的起始符號；與
Py_CompileString()結合使用。這是編譯任意長的 Python 原始碼時要使用的符號。
-
int Py_single_input¶
用於單個語句的 Python 語法中的起始符號；與
Py_CompileString()結合使用。這是互動式直譯器迴圈使用的符號。
-
struct PyCompilerFlags¶
這是用於儲存編譯器標誌的結構。在只編譯程式碼的情況下，它作為
int flags傳遞，而在執行程式碼的情況下，它作為PyCompilerFlags *flags傳遞。在這種情況下，from __future__ import可以修改 flags。每當
PyCompilerFlags *flags為NULL時，cf_flags被視為等於0，並且由於from __future__ import而導致的任何修改都將被丟棄。-
int cf_flags¶
編譯器標誌。
-
int cf_feature_version¶
cf_feature_version 是 Python 次要版本。 它應該初始化為
PY_MINOR_VERSION。該欄位預設被忽略，當且僅當
cf_flags中設定了PyCF_ONLY_AST標誌時才使用。
3.8 版本中的變化: 添加了 cf_feature_version 欄位。
可用的編譯器標誌可透過宏訪問
-
PyCF_ALLOW_TOP_LEVEL_AWAIT¶
-
PyCF_ONLY_AST¶
-
PyCF_OPTIMIZED_AST¶
-
PyCF_TYPE_COMMENTS¶
參見
astPython 模組文件中的編譯器標誌，該模組以相同的名稱匯出這些常量。
上述“
PyCF”標誌可以與“CO_FUTURE”標誌（例如CO_FUTURE_ANNOTATIONS）結合使用，以啟用通常可透過未來語句選擇的功能。有關完整列表，請參見程式碼物件標誌。-
int cf_flags¶