NumPy 与 SWIG:深入解析 numpy.i 类型映射(typemap)的测试基础设施

原创2026-09-19 18:00:161,885 阅读
文章标签:科学计算高性能计算数据分析并发编程

NumPy 与 SWIG:深入解析 numpy.i 类型映射(typemap)的测试基础设施

导读

numpy.i 是 NumPy 提供的一组 SWIG 类型映射(typemap)文件,它让 C/C++ 代码中那些以原生 C 数组为参数的函数,能够被自动包装成接受 NumPy 数组的 Python 扩展。由于数据类型与参数签名的组合呈爆炸式增长(12 种数据类型 × 74 种参数签名 = 888 个开箱即用的 typemap),验证这些 typemap 是否正常工作本身就是一个组合学难题。本文以 doc/source/reference/swig.testing.rst 为骨架,结合 tools/swig 目录下的真实源码,系统讲解 NumPy 官方是如何组织这套测试基础设施的:从 C 宏批量生成函数原型与实现,到 SWIG 接口文件批量应用 typemap,再到基于 unittest 的 Python 继承式测试驱动。读完本文,你将完整掌握这套「组合爆炸」测试方法,并能在自己的 SWIG 项目中复用它。

测试的背景:888 个 typemap 的组合学挑战

为 numpy.i SWIG 接口文件编写测试是一项组合学意义上的麻烦事。当前 numpy.i 支持 12 种数据类型,每种类型有 74 种不同的参数签名,合计 888 个"开箱即用"的 typemap。而每一个 typemap 又可能需要多个单元测试来验证其在合法输入与非法输入下的预期行为。因此在 numpy/tools/swig 子目录中执行 make test 时,会运行超过 1,000 个独立的单元测试。

为了驾驭如此数量庞大且高度相似的测试,测试代码运用了几种高级编程技术:

  • C 宏:在头文件与源文件中批量生成函数原型和实现;
  • SWIG 宏:在接口文件中批量应用 typemap;
  • Python 继承:在测试脚本中通过类继承按数据类型派生测试用例。

numpy.i 文件本身位于 tools/swig/numpy.i,其中仅一维数组相关的 IN_ARRAY1 / INPLACE_ARRAY1 / ARGOUT_ARRAY1 系列 typemap 就有 42 处定义(可通过在仓库中搜索该模式核实),可见其规模。

测试组织:五套相互独立的测试框架

测试按数组维度组织为若干独立框架。对于一维数组,有两个 C++ 文件——一个头文件和一个源文件:

Vector.h
Vector.cxx

它们包含一系列以一维数组为函数参数的函数原型与实现。文件 Vector.i 是 SWIG 接口文件,它定义了一个 Python 模块 Vector,在包装 Vector.h 中的函数时使用 numpy.i 中的 typemap 正确处理 C 数组。

Makefile(见 tools/swig/test/Makefile)调用 swig 生成 Vector.py 和 Vector_wrap.cxx,并执行 setup.py 脚本(见 tools/swig/test/setup.py)编译 Vector_wrap.cxx,链接生成扩展模块 _Vector.so 或 _Vector.dylib(取决于平台)。该扩展模块与代理文件 Vector.py 一起被放置在 build 目录的子目录下。

实际的测试由一个名为 testVector.py 的 Python 脚本(见 tools/swig/test/testVector.py)执行。它使用 Python 标准库中的 unittest 模块,对所支持的每一种数据类型、对 Vector.h 中定义的每个函数进行多项测试。

其他维度完全遵循同一套模式:

测试维度 头文件/源文件 接口文件 测试脚本
二维数组 Matrix.h / Matrix.cxx Matrix.i testMatrix.py
三维数组 Tensor.h / Tensor.cxx Tensor.i testTensor.py
四维数组 SuperTensor.h / SuperTensor.cxx SuperTensor.i testSuperTensor.py
扁平 in-place 数组 Flat.h / Flat.cxx Flat.i testFlat.py

(此外还有针对 Fortran 顺序数组的 Farray、testFarray.py,以及 Array / testArray.py。)下文以 Vector 测试为例展开,但同样的说明适用于 Matrix、Tensor 与 SuperTensor 测试。命令 make test 会确保所有测试软件被构建,然后依次运行全部测试脚本。

测试头文件:用 TEST_FUNC_PROTOS 宏批量生成原型

Vector.h(见 tools/swig/test/Vector.h)是一个 C++ 头文件,定义了一个名为 TEST_FUNC_PROTOS 的 C 宏,它接受两个参数:

  • TYPE:数据类型名,例如 unsigned int;
  • SNAME:同一数据类型的无空格短名,例如 uint。

该宏定义了一系列以 SNAME 为前缀的函数原型,每个原型至少有一个类型为 TYPE 的数组参数;有返回值的函数返回 TYPE 值。宏展开后生成的函数族覆盖了 9 种典型的一维数组参数形式:

  • TYPE SNAMELength(TYPE vector[3]) —— 1D 输入数组,硬编码长度;
  • TYPE SNAMEProd(TYPE * series, int size) —— 1D 输入数组;
  • TYPE SNAMESum(int size, TYPE * series) —— 1D 输入数组,数据参数在最后;
  • void SNAMEReverse(TYPE array[3]) —— 1D in-place 数组,硬编码长度;
  • void SNAMEOnes(TYPE * array, int size) —— 1D in-place 数组;
  • void SNAMEZeros(int size, TYPE * array) —— 1D in-place 数组,数据参数在最后;
  • void SNAMEEOSplit(TYPE vector[3], TYPE even[3], TYPE odd[3]) —— 1D argout 数组,硬编码长度;
  • void SNAMETwos(TYPE * twoVec, int size) —— 1D argout 数组;
  • void SNAMEThrees(int size, TYPE * threeVec) —— 1D argout 数组,数据参数在最后。

随后 TEST_FUNC_PROTOS 对 numpy.i 支持的全部 12 种数据类型逐一展开:

数据类型(TYPE) 短名(SNAME)
signed char schar
unsigned char uchar
short short
unsigned short ushort
int int
unsigned int uint
long long
unsigned long ulong
long long longLong
unsigned long long ulongLong
float float
double double

从源码结构看,这 12 个 TEST_FUNC_PROTOS 宏调用(Vector.h)一次性生成了 108 个函数原型,这正是用宏解决「组合爆炸」的第一步:只写一次宏,展开 12 次。

测试源文件:TEST_FUNCS 宏的实现

Vector.cxx(见 tools/swig/test/Vector.cxx)为 Vector.h 中声明的每个函数原型提供可编译的实现。它定义了一个与 TEST_FUNC_PROTOS 具有相同参数、工作方式相同的 C 宏 TEST_FUNCS,并同样对上述 12 种数据类型逐一实现。

每个函数实现都极具针对性,用于验证某一类 typemap 的特定行为。例如:

  • SNAMELength 计算三维向量的模长(sqrt 累加平方和),用来验证 IN_ARRAY1[ANY] 固定长度输入数组;
  • SNAMEProd 与 SNAMESum 分别以「数据在前、维度在后」和「维度在前、数据在后」两种顺序书写,用于验证 IN_ARRAY1 的两种签名变体;
  • SNAMEReverse、SNAMEOnes、SNAMEZeros 就地修改传入数组,验证 INPLACE_ARRAY1 系列 typemap 能否把 NumPy 数组按引用传入 C 函数并让修改生效;
  • SNAMEEOSplit、SNAMETwos、SNAMEThrees 由 C 侧填充输出数组,验证 ARGOUT_ARRAY1 系列 typemap 能否把输出参数转换为 Python 返回值。

测试 SWIG 接口文件:%apply_numpy_typemaps 宏

Vector.i(见 tools/swig/test/Vector.i)是定义 Python 模块 Vector 的 SWIG 接口文件,完全遵循 doc/source/reference/swig.interface-file.rst 中描述的 numpy.i 使用约定。它的核心结构包括:

  1. %module Vector 声明模块名,并在 %{ %} 块中定义 SWIG_FILE_WITH_INIT 宏、包含 Vector.h;
  2. %include "../numpy.i" 引入 NumPy 类型映射(注意这里用的是相对于 tools/swig/test 的路径,实际文件在 tools/swig/numpy.i);
  3. %init %{ import_array(); %} 初始化 NumPy C API;
  4. 定义一个带单一参数 TYPE 的 SWIG 宏 %apply_numpy_typemaps,其内部用 SWIG 指令 %apply 把 numpy.i 提供的 typemap 应用到 Vector.h 中的参数签名上。

%apply 指令的映射关系非常直白,以输入数组为例:

%apply (TYPE IN_ARRAY1[ANY])          {(TYPE vector[3])};
%apply (TYPE* IN_ARRAY1, int DIM1)    {(TYPE* series, int size)};
%apply (int DIM1, TYPE* IN_ARRAY1)    {(int size, TYPE* series)};

即:numpy.i 中名为 IN_ARRAY1[ANY] 的 typemap 被应用到头文件里 TYPE vector[3] 这样的固定长度数组参数上;TYPE* IN_ARRAY1, int DIM1 被应用到 TYPE* series, int size 上,等等。in-place 与 argout 系列同理:

%apply (TYPE INPLACE_ARRAY1[ANY])         {(TYPE array[3])};
%apply (TYPE* INPLACE_ARRAY1, int DIM1)   {(TYPE* array, int size)};
%apply (int DIM1, TYPE* INPLACE_ARRAY1)   {(int size, TYPE* array)};

%apply (TYPE ARGOUT_ARRAY1[ANY])          {(TYPE even[3])};
%apply (TYPE ARGOUT_ARRAY1[ANY])          {(TYPE odd[ 3])};
%apply (TYPE* ARGOUT_ARRAY1, int DIM1)    {(TYPE* twoVec, int size)};
%apply (int DIM1, TYPE* ARGOUT_ARRAY1)    {(int size, TYPE* threeVec)};

之后这个宏对 12 种数据类型全部展开,最后执行 %include "Vector.h" 用套用了 typemap 的方式包装头文件中的所有函数原型。这样,Vector.doubleLength、Vector.intProd、Vector.floatReverse 等 108 个 Python 可调用函数便全部生成。Matrix.i、Tensor.i、SuperTensor.i 的结构完全相同,只是把 IN_ARRAY1 换成 IN_ARRAY2 / IN_ARRAY3 / IN_ARRAY4 系列;而 Flat.i 则专门针对扁平 in-place 数组签名 (TYPE* INPLACE_ARRAY_FLAT, int DIM_FLAT)。

测试 Python 脚本:继承驱动的类型化测试

构建完测试扩展模块之后,运行 testVector.py 即可执行测试。与其他使用 unittest 的脚本一样,testVector.py 首先定义一个继承自 unittest.TestCase 的类:

class VectorTestCase(unittest.TestCase):

但这个类并不会被直接运行,而是作为多个按数据类型划分的 Python 类的基类。VectorTestCase 类存放两个用于类型信息的字符串:

self.typeStr 与 Vector.h / Vector.cxx 中使用的 SNAME 前缀匹配的字符串,例如 "double"。

self.typeCode 表示 NumPy 数据类型类型的短字符串(通常为单字符),与 self.typeStr 对应。例如若 self.typeStr 为 "double",则 self.typeCode 应为 "d"。

VectorTestCase 定义的每个测试都通过访问 Vector 模块的字典来取出待测的 Python 函数:

length = Vector.__dict__[self.typeStr + "Length"]

对于双精度测试,这会返回 Python 函数 Vector.doubleLength。这样做的好处是:所有测试方法只写一遍,具体测哪个函数完全由 typeStr 在运行时决定。

随后为每种受支持的数据类型定义一个简短的测试用例子类,例如:

class doubleTestCase(VectorTestCase):
    def __init__(self, methodName="runTest"):
        VectorTestCase.__init__(self, methodName)
        self.typeStr  = "double"
        self.typeCode = "d"

12 个这样的类(scharTestCase、ucharTestCase、shortTestCase、ushortTestCase、intTestCase、uintTestCase、longTestCase、ulongTestCase、longLongTestCase、ulongLongTestCase、floatTestCase、doubleTestCase,对应 typeCode 分别为 b、B、h、H、i、I、l、L、q、Q、f、d)被收集进一个 unittest.TestSuite 并执行。错误与失败被求和后作为退出参数返回,任何非零结果都表示至少有一个测试未通过(见 testVector.py 的主入口逻辑)。

测试内容的设计:每个 typemap 对应一组正反用例

VectorTestCase 中的测试方法对每一类 typemap 都同时覆盖「正确输入」与「错误输入」两种路径。以固定长度输入数组 IN_ARRAY1[ANY] 的 Length 测试为例:

def testLength(self):
    length = Vector.__dict__[self.typeStr + "Length"]
    self.assertEqual(length([5, 12, 0]), 13)      # 正常输入,返回模长

def testLengthBadList(self):
    length = Vector.__dict__[self.typeStr + "Length"]
    self.assertRaises(BadListError, length, [5, "twelve", 0])  # 元素类型错误

def testLengthWrongSize(self):
    length = Vector.__dict__[self.typeStr + "Length"]
    self.assertRaises(TypeError, length, [5, 12])              # 长度错误

def testLengthWrongDim(self):
    length = Vector.__dict__[self.typeStr + "Length"]
    self.assertRaises(TypeError, length, [[1, 2], [3, 4]])     # 维度错误

def testLengthNonContainer(self):
    length = Vector.__dict__[self.typeStr + "Length"]
    self.assertRaises(TypeError, length, None)                 # 非容器

有趣的是脚本开头的兼容性处理:

major, minor = [int(d) for d in np.__version__.split(".")[:2]]
if major == 0:
    BadListError = TypeError
else:
    BadListError = ValueError

它根据 NumPy 的主版本号选择「坏列表」触发的异常类型,这正说明 typemap 在把非法容器转换为 NumPy 数组时会抛出 ValueError(现代版本),而错误类型本身也被当作测试契约的一部分。

对于 in-place 系列,测试则验证「修改必须作用于原数组」这一核心语义,例如 Reverse:

vector = np.array([1, 2, 4], self.typeCode)
reverse(vector)
self.assertEqual((vector == [4, 2, 1]).all(), True)

同时还要验证错误类型(如用 'c' 类型数组)、错误维度、非数组参数均抛出 TypeError。对于 argout 系列,测试验证 C 函数填充的输出被正确返回为 Python 对象,例如 EOSplit 返回 (even, odd) 两个数组,Twos(5) 返回全 2 的长度 5 数组,并额外验证非整数维度参数会报错。

构建与运行:Makefile 的自动化流程

tools/swig/test/Makefile 将上述全部环节自动化:

INTERFACES = Array.i Farray.i Vector.i Matrix.i Tensor.i Fortran.i Flat.i
WRAPPERS   = $(INTERFACES:.i=_wrap.cxx)
PROXIES    = $(INTERFACES:.i=.py      )

all:
    ./setup.py build_ext -i

test: all
    python testVector.py
    python testMatrix.py
    python testTensor.py
    python testArray.py
    python testFarray.py
    python testFortran.py
    python testFlat.py

%_wrap.cxx: %.i %.h ../numpy.i
    swig -c++ -python $<

其模式规则 %_wrap.cxx 声明了依赖关系:只要 .i 接口文件、.h 头文件或 ../numpy.i 中任何一个发生变更,就会重新调用 swig -c++ -python 生成包装代码,从而保证 typemap 本身的每次修改都会被重新编译测试。clean 目标则清理 build 目录、.so 共享库、包装源码与代理文件。

整个流程可概括为一条命令(在 tools/swig 目录下):

$ make test

它会:依次为每个接口文件调用 SWIG 生成 _wrap.cxx 与 .py 代理 → 调用 setup.py 编译链接扩展模块 → 逐个运行 7 个测试脚本(覆盖 1D/2D/3D/4D、扁平、Fortran 顺序等全部维度)。tools/swig/README(见 tools/swig/README)对这套流程与各签名形式做了同样的说明,可作为配套参考。

小结:一套可复用的「组合爆炸」测试模式

回顾整个测试基础设施,其设计精髓可以概括为三个层次的正交组合:

  1. C 宏层(TEST_FUNC_PROTOS / TEST_FUNCS):把「函数签名形态 × 数据类型」的矩阵批量展开,12 种类型 × 9 种签名一次性生成 108 个函数;
  2. SWIG 宏层(%apply_numpy_typemaps):把「typemap 名称 × 参数签名」的映射批量应用,让每个函数都套上正确的类型转换规则;
  3. Python 继承层(VectorTestCase 及其 12 个子类):把「测试方法 × 数据类型」的组合通过类继承与 typeStr/typeCode 动态拼接彻底消除重复代码。

最终,超过 1,000 个单元测试以极低的代码重复率覆盖了 888 个 typemap 的正反向行为。这套模式完全可以迁移到你自己的 SWIG + NumPy 项目中:如果你维护一组面向多数据类型的 C/C++ 包装,不妨照此用宏生成函数族、用 %apply 批量套用 typemap、再用继承式 unittest 驱动按类型参数化的测试,从而以最小的维护成本获得最全面的覆盖。

登录后查看全文
numpy