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

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

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

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

int Py_Main(int argc, wchar_t **argv)

   针对标准解释器的主程序。 嵌入了 Python 的程序将可使用此程序。 所提
   供的 *argc* 和 *argv* 形参应当与传给 C 程序的 "main()" 函数的形参相
   同（将根据用户的语言区域转换为）。 一个重要的注意事项是参数列表可能
   会被修改（但参数列表中字符串所指向的内容不会被修改）。 如果解释器正
   常退出（即未引发异常）则返回值将为 "0"，如果解释器因引发异常而退出
   则返回 "1"，或者如果形参列表不能表示有效的 Python 命令行则返回 "2"
   。

   请注意如果引发了一个在其他场合下未处理的 "SystemExit"，此函数将不会
   返回 "1"，而是退出进程，只要 "Py_InspectFlag" 还未被设置。

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"
   ，此函数会使用 ""???"" 作为文件名。 如果 *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"，而是退出进程，只要 "Py_InspectFlag" 还未被设置。

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)

   Similar to "PyRun_SimpleStringFlags()", but the Python source code
   is read from *fp* instead of an in-memory string. *filename* should
   be the name of the file, it is decoded from the filesystem encoding
   ("sys.getfilesystemencoding()").  If *closeit* is true, the file is
   closed before PyRun_SimpleFileExFlags returns.

   備註:

     在 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)

   Read and execute a single statement from a file associated with an
   interactive device according to the *flags* argument.  The user
   will be prompted using "sys.ps1" and "sys.ps2".  *filename* is
   decoded from the filesystem encoding
   ("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)

   Read and execute statements from a file associated with an
   interactive device until EOF is reached.  The user will be prompted
   using "sys.ps1" and "sys.ps2".  *filename* is decoded from the
   filesystem encoding ("sys.getfilesystemencoding()").  Returns "0"
   at EOF or a negative number upon failure.

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)" 的函数，重写被用来读取解释器提示符的一行输入的默认函
   数。 该函数被预期为如果字符串 *prompt* 不为 "NULL" 就输出它，然后从
   所提供的标准输入文件读取一行输入，并返回结果字符串。 例如，
   "readline" 模块将这个钩子设置为提供行编辑和 tab 键补全等功能。

   结果必须是一个由 "PyMem_RawMalloc()" 或 "PyMem_RawRealloc()" 分配的
   字符串，或者如果发生错误则为 "NULL"。

   3.4 版更變: 结果必须由 "PyMem_RawMalloc()" 或 "PyMem_RawRealloc()"
   分配，而不是由 "PyMem_Malloc()" 或 "PyMem_Realloc()" 分配。

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

   This is a simplified interface to
   "PyParser_SimpleParseStringFlagsFilename()" below, leaving
   *filename* set to "NULL" and *flags* set to "0".

   Deprecated since version 3.9, will be removed in version 3.10.

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

   This is a simplified interface to
   "PyParser_SimpleParseStringFlagsFilename()" below, leaving
   *filename* set to "NULL".

   Deprecated since version 3.9, will be removed in version 3.10.

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

   Parse Python source code from *str* using the start token *start*
   according to the *flags* argument.  The result can be used to
   create a code object which can be evaluated efficiently. This is
   useful if a code fragment must be evaluated many times. *filename*
   is decoded from the filesystem encoding
   ("sys.getfilesystemencoding()").

   Deprecated since version 3.9, will be removed in version 3.10.

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

   This is a simplified interface to "PyParser_SimpleParseFileFlags()"
   below, leaving *flags* set to "0".

   Deprecated since version 3.9, will be removed in version 3.10.

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

   Similar to "PyParser_SimpleParseStringFlagsFilename()", but the
   Python source code is read from *fp* instead of an in-memory
   string.

   Deprecated since version 3.9, will be removed in version 3.10.

PyObject* PyRun_String(const char *str, int start, PyObject *globals, PyObject *locals)
    *Return value: New reference.*

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

PyObject* PyRun_StringFlags(const char *str, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)
    *Return value: New reference.*

   在由对象 *globals* 和 *locals* 指定的上下文中执行来自 *str* 的
   Python 源代码，并使用以 *flags* 指定的编译器旗标。 *globals* 必须是
   一个字典；*locals* 可以是任何实现了映射协议的对象。 形参 *start* 指
   定了应当被用来解析源代码的起始形符。

   返回将代码作为 Python 对象执行的结果，或者如果引发了异常则返回
   "NULL"。

PyObject* PyRun_File(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals)
    *Return value: New reference.*

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

PyObject* PyRun_FileEx(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit)
    *Return value: New reference.*

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

PyObject* PyRun_FileFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)
    *Return value: New reference.*

   这是针对下面 "PyRun_FileExFlags()" 的简化版接口，将 *closeit* 设为
   "0"。

PyObject* PyRun_FileExFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit, PyCompilerFlags *flags)
    *Return value: New reference.*

   Similar to "PyRun_StringFlags()", but the Python source code is
   read from *fp* instead of an in-memory string. *filename* should be
   the name of the file, it is decoded from the filesystem encoding
   ("sys.getfilesystemencoding()"). If *closeit* is true, the file is
   closed before "PyRun_FileExFlags()" returns.

PyObject* Py_CompileString(const char *str, const char *filename, int start)
    *Return value: New reference.*

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

PyObject* Py_CompileStringFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags)
    *Return value: New reference.*

   这是针对下面 "Py_CompileStringExFlags()" 的简化版接口，将
   *optimize* 设为 "-1"。

PyObject* Py_CompileStringObject(const char *str, PyObject *filename, int start, PyCompilerFlags *flags, int optimize)
    *Return value: New reference.*

   解析并编译 *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)
    *Return value: New reference.*

   Like "Py_CompileStringObject()", but *filename* is a byte string
   decoded from the filesystem encoding ("os.fsdecode()").

   3.2 版新加入.

PyObject* PyEval_EvalCode(PyObject *co, PyObject *globals, PyObject *locals)
    *Return value: New reference.*

   这是针对 "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)
    *Return value: New reference.*

   对一个预编译的代码对象求值，为其求值给出特定的环境。 此环境由全局变
   量的字典，局部变量映射对象，参数、关键字和默认值的数组，仅限关键字
   参数的默认值的字典和单元的封闭元组构成。

PyFrameObject

   用于描述帧对象的 C 对象结构体。 此类型的字段可能在任何时候被改变。

PyObject* PyEval_EvalFrame(PyFrameObject *f)
    *Return value: New reference.*

   对一个执行帧求值。 这是针对 "PyEval_EvalFrameEx()" 的简化版接口，用
   于保持向下兼容性。

PyObject* PyEval_EvalFrameEx(PyFrameObject *f, int throwflag)
    *Return value: New reference.*

   这是 Python 解释运行不带修饰的主函数。 与执行帧 *f* 相关联的代码对
   象将被执行，解释字节码并根据需要执行调用。 额外的 *throwflag* 形参
   基本可以被忽略 —— 如果为真值，则会导致立即抛出一个异常；这会被用于
   生成器对象的 "throw()" 方法。

   3.4 版更變: 该函数现在包含一个调试断言，用以确保不会静默地丢弃活动
   的异常。

int PyEval_MergeCompilerFlags(PyCompilerFlags *cf)

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

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

   这个标志位可在 *flags* 中设置以使得除法运算符 "/" 被解读为 **PEP
   238** 所规定的“真除法”。
