极高层级 API
************

本章节的函数将允许你执行在文件或缓冲区中提供的 Python 源代码，但它们将
不允许你以更细节化的方式与解释器进行交互。

这些函数中有几个可以接受特定的语法起始符号作为形参。可用的起始符号有
"Py_eval_input", "Py_file_input", "Py_single_input" 和
"Py_func_type_input"。这些符号会在接受它们作为形参的函数中加以说明。

还要注意这些函数中有几个可以接受 FILE* 形参。有一个需要小心处理的特别
问题是针对不同 C 库的 "FILE" 结构体可能是不相同且不兼容的。 （至少是）
在 Windows 中，动态链接的扩展实际上有可能会使用不同的库，所以应当特别
注意只有在确定这些函数是由 Python 运行时所使用的相同的库创建的情况下才
将 FILE* 形参传给它们。

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__" 模块中执行 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* 应为文件名，它将使用
   *filesystem encoding and error handler* 来解码。如果 *closeit* 为真
   值，则文件将在 "PyRun_SimpleFileExFlags()" 返回之前被关闭。

   备注:

     在 Windows 上，*fp* 应当以二进制模式打开 (即 "fopen(filename,
     "rb")")。否则，Python 可能无法正确地处理使用 LF 行结束符的脚本文
     件。

int PyRun_InteractiveOneObject(FILE *fp, PyObject *filename, PyCompilerFlags *flags)

   根据 *flags* 参数读取并执行来自与交互设备相关联的文件的一条语句。用
   户将得到使用 "sys.ps1" 和 "sys.ps2" 的提示。 *filename* 必须是一个
   Python "str" 对象。

   当输入被成功执行时返回 "0"，如果引发异常则返回 "-1"，或者如果存在解
   析错误则返回来自作为 Python 的组成部分发布的 "errcode.h" 包含文件的
   错误代码。 （请注意 "errcode.h" 并未被 "Python.h" 所包含，因此如果
   需要则必须专门地包含。）

int PyRun_InteractiveOne(FILE *fp, const char *filename)

   这是针对下面 "PyRun_InteractiveOneFlags()" 的简化版接口，将 *flags*
   设为 "NULL"。

int PyRun_InteractiveOneFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)

   类似于 "PyRun_InteractiveOneObject()"，但 *filename* 是一个 const
   char*，它使用 *filesystem encoding and error handler* 来解码。

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* 将使用 *filesystem
   encoding and error handler* 来解码。当位于 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" 模块将这个钩子设置为提供行编辑和 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)
    *返回值：新的引用。*

   Execute Python source code from *str* in the context specified by
   the objects *globals* and *locals* with the compiler flags
   specified by *flags*.  *globals* must be a dictionary; *locals* can
   be any object that implements the mapping protocol.  The parameter
   *start* specifies the start symbol and must be one of the available
   start symbols.

   返回将代码作为 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* 应为文件名，它将使用 *filesystem
   encoding and error handler* 来解码。如果 *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* 给出；这可用于约束可编译的代码并且应当是 可用的起始符号。由
   *filename* 指定的文件名将被用来构建代码对象并可能出现在回溯或
   "SyntaxError" 异常消息中。如果代码无法被解析或编译则返回 "NULL"。

   整数 *optimize* 指定编译器的优化级别；值 "-1" 将选择与 "-O" 选项相
   同的解释器优化级别。显式级别为 "0" (无优化；"__debug__" 为真值)、
   "1" (断言被移除，"__debug__" 为假值) 或 "2" (文档字符串也被移除)。

   Added in version 3.4.

PyObject *Py_CompileStringExFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags, int optimize)
    *返回值：新的引用。*

   与 "Py_CompileStringObject()" 类似，但 *filename* 是一个字节串，使
   用 *filesystem encoding and error handler* 来解码。

   Added in version 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)

   此函数会修改当前求值帧的旗标，并在成功时返回真值，失败时返回假值。

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

      请参阅 "ast" Python 模块文档中的 编译器旗标，它们会将这些常量以
      相同的名称导出。

   上述 ""PyCF"" 旗标可与 ""CO_FUTURE"" 类旗标如
   "CO_FUTURE_ANNOTATIONS" 组合使用，以启用通常通过 future 语句 选择的
   功能特性。完整旗标列表请参见 代码对象标志.


可用的起始符号
==============

int Py_eval_input

   Python 语法中用于孤立表达式的起始符号；配合 "Py_CompileString()" 使
   用。

int Py_file_input

   Python 语法中用于从文件或其他源读取语句序列的起始符号；配合
   "Py_CompileString()" 使用。这是在编译任意长的 Python 源代码时要使用
   的符号。

int Py_single_input

   Python 语法中用于单独语句的起始符号；配合 "Py_CompileString()" 使用
   。这是用于交互式解释器循环的符号。

int Py_func_type_input

   Python 语法中用于函数类型的起始符号；配合 "Py_CompileString()" 使用
   。这是用于解析来自 **PEP 484** 的 "签名类型注释"。

   这需要设置 "PyCF_ONLY_AST" 旗标。

   参见:

     * "ast.FunctionType"

     * **PEP 484**

   Added in version 3.8.


栈影响
======

参见: "dis.stack_effect()"

PY_INVALID_STACK_EFFECT

   代表无效栈影响的哨兵值。

   目前这等价于 "INT_MAX"。

   Added in version 3.8.

int PyCompile_OpcodeStackEffect(int opcode, int oparg)

   使用参数 *oparg* 计算 *opcode* 的栈影响。

   成功时，此函数返回栈影响；失败时，则返回 "PY_INVALID_STACK_EFFECT"
   。

   Added in version 3.4.

int PyCompile_OpcodeStackEffectWithJump(int opcode, int oparg, int jump)

   类似于 "PyCompile_OpcodeStackEffect()"，但不包括当 *jump* 为零时的
   跳转的栈影响。

   如果 *jump* 为 "0"，这将不包括跳转的栈影响，但如果 *jump* 为 "1" 或
   "-1"，这将会包括它。

   成功时，此函数返回栈影响；失败时，则返回 "PY_INVALID_STACK_EFFECT"
   。

   Added in version 3.8.
