Python：C语言扩展

1. 概述

Python 可以非常方便地和 C 进行相互的调用。

一般，我们不会使用 C 去直接编写一个 Python 的模块。通常的情景是，我们需要把 C 的相关模块包装一下，然后在 Python 中可以直接调用它。或者是，把 Python 逻辑中的某一效率要求很高的部分使用 C 来实现。整个过程大概是：

引入 Python.h 头文件。

编写包装函数。

函数中处理从 Python 传入的参数。

实现功能逻辑。

处理 C 中的返回值，包装成 Python 对象。

在一个 PyMethodDef 结构体中注册需要的函数。

在一个初始化方法中注册模块名。

把这个 C 源文件编译成链接库。

int add(int x, int y){
return x + y;
}

//int main(void){
//    printf("%d", add(1, 2));
//    return 0;
//}

#include<Python.h>

static PyObject* W_add(PyObject* self, PyObject* args){
int x;
int y;
if(!PyArg_ParseTuple(args, "i|i", &x, &y)){
return NULL;
} else {
return Py_BuildValue("i", add(x, y));
}
}

static PyMethodDef ExtendMethods[] = {
{"add", W_add, METH_VARARGS, "a function from C"},
{NULL, NULL, 0, NULL},
};

PyMODINIT_FUNC initdemo(){
Py_InitModule("demo", ExtendMethods);
}

2. 引入 Python.h 头文件

这个文件一般位于 Python 的主目录中。比如我的 Ubuntu 10.04 下，它的位置在：

/usr/include/python2.6

在最后编译的时候指定目录就可以了。

3. 编写包装函数

因为 Python 用到的函数与普通的 C 函数，在输入和输出上，会有一些不同，所以，我们需要把普通的 C 做一些封来给 Python 用。

从另一方面来说，在实现功能的过程中，我们可以先完全不考虑这东西是拿给 Python 用的，只专注于使用 C 把它写好就可以了。最后，功能写好，测试没有问题之后，再做 Python 封装的工作。

包装函数一般声明成 static ，并且第一个参数是一个默认传入的 Python 对象，就是 Python 中某个对象的属性方法一样，第二个参数才是我们调用时传入的参数（实际上它是一个序列化后的字符串）：

static PyObject* W_add(PyObject* self, PyObject* args);

4. 处理从 Python 传入的参数

因为我们的相关函数，之后是在 Python 环境中被调用的，那么它显然接受的就是从 Python 环境下传入的参数。这和 C 中你看到的函数是不同的，在 Python 的世界中，一切都是对象。所以，包装函数中首先要处理的问题就是解析从 Python 占获取的参数。

常用的函数有： PyArg_ParseTuple

int x;
int y;
PyArg_ParseTuple(args, "i|i", &x, &y);

PyArg_ParseTuple 的作用是解析我们从 Python 中传入的 args 这个字符串，然后以我们规定的格式将解析结果放入指定变量的内存位。

" i|i " 就表示要把传入的东西解析成两个整数，同样，还有 s 表示字符串等。

5. 实现逻辑功能

这部分没什么特别的，只需要在 C 中一样调用函数就可以了，相关变量我们已经在上一步处理过了。

add(x, y);

6. 处理 C 中的返回值

我们使用 C 完成了功能逻辑， C 中会产生一个返回值，要将这个值返回到我们之前调用函数的 Python 环境中，当然还需要经过一些处理才行。

常用的函数是： Py_BuildValue 。

return Py_BuildValue("i", add(x, y));

这个函数的用法和上一步中的 PyArg_ParseTuple 是一样的，它们过程相反。 Py_BuildValue 把 C 中的值按给定的格式格式化成 Python 需要的对象。这里注意一下，对于 W_add 这个函数，我们可是声明了它的返回类型为 PyObject* 的哦。

7. 注册函数

在上面的实现完成之后，就需要作导出的准备了。第一步，就是要在一个类型为 PyMethodDef 的结构体中注册我们需要导出到 Python 中的函数：

static PyMethodDef ExtendMethods[] = {
{"add", W_add, METH_VARARGS, "a function from C"},
{NULL, NULL, 0, NULL},
}

这个结构体成员有四个函数：

" add " 导出后在 Pyhton 中可见的方法名。

W_add 实际映射到 C 中的方法名。

METH_VARARGS 表示传入方法的是普通参数，当然还可以处理关键词参数。

此方法的注释。

8. 注册模块

在注册了方法后，就要注册此模块了。方法是定义一个 init* 的函数：

PyMODINIT_FUNC initdemo(){
Py_InitModule("demo", ExtendMethods);
}

方法名必须是 init 加上模块名，然后调用 Py_InitModule 来注册模块，这个函数的第一个参数就是模块名，第二个参数是此模块中我们导出的方法，就是上一步我们定义的结构体。

9. 编译

最后一步就是编译了。没什么特别的，指定好 Python.h 头文件的位置就可以了：

gcc demo.c -I /usr/include/python2.6 -shared -o demo.so

当然，链接库的名字要和我们期望导出的模块名一致。

这样，你就可以在 Python 中使用 import 直接引入 demo 模块，然后调用它的 add 方法了：

import demo
demo.add(3, 4)

Sample

1 #include <string>
2 #include <iostream>
3 #include <Python.h>
4
5 //Python c api使用方法
6
7 using namespace std;
8
9 string GetPyFun(string s1,string s2)
10 {
11    // void Py_Initialize( )
12    //初始化Python解释器，在C++程序中使用其它Python/C API之前，必须调用此函数，如果调用失败，将产生一个致命的错误
13    Py_Initialize();
14
15    //定义变量
16    PyObject * pModule = NULL;
17    PyObject * pFunc = NULL;
18    PyObject * pArg    = NULL;
19    PyObject * result;
20    char *resultStr = "";
21
22     //int PyRun_SimpleString( const char *command)
23     //直接执行一段Python代码，就好象是在__main__ 函数里面执行一样。
24     //PyRun_SimpleString("import sys");
25    //PyRun_SimpleString("sys.path.append('C:\\Documents and Settings\\Administrator\\My Documents\\Visual Studio 2005\\Projects\\hello\\hello')");
26
27    //PyObject* PyImport_ImportModule(char *name)
28    //导入一个Python模块，参数name可以是*.py文件的文件名。相当于Python内建函数__import__()
29    pModule =PyImport_ImportModule("hello");//这里是要调用的文件名
30
31    //PyObject* PyObject_GetAttrString(PyObject *o, char *attr_name)
32    //返回模块对象o中的attr_name属性或函数，相当于Python中表达式语句：o.attr_name
33    pFunc= PyObject_GetAttrString(pModule, "Hello");
34
35    //PyObject* Py_BuildValue( char *format, ...)
36    //format以tuple的形式指定，一个参数就是(i)
37    //构建一个参数列表，把C类型转换为Python对象，使Python可以使用C类型数据
38    pArg= Py_BuildValue("(s,s)", s1.c_str(),s2.c_str());
39
40    //pParm = PyTuple_New(2);
41    //PyTuple_SetItem(pParm, 0, Py_BuildValue("s", csEntity));
42    //PyTuple_SetItem(pParm, 1, Py_BuildValue("s", csEntity));
43
44    //PyObject* PyEval_CallObject(PyObject* pfunc, PyObject* pargs)
45    //用于调用Python函数
46    //此函数接受两个PyObject*形参
47    //pfunc是要被调用的Python函数，通常可由PyObject_GetAttrString获得
48    //pargs是函数的参数列表，通常可由Py_BuildValue获得
49    result = PyEval_CallObject(pFunc, pArg);
50
51     //int PyArg_Parse( PyObject *args, char *format, ...)
52     //解构Python数据为C的类型，这样C程序中才可以使用Python里的数据。
53     PyArg_Parse(result, "s", &resultStr);
54
55     //关闭Python解释器，释放解释器所占用的资源
56    Py_Finalize();
57    return resultStr;
58    }
59
60    int Walk(const string& s1,const string& s2)
61    {
62     // void Py_Initialize( )
63     //初始化Python解释器，在C++程序中使用其它Python/C API之前，必须调用此函数，如果调用失败，将产生一个致命的错误
64    Py_Initialize();
65
66    //定义变量
67    PyObject * pModule = NULL;
68    PyObject * pFunc = NULL;
69    PyObject * pArg    = NULL;
70    PyObject * result;
71    int reVal = 0;
72
73    //int PyRun_SimpleString( const char *command)
74    //直接执行一段Python代码，就好象是在__main__ 函数里面执行一样。
75    //PyRun_SimpleString("import sys");
76    //PyRun_SimpleString("sys.path.append('C:\\Documents and Settings\\Administrator\\My Documents\\Visual Studio 2005\\Projects\\hello\\hello')");
77
78    //PyObject* PyImport_ImportModule(char *name)
79    //导入一个Python模块，参数name可以是*.py文件的文件名。相当于Python内建函数__import__()
80    pModule =PyImport_ImportModule("walkdir");//这里是要调用的文件名
81
82    //PyObject* PyObject_GetAttrString(PyObject *o, char *attr_name)
83    //返回模块对象o中的attr_name属性或函数，相当于Python中表达式语句：o.attr_name
84    pFunc= PyObject_GetAttrString(pModule, "list_dir");
85
86    //PyObject* Py_BuildValue( char *format, ...)
87    //format以tuple的形式指定，一个参数就是(i)
88    //构建一个参数列表，把C类型转换为Python对象，使Python可以使用C类型数据
89    pArg= Py_BuildValue("(s,s)", s1.c_str(),s2.c_str());
90
91    //pParm = PyTuple_New(2);
92    //PyTuple_SetItem(pParm, 0, Py_BuildValue("s", csEntity));
93    //PyTuple_SetItem(pParm, 1, Py_BuildValue("s", csEntity));
94
95    //PyObject* PyEval_CallObject(PyObject* pfunc, PyObject* pargs)
96    //用于调用Python函数
97    //此函数接受两个PyObject*形参
98    //pfunc是要被调用的Python函数，通常可由PyObject_GetAttrString获得
99    //pargs是函数的参数列表，通常可由Py_BuildValue获得
100    result = PyEval_CallObject(pFunc, pArg);
101
102    //int PyArg_Parse( PyObject *args, char *format, ...)
103    //解构Python数据为C的类型，这样C程序中才可以使用Python里的数据。
104    PyArg_Parse(result, "i", &reVal);
105
106    //关闭Python解释器，释放解释器所占用的资源
107    Py_Finalize();
108    return reVal;
109   }
110
111    int main()
112   {
113    //string re=GetPyFun("hello","world");
114    //cout<<"\n"<<re<<endl;
115
116      cout<<"enter a path and a filename:"<<endl;
117      string path,dir;
118      cin>>path>>dir;
119      int re=Walk(path,dir);
120
121      return 0;
122   }

在windows和linux下面，对C扩展的编译方法是不一样的，我们先来看windows版的。

我们用C实现一个简单的加法。 首先新建一个文件add.c，代码如下：

#include <Python.h>;

static PyObject* add(PyObject *self, PyObject *args);

//一定声明为static，把他们限制在这个文件范围里。 几乎所有的参数都是PyObject类型，在python，每个东西都是object。

static PyObject* add(PyObject* self, PyObject* args)

{

int x=0 ;

int y=0;

int z=0;

if (! PyArg_ParseTuple(args, "i|i", &x, &y))

return NULL;

/*第一个参数是self，这个是python用的， 每个函数都要有。我们暂时不管。args是一个参数列表。她把所有的参数都整合成一个string。所以

我们需要从这个string里来解析我们的参数。PyArg_ParseTuple来完成这个任务。第一个参数是args， 就是我们要转换的参数。第二个是格式符号。

“s”代表是个string。 从args里提取一个参数就写"s", 两个的话就写"s|s", 如果是一个string，一个int，就写"s|i", 和printf差不多。第三个

参数就是提取出来的参数放置的真正位置。必须传递这个参数的地址。对于add， 他将提取两个参数。分别是x和y。*/

z=x+y;

return Py_BuildValue("i", z);

/*调用完之后我们需要返回结果。这个结果是c的type或者是我们自己定义的类型。必须把他转换成PyObject， 让python认识。这个用Py_BuildValue

来完成。他是PyArg_ParseTuple的逆过程。他的第一个参数和PyArg_ParseTuple的第二个参数一样， 是个格式化符号。第三个参数

是我们需要转换的参数。Py_BuildValue会把所有的返回只组装成一个tutple给python。*/

}

static PyMethodDef addMethods[] =

{

{"add",  add, METH_VARARGS, "Execute a shell command."},

{NULL, NULL, 0, NULL}

};

/*这个是一个c的结构。他来完成一个映射。 我们需要把我们扩展的函数都映射到这个表里。表的第一个字段是python真正认识的。是python  里的方法名字。 第二个字段是python里的这个方法名字的具体实现的函数名。 在python里调用add， 真正执行的是用c写的add函数。第三个字段是METH_VARARGS， 他告诉python，add是调用c函数来实现的。第四个字段是这个函数的说明。如果你在python里来help这个函数，将显示这个说明。相当于在python里的函数的文档说明。*/

PyMODINIT_FUNC initadd()

{

Py_InitModule("add", addMethods);

}

/*注意，这个函数的名字不能改动。 必须是init+模块名字。 我们的模块名字是add。所以这个函数是initadd()。

这样python在导入add 的模块时候，才会找到这个函数，并调用。这个函数调用Py_InitModule来将模块名字和映射表结合在一起。 他表示，add这个模块使用addMethods这个映射表。python应该这样导入我们的module的.*/

新建一个setup.py，内容如下：

组建：（由于我的机器上装了mingw，所以指定了mingw32。默认的编译器是vs2008。参考：

python setup.py build --compiler=mingw32

执行后会在当前目录生成一个build目录及文件:

build\lib.win32-2.6\add.pyd

将add.pyd拷贝到当前目录，并写一个测试文件test.py，代码如下：

import add print add.add(3,4)

执行一下，输出为7

OK，基本上就是如此了。

在linux下的话，会有少许不同. 即直接用makefile将add.c编译成.so，python可以直接import，makefile代码如下：

用同样的测试代码，可以测试通过。

本文介绍如何用 C 语言来扩展 python。所举的例子是，为 python 添加一个设置字符串到 windows 的剪切板(Clipboard)的功能。我在写以下代码的时候用到的环境是：windows xp, gcc.exe 4.7.2, Python 3.2.3。

第一步 撰写C语言的DLL

创建一个 clip.c 文件，内容如下：

// 设置 UNICODE 库，这样的话才可以正确复制宽字符集

#define UNICODE

#include <windows.h>

#include <python.h>

// 设置文本到剪切板(Clipboard)

static PyObject *setclip(PyObject *self, PyObject *args)

{

LPTSTR  lptstrCopy;

HGLOBAL hglbCopy;

Py_UNICODE *content;

int len = 0;

// 将 python 的 UNICODE 字符串及长度传入

if (!PyArg_ParseTuple(args, "u#", &content, &len))

return NULL;

Py_INCREF(Py_None);

if (!OpenClipboard(NULL))

return Py_None;

EmptyClipboard();

hglbCopy = GlobalAlloc(GMEM_MOVEABLE, (len+1) * sizeof(Py_UNICODE));

if (hglbCopy == NULL) {

CloseClipboard();

return Py_None;

}

lptstrCopy = GlobalLock(hglbCopy);

memcpy(lptstrCopy, content, len * sizeof(Py_UNICODE));

lptstrCopy[len] = (Py_UNICODE) 0;

GlobalUnlock(hglbCopy);

SetClipboardData(CF_UNICODETEXT, hglbCopy);

CloseClipboard();

return Py_None;

}

// 定义导出给 python 的方法

static PyMethodDef ClipMethods[] = {

{"setclip", setclip, METH_VARARGS,

"Set string to clip."},

{NULL, NULL, 0, NULL}

};

// 定义 python 的 model

static struct PyModuleDef clipmodule = {

PyModuleDef_HEAD_INIT,

"clip",

NULL,

-1,

ClipMethods

};

// 初始化 python model

PyMODINIT_FUNC PyInit_clip(void)

{

return PyModule_Create(&clipmodule);

}

第二步 写 python 的 setup.py

创建一个 setup.py 文件，内容如下：

第三步 用 python 编译

运行以下命令：

python setup.py build --compiler=mingw32 install

在我的环境中会提示以下错误：

gcc: error: unrecognized command line option '-mno-cygwin'

error: command 'gcc' failed with exit status 1

打开 %PYTHON安装目录%/Lib/distutils/cygwinccompiler.py 文件，将里面的 -mno-cygwin 删除掉，然后再运行即可。

正常运行后，会生成一个 clip.pyd 文件，并将该文件复制到 %PYTHON安装目录%/Lib/site-packages 目录中

第四步 测试该扩展

写一个 test.py, 内容如下：

运行

python test.py

再到任何一个地方粘贴，即可验证是否正确。

***************************************************************************************************
一个Python扩展模块是一个普通的C语言库，对于UNIX计算机，这些库通常以.so（表示共享对象）结尾。Python模块会把代码分成3个部分：
（1）希望作为模块接口呈现的C函数；
（2）将Python开发人员所看到的那些函数的名称映射为扩展模块中的C函数的一个表；
（3）初始化函数；
大多数扩展模块可以包含在一个单独的C源文件中，这个文件被称为胶水文件，启动包含Python.h的文件，它允许访问内部的Python
API，这些API将模块与解释器相关联。下面分别来讲解上述的三个部分。
****************************************************************************************************
C函数签名：
函数的C语言实现的签名总是采用如下三个形式之一
（1）PyObject *MyFunction(PyObject *self , PyObject *args)；
（2）PyObject *MyFunction(PyObject *self , PyObject *args , PyObject *kw)；
（3）PyObject *MyFunction(PyObject *self)；
通常，C函数会采用第一种形式，传递到这些函数中的参数被包装成一个元组，为了使用这些参数，必须分解它们，可以使用PyArg_ParseTuple函数和PyArg_ParseTupleAndKeywords函数
PyArg_ParseTuple(args , "ids" , &i , &d , &s)，将args分成int , double , char*，分别存入i , d , s
****************************************************************************************************
方法表：
方法表是PyMethodDef结构的一个简单数组
struct
PyMethodDef
{
char *ml_name； #Python中使用的名字
PyCFunction ml_meth； #C函数的名字
int ml_flags； #表示使用哪种C函数的签名形式
char ml_doc； #函数的字符串文档
}；
ml_flags向解释器表明ml_meth正使用三个签名中的哪一个。ml_flags的值通常是METH_VARARGS。如果希望将关键字参数引入到函数中，那么这个值可以与METH_KEYWORDS按位或。它的值也可以是METH_NOARGS，表示不希望接受任何形式的参数。
下面是是一个例子，包含函数MyFunction的表：
static PyMethodDef myFunction[] = {
{"pythonName" ,
(PyCFuntion)MyFunction , METH_NOARGS , "my first function"} ,
{ NULL , NULL , 0 , NULL}
};
****************************************************************************************************
初始化函数：
扩展模块的最后一部分是初始化函数。当模块被加载时，Python解释器调用此函数。需要将函数命名为init模块名，例如initChenhuan，模块名为Chenhuan
****************************************************************************************************
下面是一个典型的C扩展模块：



个人比较喜欢用g++来编译，error和warming区分的很清楚，格式如下：
g++ -Wall -shared -I /usr/local/python2.6 foo.c -o
foo.so
成功的话，会在文件夹下生成foo.so，就可以使用这个模块了：