使用Cython将C代码编译为Python扩展库的完整指南

Alice

发布时间：2026-10-13 | 3人浏览过

原创

本文详细介绍如何利用Cython将C语言代码编译为Python扩展库，以实现高性能计算。通过一个Numpy矩阵运算示例，演示了从C头文件编写、Cython接口定义到setup.py配置及编译运行的完整流程。重点解析了二维数组降维传递、类型声明及内存访问技巧，展示了将循环置于C层以提升执行效率的方法。

Cython扩展库开发概述

在前文讨论Cython编译Python的基础上，本节重点讲解如何借助Cython编写Python的C语言扩展库。

混合编程的核心难点在于两种语言间数据类型的正确传递与处理。

我们将通过一个基础示例进行演示：目标是使用C语言实现Numpy数组的加法及元素级乘法模块。在此场景中，Numpy数组被传入C语言模块后，转换为二维数组进行处理。

C语言核心模块实现

首先定义头文件main.h，声明相关函数接口。


#ifndef _MAIN_H
#define _MAIN_H
void plus(double *a, double *b, double *r, int n, int m); // 矩阵加法
void mul(double *a, double *b, double *r, int n, int m); // 矩阵按元素相乘
void main(double *a, double *b, double *r, int n, int m, int times); // 用于测试的main函数
#endif

接下来在main.c中编写核心逻辑代码。


#include "main.h"
 
/***********************************
* 矩阵的加法
* 利用数组是顺序存储的特性, *
* 通过降维来访问二维数组! *
* r
***********************************/
void plus(double *a, double *b, double *r, int n, int m)
{
  int i, j;
  for(i = 0; i < n; i++)
  {
    for(j = 0; j < m; j++)
      *(r + i*m + j) = *(a + i*m + j) + *(b + i*m + j);
  }
}
 
/***********************************
* 矩阵的按元素乘法
* 利用数组是顺序存储的特性, *
* 通过降维来访问二维数组! *
* r
***********************************/
void mul(double *a, double *b, double *r, int n, int m)
{
  int i, j;
  for(i = 0; i < n; i++)
  {
    for(j = 0; j < m; j++)
      *(r + i*m + j) = *(a + i*m + j) * *(b + i*m + j);
  }
}
 
/***********************************
* main函数
* 利用数组是顺序存储的特性, *
* 通过降维来访问二维数组! *
* r
***********************************/
void main(double *a, double *b, double *r, int n, int m, int times)
{
  int i;
  // 循环times次
#pragma omp parallel for
  for (i = 0; i < times; i++)
  {
    // 矩阵的加法
    plus(a, b, r, n, m);
    
    // 矩阵按元素相乘
    mul(a, b, r, n, m);
  }
}

该文件实现了矩阵加法与按元素相乘功能，采用二维数组作为数据结构。鉴于C语言中直接传递二维数组较为繁琐，此处采用降维方式访问数组。此外，main函数中包含一个循环用于性能测试。

Cython接口定义与调用

随后编写test.pyx文件以调用上述C函数（注意文件后缀为.pyx）。关键知识点已在代码注释中详细说明。


# 既要import numpy, 也要用cimport numpy
import time
import numpy as np
cimport numpy as np
 
# 使用Numpy-C-API
np.import_array()
 
# cdefine C 函数
cdef extern from "main.h":
  void plus(double *a, double *b, double *r, int n, int m)
  void mul(double *a, double *b, double *r, int n, int m)
  void main(double *a, double *b, double *r, int n, int m, int times)
 
"""
# 定义一个"包装函数", 用于调用C语言的main函数，调用范例：plus_fun(a, b, r)
# 在这里要注意函数传入的参数的类型声明，double表示数组的元素是double类型的，
# ndim = 2表示数组的维度是2
# 在调用main函数时，要把python的变量强制转化成相应的类型（以确保无误），比如<int>
# 当然，基本类型如int，可以不显式地写出来，如下面的a.shape[0]、a.shape[1]
"""
def main_func(np.ndarray[double, ndim=2, mode="c"] a not None,
           np.ndarray[double, ndim=2, mode="c"] b not None, 
           np.ndarray[double, ndim=2, mode="c"] r not None,
           times not None):
  main(<double*> np.PyArray_DATA(a),
        <double*> np.PyArray_DATA(b),
        <double*> np.PyArray_DATA(r),
        a.shape[0],
        a.shape[1],
        <int> times)

编译配置与执行流程

为了使用Cython编译上述代码，需创建一个setup.py配置文件。


import numpy
from distutils.core import setup
from distutils.extension import Extension
from Cython.Distutils import build_ext
 
filename = 'test' # 源文件名
full_filename = 'test.pyx' # 包含后缀的源文件名
 
setup(
  name = 'test',
  cmdclass = {'build_ext': build_ext},
  ext_modules=[Extension(filename,sources=[full_filename, "main.c"],
         include_dirs=[numpy.get_include()])],
)

确保main.h、main.c和test.pyx位于同一目录下。在该文件夹中按住Shift键并右键点击，选择打开cmd或PowerShell控制台，执行以下命令进行Cython编译：

python setup.py build_ext --i

或者使用以下命令：

python setup.py build_ext --inplace

编译成功的界面示例如下：

测试验证与性能分析

编译完成后，同目录下会生成名为“test.cp36-win_amd64.pyd”的二进制文件。该文件虽为闭源，但可直接通过Python的import语句导入。接下来编写测试代码main.py进行验证。


import test
import time
import numpy as np
 
start_time = time.time()
a = np.random.rand(100, 100) * 2 - 1 # 生成300*300的随即矩阵
b = np.random.rand(100, 100) * 2 - 1
r = np.empty_like(a) # 创建一个空矩阵，用来存储计算结果
test.main_func(a, b, r, 500000) # 调用main_func进行测试
end_time = time.time()
print(end_time - start_time) # 输出时间
print(r) # 输出运行结果

运行上述测试代码后的输出结果如下：