最高级层¶
本章中的函数允许您执行给定文件或缓冲区中的 Python 源代码，但它们不允许您以更详细的方式与解释器交互。
其中一些函数接受语法中的起始符号作为参数。可用的起始符号是 Py_eval_input、Py_file_input 和 Py_single_input。这些将在接受它们作为参数的函数之后进行描述。
还要注意，其中一些函数采用 FILE* 参数。需要仔细处理的一个特定问题是，不同 C 库的 FILE 结构可能不同且不兼容。在 Windows（至少）下，动态链接扩展实际上可以使用不同的库，因此应注意仅在确定它们是由 Python 运行时使用的相同库创建时才将 FILE* 参数传递给这些函数。
-
int Py_Main(int argc, wchar_t **argv)¶
- 是 稳定 ABI 的一部分。
标准解释器的主要程序。这可用于嵌入 Python 的程序。argc 和 argv 参数应与传递给 C 程序的
main()函数的参数完全相同（根据用户的区域设置转换为 wchar_t）。重要的是要注意，参数列表可能会被修改（但参数列表指向的字符串的内容不会被修改）。返回值将为0，如果解释器正常退出（即，没有异常），则为1，如果解释器由于异常而退出，则为2，如果参数列表不代表有效的 Python 命令行。请注意，如果引发了未处理的
SystemExit，只要PyConfig.inspect为零，此函数将不会返回1，而是退出进程。
-
int Py_BytesMain(int argc, char **argv)¶
- 是 稳定 ABI 的一部分，从 3.8 版本开始。
类似于
Py_Main()，但 argv 是字节字符串数组。在 3.8 版本中添加。
-
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，此函数不会返回-1，而是退出进程，只要PyConfig.inspect为零。
-
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），然后从提供的标准输入文件读取一行输入，并返回结果字符串。 例如，readline模块设置此钩子以提供行编辑和制表符完成功能。结果必须是通过
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 指定用于解析源代码的起始标记。
返回执行代码的结果作为 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)¶
此函数更改当前评估帧的标志，并在成功时返回真，失败时返回假。
-
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。默认情况下，该字段被忽略，只有当
PyCF_ONLY_AST标志在cf_flags中被设置时才会使用。
在版本 3.8 中变更: 添加了 cf_feature_version 字段。
-
int cf_flags¶