极高层级 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)
    *返回值：新的引用。*

   在由 *globals* 和 *locals* 对象指定的上下文中执行 *str* 中的 Python
   源代码并使用由 *flags* 指定的编译器旗标。 *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* 应为文件名，它将使用 *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_ALLOW_INCOMPLETE_INPUT

      此旗标是编译器和 "codeop" 模块之间的一个私有接口。 请不要使用它
      ；它的行为不受支持并可能不加警告地发生改变。

      在设置此旗标的情况下，当编译因源文本在预期有更多输入的位置结束而
      失败时，例如在缩进代码块或未结束字符串字面值的中间，被引发的错误
      是未写入文档的 "_IncompleteInputError"，它是 "SyntaxError" 的子
      类。 "codeop" 模块会设置此旗标，并与 "PyCF_DONT_IMPLY_DEDENT" 一
      起，以将不完整的输入与具有真正语法错误的输入区分开来，从而使交互
      式解释器能知道何时应当提示输入下一行而不是报告错误。

      Added in version 3.11.

   PyCF_DONT_IMPLY_DEDENT

      在默认情况下，当附带 "Py_single_input" 开始符号进行编译时，到达
      源文本末尾会隐式地关闭任何已打开的缩进代码块。 当设置此旗标时，
      已打开的代码块只有在源文本的最后一行是以换行符结尾时才会被关闭；
      否则的话，编译将失败并引发 "SyntaxError":

         PyCompilerFlags flags = {
             .cf_flags = 0,
             .cf_feature_version = PY_MINOR_VERSION,
         };
         const char *source = "if a:\n    pass";

         /* "if" 代码块隐式地关闭；
            这将返回一个代码对象: */
         Py_CompileStringFlags(source, "<input>", Py_single_input, &flags);

         /* 当设置旗标时，这将失败并引发 SyntaxError，
            因为最后一行不是以换行符结束的: */
         flags.cf_flags = PyCF_DONT_IMPLY_DEDENT;
         Py_CompileStringFlags(source, "<input>", Py_single_input, &flags);

      "codeop" 模块使用此旗标来检测不完整的交互式输入。 当用户还在缩进
      代码块中输入内容，源代码尚未以换行符结束，因此编译失败并将提示用
      户输入下一行。

   PyCF_IGNORE_COOKIE

      Read the source text as UTF-8, ignoring its **PEP 263** encoding
      declaration ("coding cookie"), if any:

         PyCompilerFlags flags = {
             .cf_flags = 0,
             .cf_feature_version = PY_MINOR_VERSION,
         };
         const char *source = "# coding: latin-1\ns = '\xe9'\n";

         /* The coding cookie is honored: byte 0xE9 is decoded as
            Latin-1, and this returns a code object that sets s to "é": */
         Py_CompileStringFlags(source, "<input>", Py_file_input, &flags);

         /* With the flag, the cookie is ignored and compilation fails
            with a SyntaxError, because 0xE9 is not valid UTF-8: */
         flags.cf_flags = PyCF_IGNORE_COOKIE;
         Py_CompileStringFlags(source, "<input>", Py_file_input, &flags);

      The "compile()", "eval()" and "exec()" built-in functions set
      this flag when the source is a "str" object, because they pass
      the text to the parser encoded as UTF-8.

   PyCF_SOURCE_IS_UTF8

      Mark the source text as known to be UTF-8 encoded. The
      "compile()", "eval()" and "exec()" built-in functions set this
      flag, but it currently has no effect.

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

   以下掩码组合了多个旗标：

   PyCF_MASK

      Bitmask of all "CO_FUTURE" flags (see 代码对象标志), which
      select features normally enabled by future statements. When code
      compiled with a "PyCompilerFlags *flags" argument contains a
      "from __future__ import" statement, the flag for the imported
      feature is added to *flags*, so that code executed later in the
      same context inherits it.

   PyCF_MASK_OBSOLETE

      Do not use this mask in new code.  It is kept only so that old
      code passing its flags to "compile()" keeps working.

      Bitmask of flags for obsolete future features that no longer
      have any effect.

   PyCF_COMPILE_MASK

      Bitmask of all "PyCF" flags that change how the source is
      compiled, such as "PyCF_ONLY_AST". The "compile()" built-in
      function uses this mask to validate its *flags* argument.


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

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.
