非常高级的层 — 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 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 读取的,而不是从内存中的字符串读取。
- 这是下面 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 版中的新功能。
- 这是 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 *flags
为NULL
时,cf_flags
被视为等于0
,并丢弃因from __future__ import
引起的任何修改。struct PyCompilerFlags { int cf_flags; }
- int CO_FUTURE_DIVISION
- 根据 PEP 238,可以在 flags 中设置该位,使除法运算符
/
被解释为“真正除法”。