[Python源码学习]之Very High Level Layer

Python手册 Very High Level Layer 一节给出高层的 API 接口函数。

Py_Main(...)	这个？最顶层的接口了
PyRun_***（...）	运行位于字符串或文件(包括标准输入)中的代码
PyParser_***(...)	parser字符串或文件
Py_CompileString***（...）	parser + compile
PyEval_Eval***（...）	执行(evaluate)编译后的PyCodeObject或可执行的PyFrameObject
Py_***_input	3个宏，3个整数
PyCompilerFlags	结构体，存放编译选项
PyEval_MergeCompilerFlags	与当前帧的编译选项合并

Py_Main

源码：Python/pythonrun.c

这个函数我们已经多次看到了，不用多说了。

• The main program for the standard interpreter. This is made available for programs which embed Python.

PyRun_***

源码：Python/pythonrun.c

PyRun_SimpleStringFlags(...)	执行字符串中的代码
PyRun_StringFlags(...)
PyRun_AnyFileExFlags(...)	执行文件(普通文件+标准输入)中的代码
PyRun_InteractiveLoopFlags(...)		交互式执行
PyRun_InteractiveOneFlags(...)
PyRun_SimpleFileExFlags(...)
PyRun_FileExFlags(...)

• 这些函数函数均有马甲若干，比如PyRun_FileExFlags有马甲：PyRun_File 等

• 带Simple的函数是对应函数的便利版本。

马甲函数

• PyRun_AnyFile(FILE *fp, const char *filename)

• PyRun_AnyFileFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)

• PyRun_AnyFileEx(FILE *fp, const char *filename, int closeit)

• PyRun_AnyFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)

前面3个是最后一个的马甲，只是使用了某些默认值而已。比如：

PyAPI_FUNC(int)
PyRun_AnyFile(FILE *fp, const char *name)
{
    return PyRun_AnyFileExFlags(fp, name, 0, NULL);
}

Simple...

带Simple的是对应的不带的函数的便利版本，它和前面提到的马甲不同！

比如：

• int PyRun_SimpleStringFlags(const char *command, PyCompilerFlags *flags)

• PyObject* PyRun_StringFlags(const char *str, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)

尽管前者调用后者，但需要先提供一些默认的 globals、locals。源码：

int
PyRun_SimpleStringFlags(const char *command, PyCompilerFlags *flags)
{
    PyObject *m, *d, *v;
    m = PyImport_AddModule("__main__");
    if (m == NULL)
        return -1;
    d = PyModule_GetDict(m);
    v = PyRun_StringFlags(command, Py_file_input, d, d, flags);
    if (v == NULL) {
        PyErr_Print();
        return -1;
    }
    Py_DECREF(v);
    return 0;
}

PyParser_***

PyParser_SimpleParseStringFlagsFilename(...)	从字符串中parse
PyParser_SimpleParseFileFlags(...)	从文件内容parse

这两个函数各有马甲 二、三个。

另外，和前面的PyRun_*类似，也有不带Simple的对应版本。

• PyParser_ParseStringFlagsFilename(...)

• PyParser_ParseFileFlags(...)

注：

• Manual中并没有提到这两个函数，可见不属于高级接口
• 在Parser/parsertok.c

调用关系：

node *
PyParser_SimpleParseFileFlags(FILE *fp, const char *filename, int start, int flags)
{
    perrdetail err;
    node *n = PyParser_ParseFileFlags(fp, filename, NULL,
                                      &_PyParser_Grammar,
                                      start, NULL, NULL, &err, flags);
    if (n == NULL)
        err_input(&err);

    return n;
}

Py_CompileString***

PyObject* Py_CompileStringExFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags, int optimize)

• 有马甲两个
• 执行 parse 和 compile 两个子步骤，源码如下：

PyObject *
Py_CompileStringExFlags(const char *str, const char *filename, int start,
                        PyCompilerFlags *flags, int optimize)
{
    PyCodeObject *co;
    mod_ty mod;
    PyArena *arena = PyArena_New();
...
    mod = PyParser_ASTFromString(str, filename, start, flags, arena);
...
    co = PyAST_CompileEx(mod, filename, flags, optimize, arena);
    PyArena_Free(arena);
    return (PyObject *)co;
}

PyEval_Eval***

源码：Python/ceval.c

PyEval_EvalCodeEx	执行(evaluate)预编译的代码对象：PyCodeObject
PyEval_EvalFrameEx	执行(evaluate)可执行的frame：PyFrameObject

两个函数各有马甲一个。

Py_***_input

• Py_single_input
• Py_file_input
• Py_eval_input

额，这只是3个宏，定义在 Include/Python.h 中：

/* These definitions must match corresponding definitions in graminit.h.
   There's code in compile.c that checks that they are the same. */
#define Py_single_input 256
#define Py_file_input 257
#define Py_eval_input 258

其他

• PyCompilerFlags

一个结构体(源码 Python/pythonrun.c)，顾名思义，用来存放编译选项

typedef struct {
    int cf_flags;  /* bitmask of CO_xxx flags relevant to future */
} PyCompilerFlags;

可用的选项定义在 Include/code.h 中：

#define CO_FUTURE_DIVISION      0x2000
#define CO_FUTURE_ABSOLUTE_IMPORT 0x4000 /* do absolute imports by default */
#define CO_FUTURE_WITH_STATEMENT  0x8000
#define CO_FUTURE_PRINT_FUNCTION  0x10000
#define CO_FUTURE_UNICODE_LITERALS 0x20000

• PyEval_MergeCompilerFlags

合并当前帧的 CompilerFlags，源码 Python/ceval.c :

int PyEval_MergeCompilerFlags(PyCompilerFlags *cf)
{
    PyFrameObject *current_frame = PyEval_GetFrame();
    int result = cf->cf_flags != 0;

    if (current_frame != NULL) {
        const int codeflags = current_frame->f_code->co_flags;
        const int compilerflags = codeflags & PyCF_MASK;
        if (compilerflags) {
            result = 1;
            cf->cf_flags |= compilerflags;
        }
    }
    return result;
}

参考

• http://docs.python.org/py3k/c-api/veryhigh.html