非常高级的层 — Python 文档

来自菜鸟教程
Python/docs/3.7/c-api/veryhigh
跳转至:导航、​搜索

非常高级的层

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

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

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

int Py_Main(int argc, wchar_t **argv)

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

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

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()) 解码。 如果 filenameNULL,该函数使用 "???" 作为文件名。
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.ps1sys.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.ps1sys.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 参数,使用开始标记 startstr 解析 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)

在对象 globalslocals 指定的上下文中,使用 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_inputPy_file_inputPy_single_inputfilename 指定的文件名用于构造代码对象,并且可能出现在回溯或 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 解释的主要、未修饰的功能。 它实际上有 2000 行长。 与执行帧 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 *flagsNULL 时,cf_flags 被视为等于 0,并丢弃因 from __future__ import 引起的任何修改。

struct PyCompilerFlags {
    int cf_flags;
}
int CO_FUTURE_DIVISION
根据 PEP 238,可以在 flags 中设置该位,使除法运算符 / 被解释为“真正除法”。