1. 概述
Python 可以非常方便地和 C 进行相互的调用。
一般,我们不会使用 C 去直接编写一个 Python 的模块。通常的情景是,我们需要把 C 的相关模块包装一下,然后在 Python 中可以直接调用它。或者是,把 Python 逻辑中的某一效率要求很高的部分使用 C 来实现。整个过程大概是:
- 引入 Python.h 头文件。
- 编写包装函数。
- 函数中处理从 Python 传入的参数。
- 实现功能逻辑。
- 处理 C 中的返回值,包装成 Python 对象。
- 在一个 PyMethodDef 结构体中注册需要的函数。
- 在一个初始化方法中注册模块名。
- 把这个 C 源文件编译成链接库。
1 int add(int x, int y){ 2 return x + y; 3 } 4 5 //int main(void){ 6 // printf("%d", add(1, 2)); 7 // return 0; 8 //} 9 10 #include<Python.h> 11 12 static PyObject* W_add(PyObject* self, PyObject* args){ 13 int x; 14 int y; 15 if(!PyArg_ParseTuple(args, "i|i", &x, &y)){ 16 return NULL; 17 } else { 18 return Py_BuildValue("i", add(x, y)); 19 } 20 } 21 22 static PyMethodDef ExtendMethods[] = { 23 {"add", W_add, METH_VARARGS, "a function from C"}, 24 {NULL, NULL, 0, NULL}, 25 }; 26 27 PyMODINIT_FUNC initdemo(){ 28 Py_InitModule("demo", ExtendMethods); 29 }
2. 引入 Python.h 头文件
这个文件一般位于 Python 的主目录中。比如我的 Ubuntu 10.04 下,它的位置在:
1 /usr/include/python2.6
在最后编译的时候指定目录就可以了。
3. 编写包装函数
因为 Python 用到的函数与普通的 C 函数,在输入和输出上,会有一些不同,所以,我们需要把普通的 C 做一些封来给 Python 用。
从另一方面来说,在实现功能的过程中,我们可以先完全不考虑这东西是拿给 Python 用的,只专注于使用 C 把它写好就可以了。最后,功能写好,测试没有问题之后,再做 Python 封装的工作。
包装函数一般声明成 static ,并且第一个参数是一个默认传入的 Python 对象,就是 Python 中某个对象的属性方法一样,第二个参数才是我们调用时传入的参数(实际上它是一个序列化后的字符串):
1 static PyObject* W_add(PyObject* self, PyObject* args);
4. 处理从 Python 传入的参数
因为我们的相关函数,之后是在 Python 环境中被调用的,那么它显然接受的就是从 Python 环境下传入的参数。这和 C 中你看到的函数是不同的,在 Python 的世界中,一切都是对象。所以,包装函数中首先要处理的问题就是解析从 Python 占获取的参数。
常用的函数有: PyArg_ParseTuple
1 int x; 2 int y; 3 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 中的函数:
1 static PyMethodDef ExtendMethods[] = { 2 {"add", W_add, METH_VARARGS, "a function from C"}, 3 {NULL, NULL, 0, NULL}, 4 }
这个结构体成员有四个函数:
- " add " 导出后在 Pyhton 中可见的方法名。
- W_add 实际映射到 C 中的方法名。
- METH_VARARGS 表示传入方法的是普通参数,当然还可以处理关键词参数。
- 此方法的注释。
8. 注册模块
在注册了方法后,就要注册此模块了。方法是定义一个 init* 的函数:
1 PyMODINIT_FUNC initdemo(){ 2 Py_InitModule("demo", ExtendMethods); 3 }
方法名必须是 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,代码如下:
1 #include <Python.h>; 2 3 static PyObject* add(PyObject *self, PyObject *args); 4 5 //一定声明为static,把他们限制在这个文件范围里。 几乎所有的参数都是PyObject类型,在python,每个东西都是object。 6 7 static PyObject* add(PyObject* self, PyObject* args) 8 9 { 10 11 int x=0 ; 12 13 int y=0; 14 15 int z=0; 16 17 if (! PyArg_ParseTuple(args, "i|i", &x, &y)) 18 19 return NULL; 20 21 /*第一个参数是self,这个是python用的, 每个函数都要有。我们暂时不管。args是一个参数列表。她把所有的参数都整合成一个string。所以 22 23 我们需要从这个string里来解析我们的参数。PyArg_ParseTuple来完成这个任务。第一个参数是args, 就是我们要转换的参数。第二个是格式符号。 24 25 “s”代表是个string。 从args里提取一个参数就写"s", 两个的话就写"s|s", 如果是一个string,一个int,就写"s|i", 和printf差不多。第三个 26 27 参数就是提取出来的参数放置的真正位置。必须传递这个参数的地址。对于add, 他将提取两个参数。分别是x和y。*/ 28 29 z=x+y; 30 31 return Py_BuildValue("i", z); 32 33 /*调用完之后我们需要返回结果。这个结果是c的type或者是我们自己定义的类型。必须把他转换成PyObject, 让python认识。这个用Py_BuildValue 34 35 来完成。他是PyArg_ParseTuple的逆过程。他的第一个参数和PyArg_ParseTuple的第二个参数一样, 是个格式化符号。第三个参数 36 37 是我们需要转换的参数。Py_BuildValue会把所有的返回只组装成一个tutple给python。*/ 38 39 } 40 41 static PyMethodDef addMethods[] = 42 43 { 44 45 {"add", add, METH_VARARGS, "Execute a shell command."}, 46 47 {NULL, NULL, 0, NULL} 48 49 }; 50 51 /*这个是一个c的结构。他来完成一个映射。 我们需要把我们扩展的函数都映射到这个表里。表的第一个字段是python真正认识的。是python 里的方法名字。 第二个字段是python里的这个方法名字的具体实现的函数名。 在python里调用add, 真正执行的是用c写的add函数。第三个字段是METH_VARARGS, 他告诉python,add是调用c函数来实现的。第四个字段是这个函数的说明。如果你在python里来help这个函数,将显示这个说明。相当于在python里的函数的文档说明。*/ 52 53 PyMODINIT_FUNC initadd() 54 55 { 56 57 Py_InitModule("add", addMethods); 58 59 } 60 61 /*注意,这个函数的名字不能改动。 必须是init+模块名字。 我们的模块名字是add。所以这个函数是initadd()。 62 63 这样python在导入add 的模块时候,才会找到这个函数,并调用。这个函数调用Py_InitModule来将模块名字和映射表结合在一起。 他表示,add这个模块使用addMethods这个映射表。python应该这样导入我们的module的.*/
新建一个setup.py,内容如下:
1 2 3 |
|
组建:(由于我的机器上装了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代码如下:
1 2 3 4 5 6 |
|
用同样的测试代码,可以测试通过。
本文介绍如何用 C 语言来扩展 python。所举的例子是,为 python 添加一个设置字符串到 windows 的剪切板(Clipboard)的功能。我在写以下代码的时候用到的环境是:windows xp, gcc.exe 4.7.2, Python 3.2.3。
第一步 撰写C语言的DLL
创建一个 clip.c 文件,内容如下:
1 // 设置 UNICODE 库,这样的话才可以正确复制宽字符集 2 3 #define UNICODE 4 5 6 7 #include <windows.h> 8 9 #include <python.h> 10 11 12 13 // 设置文本到剪切板(Clipboard) 14 15 static PyObject *setclip(PyObject *self, PyObject *args) 16 17 { 18 19 LPTSTR lptstrCopy; 20 21 HGLOBAL hglbCopy; 22 23 Py_UNICODE *content; 24 25 int len = 0; 26 27 28 29 // 将 python 的 UNICODE 字符串及长度传入 30 31 if (!PyArg_ParseTuple(args, "u#", &content, &len)) 32 33 return NULL; 34 35 36 37 Py_INCREF(Py_None); 38 39 40 41 if (!OpenClipboard(NULL)) 42 43 return Py_None; 44 45 46 47 EmptyClipboard(); 48 49 50 51 hglbCopy = GlobalAlloc(GMEM_MOVEABLE, (len+1) * sizeof(Py_UNICODE)); 52 53 if (hglbCopy == NULL) { 54 55 CloseClipboard(); 56 57 return Py_None; 58 59 } 60 61 62 63 lptstrCopy = GlobalLock(hglbCopy); 64 65 memcpy(lptstrCopy, content, len * sizeof(Py_UNICODE)); 66 67 lptstrCopy[len] = (Py_UNICODE) 0; 68 69 70 71 GlobalUnlock(hglbCopy); 72 73 74 75 SetClipboardData(CF_UNICODETEXT, hglbCopy); 76 77 78 79 CloseClipboard(); 80 81 82 83 return Py_None; 84 85 } 86 87 88 89 // 定义导出给 python 的方法 90 91 static PyMethodDef ClipMethods[] = { 92 93 {"setclip", setclip, METH_VARARGS, 94 95 "Set string to clip."}, 96 97 {NULL, NULL, 0, NULL} 98 99 }; 100 101 102 103 // 定义 python 的 model 104 105 static struct PyModuleDef clipmodule = { 106 107 PyModuleDef_HEAD_INIT, 108 109 "clip", 110 111 NULL, 112 113 -1, 114 115 ClipMethods 116 117 }; 118 119 120 121 // 初始化 python model 122 123 PyMODINIT_FUNC PyInit_clip(void) 124 125 { 126 127 return PyModule_Create(&clipmodule); 128 129 }
第二步 写 python 的 setup.py
创建一个 setup.py 文件,内容如下:
1 2 3 4 5 6 7 8 9 |
|
第三步 用 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, 内容如下:
1 2 3 |
|
运行
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,就可以使用这个模块了: