非常高级的层 — Python 文档

非常高级的层

本章中的函数将允许您执行文件或缓冲区中给出的 Python 源代码，但它们不会让您以更详细的方式与解释器进行交互。

其中一些函数接受语法中的开始符号作为参数。 可用的起始符号为 Py_eval_input、Py_file_input 和 Py_single_input。 这些在接受它们作为参数的函数之后进行描述。

另请注意，其中一些函数采用 FILE* 参数。 需要小心处理的一个特殊问题是不同 C 库的 FILE 结构可能不同且不兼容。 在 Windows 下（至少），动态链接的扩展实际上可以使用不同的库，因此应注意 FILE* 参数仅在确定它们是由与 Python 运行时使用的库相同。

int Py_Main(int argc, wchar_t **argv)

标准解释器的主程序。 这可用于嵌入 Python 的程序。 argc 和 argv 参数应与传递给 C 程序的 main() 函数的参数完全相同（根据用户的语言环境转换为 wchar_t）。 需要注意的是，参数列表可能会被修改（但参数列表指向的字符串的内容不会）。 解释器正常退出（即无异常）返回值为0，异常退出返回值为1，参数列表为2不代表有效的 Python 命令行。

请注意，如果引发了其他未处理的 SystemExit，只要未设置 Py_InspectFlag，该函数将不会返回 1，而是退出进程。

int Py_BytesMain(int argc, char **argv)

类似于 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，该函数使用 "???" 作为文件名。

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，只要未设置 Py_InspectFlag，该函数将不会返回 -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 应该是文件名，它是从文件系统编码（sys.getfilesystemencoding()）中解码出来的。 如果 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 从文件系统编码 (sys.getfilesystemencoding()) 解码。

成功执行输入时返回 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 从文件系统编码 (sys.getfilesystemencoding()) 解码。 在 EOF 处返回 0 或失败时返回负数。

int (*PyOS_InputHook)(void)

可以设置为指向具有原型 int func(void) 的函数。 当 Python 的解释器提示即将空闲并等待用户从终端输入时，将调用该函数。 返回值被忽略。 覆盖此钩子可用于将解释器的提示与其他事件循环集成，如 Python 源代码中的 Modules/_tkinter.c 中所做的那样。

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

可以设置为指向具有原型 char *func(FILE *stdin, FILE *stdout, char *prompt) 的函数，覆盖用于在解释器提示下读取单行输入的默认函数。 如果不是 NULL，函数应该输出字符串 prompt，然后从提供的标准输入文件中读取一行输入，返回结果字符串。 例如， readline 模块设置此挂钩以提供行编辑和制表符完成功能。

结果必须是由 PyMem_RawMalloc() 或 PyMem_RawRealloc() 或 NULL 分配的字符串（如果发生错误）。

3.4 版本变更：结果必须由PyMem_RawMalloc() 或PyMem_RawRealloc()分配，而不是由PyMem_X17(X)分配] 或 PyMem_Realloc()。

struct _node *PyParser_SimpleParseString(const char *str, int start)

这是下面 PyParser_SimpleParseStringFlagsFilename() 的简化接口，将 filename 设置为 NULL 并将 flags 设置为 0.

struct _node *PyParser_SimpleParseStringFlags(const char *str, int start, int flags)

这是下面 PyParser_SimpleParseStringFlagsFilename() 的简化接口，将 filename 设置为 NULL。

struct _node *PyParser_SimpleParseStringFlagsFilename(const char *str, const char *filename, int start, int flags)

根据 flags 参数，使用开始标记 start 从 str 解析 Python 源代码。 结果可用于创建可有效评估的代码对象。 如果必须多次评估代码片段，这将非常有用。 filename 从文件系统编码 (sys.getfilesystemencoding()) 解码。

struct _node *PyParser_SimpleParseFile(FILE *fp, const char *filename, int start)

这是下面 PyParser_SimpleParseFileFlags() 的简化接口，将 flags 设置为 0。

struct _node *PyParser_SimpleParseFileFlags(FILE *fp, const char *filename, int start, int flags)

类似于 PyParser_SimpleParseStringFlagsFilename()，但 Python 源代码是从 fp 读取的，而不是从内存中的字符串读取。

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 应该是文件名，它是从文件系统编码（sys.getfilesystemencoding()）中解码出来的。 如果 closeit 为真，则文件在 PyRun_FileExFlags() 返回之前关闭。

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

这是下面 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 是从文件系统编码 (os.fsdecode()) 解码的字节字符串。

3.2 版中的新功能。

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

这是 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)

评估一个预编译的代码对象，给定一个特定的评估环境。 该环境由全局变量字典、局部变量映射对象、参数数组、关键字和默认值、keyword-only 参数的默认值字典和单元闭包元组组成。

type PyFrameObject

用于描述框架对象的对象的 C 结构。 此类型的字段随时可能更改。

PyObject *PyEval_EvalFrame(PyFrameObject *f)

评估一个执行框架。 这是 PyEval_EvalFrameEx() 的简化接口，用于向后兼容。

PyObject *PyEval_EvalFrameEx(PyFrameObject *f, int throwflag)

这是 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 字段。

int CO_FUTURE_DIVISION

根据 PEP 238，可以在 flags 中设置该位，使除法运算符 / 被解释为“真正除法”。