Extending and Embedding the Python Interpreter(四)

I promised to show how spam_system() is called from Python programs. First, we need to list its name and address in a ``method table'':

 

static PyMethodDef SpamMethods[] = {
    ...
    {"system",  spam_system, METH_VARARGS,
     "Execute a shell command."},
    ...
    {NULL, NULL, 0, NULL}        /* Sentinel */
};

Note the third entry ("METH_VARARGS"). This is a flag telling the interpreter the calling convention to be used for the C function. It should normally always be "METH_VARARGS" or "METH_VARARGS | METH_KEYWORDS"; a value of 0 means that an obsolete variant of PyArg_ParseTuple() is used.

现在我们来看一下如何在python函数中调用spam_system()。首先我们需要在一个方法表中列出spam_system()的名称和地址。注意第三个参数("METH_VARARGS")，它是一个标记，用来同志编译器需要调用的是一个C代码函数。通常来说这个参数会写成"METH_VARARGS" 或者 "METH_VARARGS | METH_KEYWORDS"；

When using only "METH_VARARGS", the function should expect the Python-level parameters to be passed in as a tuple acceptable for parsing via PyArg_ParseTuple(); more information on this function is provided below.

如果只使用"METH_VARARGS"作为参数，那么那么函数会希望通过PyArg_ParseTuple()函数来将python中传入的参数进行解析。

The METH_KEYWORDS bit may be set in the third field if keyword arguments should be passed to the function. In this case, the C function should accept a third "PyObject *" parameter which will be a dictionary of keywords. Use PyArg_ParseTupleAndKeywords() to parse the arguments to such a function.

如果在第三个参数中加入METH_KEYWORDS的话，那么在函数参数中就需要传入关键字参数。在这种情况下，这个C函数需要接受一个PyObject指针参数作为它的第三个参数。使用PyArg_ParseTupleAndKeywords()去解析这种函数的参数。

The method table must be passed to the interpreter in the module's initialization function. The initialization function must be named initname(), where name is the name of the module, and should be the only non-static item defined in the module file:

这个方发表必须在模块的初始化函数中被传入解析器。这个初始化函数必须被命名为initname()，这里的name就是这个模块的名称，而这个函数应该是这个模块文件中唯一的非静态元素。

 

PyMODINIT_FUNC
initspam(void)
{
    (void) Py_InitModule("spam", SpamMethods);
}

Note that PyMODINIT_FUNC declares the function as void return type, declares any special linkage declarations required by the platform, and for C++ declares the function as extern "C".

注意PyMODINIT_FUNC声明这个函数没有返回值。

When the Python program imports module spam for the first time, initspam() is called. (See below for comments about embedding Python.) It calls Py_InitModule(), which creates a ``module object'' (which is inserted in the dictionary sys.modules under the key "spam"), and inserts built-in function objects into the newly created module based upon the table (an array of PyMethodDef structures) that was passed as its second argument. Py_InitModule() returns a pointer to the module object that it creates (which is unused here). It aborts with a fatal error if the module could not be initialized satisfactorily, so the caller doesn't need to check for errors.

当python程序第一次导入spam模块的时候，initspam()函数被调用。它被称作Py_InitModule()，它创建一个模块对象（这个模块将被插入到sys模块的字典中，使用spam作为关键字），另外基于方法映射表将那些方法加入到这个新创建的模块对象中。Py_InitModule()返回一个指向模块对象的指针。如果模块不能被满意的初始化，那么这个函数会产生一个fatal error将程序中止，所以函数的调用者没有必要去检查错误。

When embedding Python, the initspam() function is not called automatically unless there's an entry in the _PyImport_Inittab table. The easiest way to handle this is to statically initialize your statically-linked modules by directly calling initspam() after the call to Py_Initialize():

当在C代码中嵌入python时，initspam()函数不会被自动执行，最简单的办法是在调用Py_Initialize()函数后直接调用initspam()函数，就像下面的程序那样：

int
main(int argc, char *argv[])
{
    /* Pass argv[0] to the Python interpreter */
    Py_SetProgramName(argv[0]);

    /* Initialize the Python interpreter.  Required. */
    Py_Initialize();

    /* Add a static module */
    initspam();