2014-04-12

使用C语言编写Python扩展1——Hello World

能够使用C语言编写扩展是Python一大卖点吧，这可以将一些关键的代码使用C来写以提升程序的性能。本文是参考了Python的官方文档整理而来的，同时结合了Python2跟Python3。按照惯例现在先从一个Hello World开始讲解一下写扩展的基本流程。

详细的内容可以参考官方文档：

https://docs.python.org/2.7/extending/index.html

https://docs.python.org/3/extending/index.html

https://docs.python.org/2.7/c-api/index.html

https://docs.python.org/3/c-api/index.html

同时本文中的示例代码可从 https://github.com/wusuopu/python-c-extension-sample 获取到。

首先介绍一下我当前的开发环境：

ArchLinux
gcc 4.8.2
glibc 2.19
Python 2.7.6
Python 3.3.5

开始

先创建一个新的C代码文件 lc_hello.c。为了能够正常使用python的api，需要导入Python.h这个头文件。
```
#include <Python.h>
```
然后再定义一个模块的初始化函数。
```
PyMODINIT_FUNC initlc_hello_world(void)
{
 Py_InitModule(“lc_hello_world”, lc_hello_world_methods);
 printf(“init lc_hello_world module\n”);
}
```
这个函数是用于模块初始化的，即是在第一次使用import语句导入模块时会执行。其函数名必须为initmodule_name这样的格式，在这里我们的模块名为lc_hello_world，所以函数名就是initlc_hello_world。

在这个函数中又调用了Py_InitModule函数，它执行了模块初始化的操作。Py_InitModule函数传入了两个参数，第一个参数为字符串，表示模块的名称；第二个参数是一个PyMethodDef的结构体数组，表示该模块都具有哪些方法。与Py_InitModule相似的方法还有Py_InitModule3和Py_InitModule4。因此在initlc_hello_world方法之前还需要先定义 lc_hello_world_methods 数组。
```
static PyMethodDef lc_hello_world_methods[] = {
 {“test”, (PyCFunction)test_function, METH_NOARGS, “lc_hello_world extending test”},
 {“add”, (PyCFunction)add_function, METH_VARARGS, NULL},
 {NULL, NULL, 0, NULL}
};
```
PyMethodDef结构体有四个字段。
- 第一个是一个字符串，表示在Python中对应的方法的名称；
- 第二个是对应的C代码的函数；
- 第三个是一个标致位，表示该Python方法是否需要参数，METH_NOARGS表示不需要参数，METH_VARARGS表示需要参数；
- 第四个是一个字符串，它是该方法的doc属性，这个不是必须的，可以为NULL。
  
  PyMethodDef结构体数组最后以 {NULL, NULL, 0, NULL}结尾。（感觉好像不是必须的，但是通常都这么做那我们也这么做吧）
  
  注意：以上的用法都是针对Python2的，在Python3中又有些不同。
  
  在Python3中模块的初始化函数的函数名变为了PyInit_module_name这样的形式了，因此这里就需要定义一个函数 PyMODINIT_FUNC PyInit_lc_hello_world。并且还需要返回一个 module 类型的变量。
  
  其次在Python3中创建module对象的函数也由 Py_InitModule 变为了 PyModule_Create。
  
  因此在Python3中模块的初始化函数应该定义如下：
```
PyMODINIT_FUNC PyInit_lc_hello_world(void)
{
PyObject m;
m = PyModule_Create(&lc_hello_world_module);
if (m == NULL)
   return NULL;
printf(“init lc_hello_world module\n”);
return m;
}
```
  PyModule_Create函数需要传入一个 PyModuleDef 类型的指针。
  
  因此在此之前还需要先定义 lc_hello_world_module 变量。
```
static struct PyModuleDef lc_hello_world_module = {
PyModuleDef_HEAD_INIT,
“lc_hello_world”,        / name of module /
NULL,                    / module documentation, may be NULL /
-1,                      / size of per-interpreter state of the module, or -1 if the module keeps state in global variables. /
lc_hello_world_methods   / A pointer to a table of module-level functions, described by PyMethodDef values. Can be NULL if no functions are present. /
};
```
  在 lc_hello_world_methods 中我们为模块指定了两个方法，接下来我们需要实现这两个方法。
```
static PyObject test_function(PyObject self)
{
PyObject_Print(self, stdout, 0);
printf(“lc_hello_world test\n”);
Py_INCREF(Py_True);
return Py_True;
}
```
  这段代码定义了Python的test方法所对应的C函数。在这个函数中就只执行了一条printf语句，然后就返回了Py_True。
  
  Py_True即是Python中的True，Py_INCREF函数执行的操作是对Python对象的计数引用值进行加1。与Py_INCREF对应的是Py_DECREF，它是对计数引用减1,并且计数引用为0时就销毁对象并回收内存。
```
static PyObject add_function(PyObject self, PyObject args)
{
int num1, num2;
PyObject result=NULL;
if (!PyArg_ParseTuple(args, “nn”, &num1, &num2)) {
   printf(“传入参数错误！\n”);
   return NULL;
}
result = PyInt_FromLong(num1+num2);
return result;
}
```
  这须代码定义了Python的add方法所对应的C函数。该函数需要传入两个整数类型的参数。
  
  PyArg_ParseTuple是对传入的参数进行解析，关于这个函数的说明请查看Python手册。
  
  注意：在Python3中整数都是 long 类型的，因此这里的 PyInt_FromLong 需要改为 PyLong_FromLong，其作用是将C的int类型转为Python的int类型。
  
  编译
  
  扩展模块编写完成后，接下来就是对其进行编译了。先编写一个 setup.py 脚本。
```
#!/usr/bin/env python
#-- coding:utf-8 -*-
```


from setuptools import setup, Extension

hello_world = Extension(‘lc_hello_world’, sources=[“lc_hello.c”]) setup(ext_modules=[hello_world])

然后再执行命令进行编译：

$ python setup.py build

执行成功后会在当前目录下的build目录中生成扩展模块文件。

测试

最后就是编写一个小程序来测试刚刚的模块是否可用。

import lc_hello_world

print(lc_hello_world.test.__doc__)
print(lc_hello_world.add.__doc__)
print(lc_hello_world.test())
print(lc_hello_world.add(1, 2))
print(lc_hello_world.add(1, '2'))    # 这个会报错