numpy.i：用于 NumPy 的 SWIG 接口文件#

引言#

简单包装器和接口生成器（或 SWIG）是一个功能强大的工具，用于生成与各种脚本语言连接的包装器代码。SWIG 可以解析头文件，并且仅使用代码原型就能为目标语言创建接口。但 SWIG 并非万能。例如，它无法从原型中得知

double rms(double* seq, int n);

到底 seq 是什么。它是一个需要原地修改的单个值吗？它是一个数组吗？如果是，它的长度是多少？它是只输入？只输出？还是输入输出？SWIG 无法确定这些细节，也不会尝试这样做。

如果我们设计了 rms，我们可能会将其设计为一个例程，它接受一个长度为 n 的 double 值输入数组 seq，并返回均方根。然而，SWIG 的默认行为是创建一个可以编译的包装函数，但几乎不可能以 C 例程预期的方式从脚本语言中使用它。

对于 Python 而言，处理连续（或技术上说，跨步式）同类数据块的首选方式是使用 NumPy，它提供了对多维数组数据的完整面向对象访问。因此，rms 函数最符合逻辑的 Python 接口将是（包括文档字符串）

def rms(seq):
    """
    rms: return the root mean square of a sequence
    rms(numpy.ndarray) -> double
    rms(list) -> double
    rms(tuple) -> double
    """

其中 seq 将是一个 double 值的 NumPy 数组，其长度 n 将在内部从 seq 中提取，然后传递给 C 例程。更好的是，由于 NumPy 支持从任意 Python 序列构造数组，seq 本身可以是几乎任意的序列（只要每个元素都可以转换为 double），包装器代码将在内部将其转换为 NumPy 数组，然后再提取其数据和长度。

SWIG 允许通过一种称为 类型映射 的机制来定义这些类型的转换。本文档提供了关于如何使用 numpy.i 的信息，这是一个 SWIG 接口文件，它定义了一系列类型映射，旨在使上述数组相关的转换类型相对简单地实现。例如，假设上面定义的 rms 函数原型在一个名为 rms.h 的头文件中。要获得上面讨论的 Python 接口，你的 SWIG 接口文件需要包含以下内容

%{
#define SWIG_FILE_WITH_INIT
#include "rms.h"
%}

%include "numpy.i"

%init %{
import_array();
%}

%apply (double* IN_ARRAY1, int DIM1) {(double* seq, int n)};
%include "rms.h"

类型映射通过一个或多个函数参数列表（按类型或按类型和名称）进行键控。我们将这些列表称为 签名。numpy.i 定义的众多类型映射之一在上面被使用，其签名为 (double* IN_ARRAY1, int DIM1)。参数名称旨在表明 double* 参数是一个一维输入数组，并且 int 表示该维度的尺寸。这正是 rms 原型中的模式。

最有可能的是，实际要包装的原型都不会有 IN_ARRAY1 和 DIM1 这样的参数名称。我们使用 SWIG 的 %apply 指令，将 double 类型一维输入数组的类型映射应用于 rms 使用的实际原型。因此，有效使用 numpy.i 需要了解有哪些类型映射可用以及它们的作用。

包含上述 SWIG 指令的 SWIG 接口文件将生成类似于以下内容的包装器代码

 1 PyObject *_wrap_rms(PyObject *args) {
 2   PyObject *resultobj = 0;
 3   double *arg1 = (double *) 0 ;
 4   int arg2 ;
 5   double result;
 6   PyArrayObject *array1 = NULL ;
 7   int is_new_object1 = 0 ;
 8   PyObject * obj0 = 0 ;
 9
10   if (!PyArg_ParseTuple(args,(char *)"O:rms",&obj0)) SWIG_fail;
11   {
12     array1 = obj_to_array_contiguous_allow_conversion(
13                  obj0, NPY_DOUBLE, &is_new_object1);
14     npy_intp size[1] = {
15       -1
16     };
17     if (!array1 || !require_dimensions(array1, 1) ||
18         !require_size(array1, size, 1)) SWIG_fail;
19     arg1 = (double*) array1->data;
20     arg2 = (int) array1->dimensions[0];
21   }
22   result = (double)rms(arg1,arg2);
23   resultobj = SWIG_From_double((double)(result));
24   {
25     if (is_new_object1 && array1) Py_DECREF(array1);
26   }
27   return resultobj;
28 fail:
29   {
30     if (is_new_object1 && array1) Py_DECREF(array1);
31   }
32   return NULL;
33 }

numpy.i 中的类型映射负责以下代码行：12-20、25 和 30。第 10 行解析 rms 函数的输入。从格式字符串 "O:rms" 中，我们可以看到参数列表预期为一个 Python 对象（由冒号前的 O 指定），其指针存储在 obj0 中。numpy.i 提供的一些函数被调用，用于从通用 Python 对象到 NumPy 数组的（可能）转换进行生成和检查。这些函数在辅助函数 一节中进行了解释，但希望它们的名称是自解释的。在第 12 行，我们使用 obj0 构造一个 NumPy 数组。在第 17 行，我们检查结果的有效性：它是否非空，以及它是否具有任意长度的单个维度。一旦这些状态得到验证，我们会在第 19 和 20 行提取数据缓冲区和长度，以便在第 22 行调用底层的 C 函数。第 25 行处理我们创建了不再需要的新数组时的内存管理。

这段代码包含了大量的错误处理。请注意，SWIG_fail 是 goto fail 的一个宏，指向第 28 行的标签。如果用户提供了错误的参数数量，这将在第 10 行被捕获。如果 NumPy 数组的构造失败或生成了维度数量错误的数组，这些错误将在第 17 行被捕获。最后，如果检测到错误，内存仍然在第 30 行得到正确管理。

请注意，如果 C 函数签名顺序不同

double rms(int n, double* seq);

则 SWIG 将无法将上述类型映射签名与 rms 的参数列表匹配。幸运的是，numpy.i 有一组数据指针最后给出的类型映射

%apply (int DIM1, double* IN_ARRAY1) {(int n, double* seq)};

这只会导致在上面生成的代码的第 3 和 4 行中交换 arg1 和 arg2 的定义，以及在第 19 和 20 行中交换它们的赋值。

使用 numpy.i#

numpy.i 文件目前位于 numpy 安装目录下的 tools/swig 子目录中。通常，你会希望将其复制到开发包装器的目录中。

一个只使用单个 SWIG 接口文件的简单模块应包含以下内容

%{
#define SWIG_FILE_WITH_INIT
%}
%include "numpy.i"
%init %{
import_array();
%}

在一个编译后的 Python 模块中，import_array() 应该只被调用一次。这可能在你自己编写并链接到模块的 C/C++ 文件中。如果是这种情况，则你的任何接口文件都不应 #define SWIG_FILE_WITH_INIT 或调用 import_array()。或者，这个初始化调用可能在 SWIG 从包含上述 %init 块的接口文件生成的包装器文件中。如果是这种情况，并且你有多个 SWIG 接口文件，那么只有其中一个接口文件应该 #define SWIG_FILE_WITH_INIT 并调用 import_array()。

可用类型映射#

numpy.i 为不同数据类型（例如 double 和 int）的数组以及不同维度类型（例如 int 或 long）提供的类型映射指令，除了 C 和 NumPy 类型规范之外，彼此相同。因此，这些类型映射（通常在幕后）通过一个宏来实现

%numpy_typemaps(DATA_TYPE, DATA_TYPECODE, DIM_TYPE)

它可以为合适的 (DATA_TYPE, DATA_TYPECODE, DIM_TYPE) 三元组调用。例如

%numpy_typemaps(double, NPY_DOUBLE, int)
%numpy_typemaps(int,    NPY_INT   , int)

numpy.i 接口文件使用 %numpy_typemaps 宏为以下 C 数据类型和 int 维度类型实现类型映射

  • signed char

  • unsigned char

  • short

  • unsigned short

  • int

  • unsigned int

  • long

  • unsigned long

  • long long

  • unsigned long long

  • float

  • double

在以下描述中，我们引用一个通用的 DATA_TYPE，它可以是上面列出的任何 C 数据类型；以及 DIM_TYPE，它应该是多种整数类型之一。

类型映射签名主要通过缓冲区指针的名称来区分。带有 FARRAY 的名称用于 Fortran 顺序数组，带有 ARRAY 的名称用于 C 顺序（或 1D 数组）。

输入数组#

输入数组被定义为传入例程但不会原地修改或返回给用户的数据数组。因此，Python 输入数组可以几乎是任何可以转换为所需数组类型的 Python 序列（例如列表）。输入数组签名是

1D

  • (   DATA_TYPE IN_ARRAY1[ANY] )

  • (   DATA_TYPE* IN_ARRAY1, int DIM1 )

  • (   int DIM1, DATA_TYPE* IN_ARRAY1 )

2D

  • (   DATA_TYPE IN_ARRAY2[ANY][ANY] )

  • (   DATA_TYPE* IN_ARRAY2, int DIM1, int DIM2 )

  • (   int DIM1, int DIM2, DATA_TYPE* IN_ARRAY2 )

  • (   DATA_TYPE* IN_FARRAY2, int DIM1, int DIM2 )

  • (   int DIM1, int DIM2, DATA_TYPE* IN_FARRAY2 )

3D

  • (   DATA_TYPE IN_ARRAY3[ANY][ANY][ANY] )

  • (   DATA_TYPE* IN_ARRAY3, int DIM1, int DIM2, int DIM3 )

  • (   int DIM1, int DIM2, int DIM3, DATA_TYPE* IN_ARRAY3 )

  • (   DATA_TYPE* IN_FARRAY3, int DIM1, int DIM2, int DIM3 )

  • (   int DIM1, int DIM2, int DIM3, DATA_TYPE* IN_FARRAY3 )

4D

  • (DATA_TYPE IN_ARRAY4[ANY][ANY][ANY][ANY])

  • (DATA_TYPE* IN_ARRAY4, DIM_TYPE DIM1, DIM_TYPE DIM2, DIM_TYPE DIM3, DIM_TYPE DIM4)

  • (DIM_TYPE DIM1, DIM_TYPE DIM2, DIM_TYPE DIM3, , DIM_TYPE DIM4, DATA_TYPE* IN_ARRAY4)

  • (DATA_TYPE* IN_FARRAY4, DIM_TYPE DIM1, DIM_TYPE DIM2, DIM_TYPE DIM3, DIM_TYPE DIM4)

  • (DIM_TYPE DIM1, DIM_TYPE DIM2, DIM_TYPE DIM3, DIM_TYPE DIM4, DATA_TYPE* IN_FARRAY4)

列出的第一个签名 ( DATA_TYPE IN_ARRAY[ANY] ) 用于具有硬编码维度的一维数组。同样，( DATA_TYPE IN_ARRAY2[ANY][ANY] ) 用于具有硬编码维度的二维数组，三维数组也类似。

原地数组#

原地数组被定义为原地修改的数组。输入值可能被使用，也可能不被使用，但函数返回时的值是重要的。因此，提供的 Python 参数必须是所需类型的 NumPy 数组。原地数组签名是

1D

  • (   DATA_TYPE INPLACE_ARRAY1[ANY] )

  • (   DATA_TYPE* INPLACE_ARRAY1, int DIM1 )

  • (   int DIM1, DATA_TYPE* INPLACE_ARRAY1 )

2D

  • (   DATA_TYPE INPLACE_ARRAY2[ANY][ANY] )

  • (   DATA_TYPE* INPLACE_ARRAY2, int DIM1, int DIM2 )

  • (   int DIM1, int DIM2, DATA_TYPE* INPLACE_ARRAY2 )

  • (   DATA_TYPE* INPLACE_FARRAY2, int DIM1, int DIM2 )

  • (   int DIM1, int DIM2, DATA_TYPE* INPLACE_FARRAY2 )

3D

  • (   DATA_TYPE INPLACE_ARRAY3[ANY][ANY][ANY] )

  • (   DATA_TYPE* INPLACE_ARRAY3, int DIM1, int DIM2, int DIM3 )

  • (   int DIM1, int DIM2, int DIM3, DATA_TYPE* INPLACE_ARRAY3 )

  • (   DATA_TYPE* INPLACE_FARRAY3, int DIM1, int DIM2, int DIM3 )

  • (   int DIM1, int DIM2, int DIM3, DATA_TYPE* INPLACE_FARRAY3 )

4D

  • (DATA_TYPE INPLACE_ARRAY4[ANY][ANY][ANY][ANY])

  • (DATA_TYPE* INPLACE_ARRAY4, DIM_TYPE DIM1, DIM_TYPE DIM2, DIM_TYPE DIM3, DIM_TYPE DIM4)

  • (DIM_TYPE DIM1, DIM_TYPE DIM2, DIM_TYPE DIM3, , DIM_TYPE DIM4, DATA_TYPE* INPLACE_ARRAY4)

  • (DATA_TYPE* INPLACE_FARRAY4, DIM_TYPE DIM1, DIM_TYPE DIM2, DIM_TYPE DIM3, DIM_TYPE DIM4)

  • (DIM_TYPE DIM1, DIM_TYPE DIM2, DIM_TYPE DIM3, DIM_TYPE DIM4, DATA_TYPE* INPLACE_FARRAY4)

这些类型映射现在会检查以确保 INPLACE_ARRAY 参数使用原生字节顺序。如果不是，则会引发异常。

还有一种“扁平”原地数组，用于您希望修改或处理每个元素而不管维度数量的情况。一个例子是“量化”函数，它会原地量化数组的每个元素，无论是 1D、2D 还是其他。这种形式检查连续性，但允许 C 或 Fortran 顺序。

ND

  • (DATA_TYPE* INPLACE_ARRAY_FLAT, DIM_TYPE DIM_FLAT)

输出参数数组#

输出参数数组（Argout arrays）是那些在 C 语言中作为输入参数出现，但实际上是输出数组的数组。当存在多个输出变量且单个返回值不足时，这种模式经常出现。在 Python 中，返回多个参数的常规方法是将它们打包成一个序列（元组、列表等）并返回该序列。这就是输出参数类型映射所做的。如果使用这些输出参数类型映射的包装函数有多个返回值，它们将被打包成一个元组或列表，具体取决于 Python 版本。Python 用户无需传入这些数组，它们会直接被返回。对于指定维度的情况，Python 用户必须将该维度作为参数提供。输出参数签名是

1D

  • (   DATA_TYPE ARGOUT_ARRAY1[ANY] )

  • (   DATA_TYPE* ARGOUT_ARRAY1, int DIM1 )

  • (   int DIM1, DATA_TYPE* ARGOUT_ARRAY1 )

2D

  • (   DATA_TYPE ARGOUT_ARRAY2[ANY][ANY] )

3D

  • (   DATA_TYPE ARGOUT_ARRAY3[ANY][ANY][ANY] )

4D

  • (   DATA_TYPE ARGOUT_ARRAY4[ANY][ANY][ANY][ANY] )

这些通常用于 C/C++ 中，您会在堆上分配一个或多个数组，并调用函数来填充数组值的情况。在 Python 中，数组会为您分配，并作为新的数组对象返回。

请注意，我们支持 1D 的 DATA_TYPE* 输出参数类型映射，但不支持 2D 或 3D。这是由于 SWIG 类型映射语法的一个怪癖，无法避免。请注意，对于这些 1D 类型映射，Python 函数将接受一个表示 DIM1 的单一参数。

输出参数视图数组#

输出参数视图数组（Argoutview arrays）适用于您的 C 代码提供其内部数据的视图，并且不需要用户分配任何内存的情况。这可能是危险的。几乎无法保证 C 代码的内部数据在封装它的 NumPy 数组的整个生命周期内都存在。如果用户在销毁 NumPy 数组之前销毁了提供数据视图的对象，那么使用该数组可能会导致错误的内存引用或段错误。尽管如此，在处理大型数据集时，有时您别无选择。

用于输出参数视图数组的 C 包装代码的特点是使用指针：指向维度的指针和指向数据的双重指针，以便这些值可以传递回给用户。因此，输出参数视图类型映射签名是

1D

  • ( DATA_TYPE** ARGOUTVIEW_ARRAY1, DIM_TYPE* DIM1 )

  • ( DIM_TYPE* DIM1, DATA_TYPE** ARGOUTVIEW_ARRAY1 )

2D

  • ( DATA_TYPE** ARGOUTVIEW_ARRAY2, DIM_TYPE* DIM1, DIM_TYPE* DIM2 )

  • ( DIM_TYPE* DIM1, DIM_TYPE* DIM2, DATA_TYPE** ARGOUTVIEW_ARRAY2 )

  • ( DATA_TYPE** ARGOUTVIEW_FARRAY2, DIM_TYPE* DIM1, DIM_TYPE* DIM2 )

  • ( DIM_TYPE* DIM1, DIM_TYPE* DIM2, DATA_TYPE** ARGOUTVIEW_FARRAY2 )

3D

  • ( DATA_TYPE** ARGOUTVIEW_ARRAY3, DIM_TYPE* DIM1, DIM_TYPE* DIM2, DIM_TYPE* DIM3)

  • ( DIM_TYPE* DIM1, DIM_TYPE* DIM2, DIM_TYPE* DIM3, DATA_TYPE** ARGOUTVIEW_ARRAY3)

  • ( DATA_TYPE** ARGOUTVIEW_FARRAY3, DIM_TYPE* DIM1, DIM_TYPE* DIM2, DIM_TYPE* DIM3)

  • ( DIM_TYPE* DIM1, DIM_TYPE* DIM2, DIM_TYPE* DIM3, DATA_TYPE** ARGOUTVIEW_FARRAY3)

4D

  • (DATA_TYPE** ARGOUTVIEW_ARRAY4, DIM_TYPE* DIM1, DIM_TYPE* DIM2, DIM_TYPE* DIM3, DIM_TYPE* DIM4)

  • (DIM_TYPE* DIM1, DIM_TYPE* DIM2, DIM_TYPE* DIM3, DIM_TYPE* DIM4, DATA_TYPE** ARGOUTVIEW_ARRAY4)

  • (DATA_TYPE** ARGOUTVIEW_FARRAY4, DIM_TYPE* DIM1, DIM_TYPE* DIM2, DIM_TYPE* DIM3, DIM_TYPE* DIM4)

  • (DIM_TYPE* DIM1, DIM_TYPE* DIM2, DIM_TYPE* DIM3, DIM_TYPE* DIM4, DATA_TYPE** ARGOUTVIEW_FARRAY4)

请注意，不支持具有硬编码维度的数组。这些不能遵循这些类型映射的双重指针签名。

内存管理的输出参数视图数组#

numpy.i 最近新增了允许输出参数数组（带有对已管理内存的视图）的类型映射。

1D

  • (DATA_TYPE** ARGOUTVIEWM_ARRAY1, DIM_TYPE* DIM1)

  • (DIM_TYPE* DIM1, DATA_TYPE** ARGOUTVIEWM_ARRAY1)

2D

  • (DATA_TYPE** ARGOUTVIEWM_ARRAY2, DIM_TYPE* DIM1, DIM_TYPE* DIM2)

  • (DIM_TYPE* DIM1, DIM_TYPE* DIM2, DATA_TYPE** ARGOUTVIEWM_ARRAY2)

  • (DATA_TYPE** ARGOUTVIEWM_FARRAY2, DIM_TYPE* DIM1, DIM_TYPE* DIM2)

  • (DIM_TYPE* DIM1, DIM_TYPE* DIM2, DATA_TYPE** ARGOUTVIEWM_FARRAY2)

3D

  • (DATA_TYPE** ARGOUTVIEWM_ARRAY3, DIM_TYPE* DIM1, DIM_TYPE* DIM2, DIM_TYPE* DIM3)

  • (DIM_TYPE* DIM1, DIM_TYPE* DIM2, DIM_TYPE* DIM3, DATA_TYPE** ARGOUTVIEWM_ARRAY3)

  • (DATA_TYPE** ARGOUTVIEWM_FARRAY3, DIM_TYPE* DIM1, DIM_TYPE* DIM2, DIM_TYPE* DIM3)

  • (DIM_TYPE* DIM1, DIM_TYPE* DIM2, DIM_TYPE* DIM3, DATA_TYPE** ARGOUTVIEWM_FARRAY3)

4D

  • (DATA_TYPE** ARGOUTVIEWM_ARRAY4, DIM_TYPE* DIM1, DIM_TYPE* DIM2, DIM_TYPE* DIM3, DIM_TYPE* DIM4)

  • (DIM_TYPE* DIM1, DIM_TYPE* DIM2, DIM_TYPE* DIM3, DIM_TYPE* DIM4, DATA_TYPE** ARGOUTVIEWM_ARRAY4)

  • (DATA_TYPE** ARGOUTVIEWM_FARRAY4, DIM_TYPE* DIM1, DIM_TYPE* DIM2, DIM_TYPE* DIM3, DIM_TYPE* DIM4)

  • (DIM_TYPE* DIM1, DIM_TYPE* DIM2, DIM_TYPE* DIM3, DIM_TYPE* DIM4, DATA_TYPE** ARGOUTVIEWM_FARRAY4)

输出数组#

numpy.i 接口文件不支持输出数组的类型映射，原因有几个。首先，C/C++ 的返回值仅限于单个值。这使得无法以通用方式获取维度信息。其次，长度硬编码的数组不允许作为返回值。换句话说

double[3] newVector(double x, double y, double z);

不是合法的 C/C++ 语法。因此，我们无法提供以下形式的类型映射

%typemap(out) (TYPE[ANY]);

如果您遇到函数或方法返回数组指针的情况，最好的办法是编写您自己的要包装的函数版本，对于类方法使用 %extend，对于函数使用 %ignore 和 %rename。

其他常见类型：bool#

请注意，可用类型映射 部分的列表中不支持 C++ 类型 bool。NumPy 的布尔值是一个字节，而 C++ 的 bool 是四个字节（至少在我的系统上是这样）。因此

%numpy_typemaps(bool, NPY_BOOL, int)

将导致类型映射生成引用不正确数据长度的代码。您可以实现以下宏扩展

%numpy_typemaps(bool, NPY_UINT, int)

以解决数据长度问题，输入数组 将正常工作，但原地数组 可能会类型检查失败。

其他常见类型：复数#

复数浮点类型的类型映射转换也不受自动支持。这是因为 Python 和 NumPy 是用 C 语言编写的，而 C 语言没有原生复数类型。Python 和 NumPy 都为复数变量实现了自己的（本质上等效的）struct 定义

/* Python */
typedef struct {double real; double imag;} Py_complex;

/* NumPy */
typedef struct {float  real, imag;} npy_cfloat;
typedef struct {double real, imag;} npy_cdouble;

我们本可以实现

%numpy_typemaps(Py_complex , NPY_CDOUBLE, int)
%numpy_typemaps(npy_cfloat , NPY_CFLOAT , int)
%numpy_typemaps(npy_cdouble, NPY_CDOUBLE, int)

这将为 Py_complex、npy_cfloat 和 npy_cdouble 类型的数组提供自动类型转换。然而，似乎不太可能有任何独立的（非 Python、非 NumPy）应用程序代码会使用 SWIG 生成 Python 接口，并且也使用这些定义来表示复数类型。更可能的是，这些应用程序代码将定义自己的复数类型，或者在 C++ 的情况下，使用 std::complex。假设这些数据结构与 Python 和 NumPy 复数类型兼容，那么上述 %numpy_typemap 扩展（将用户的复数类型替换为第一个参数）应该可以工作。

NumPy 数组标量与 SWIG#

SWIG 对数值类型具有复杂的类型检查功能。例如，如果您的 C/C++ 例程期望一个整数作为输入，则 SWIG 生成的代码将检查 Python 整数和 Python 长整数，如果提供的 Python 整数太大而无法转换为 C 整数，则会引发溢出错误。随着 NumPy 标量数组引入到您的 Python 代码中，您可能会从 NumPy 数组中提取一个整数，并尝试将其传递给一个期望 int 的 SWIG 包装 C/C++ 函数，但 SWIG 类型检查将无法识别 NumPy 数组标量为整数。（通常，这实际上是有效的——它取决于 NumPy 是否识别您正在使用的整数类型是从您正在使用的平台上的 Python 整数类型继承的。有时，这意味着在 32 位机器上能工作的代码在 64 位机器上会失败。）

如果您遇到类似以下的 Python 错误

TypeError: in method 'MyClass_MyMethod', argument 2 of type 'int'

并且您传递的参数是从 NumPy 数组中提取的整数，那么您就遇到了这个问题。解决方案是修改 SWIG 类型转换系统，使其除了标准整数类型外，还接受 NumPy 数组标量。幸运的是，此功能已为您提供。只需复制文件

pyfragments.swg

到您项目的工作构建目录，此问题即可解决。建议您无论如何都这样做，因为它只会增加您的 Python 接口的功能。

为什么有第二个文件？#

SWIG 类型检查和转换系统是 C 宏、SWIG 宏、SWIG 类型映射和 SWIG 片段的复杂组合。片段是一种根据需要有条件地将代码插入到包装器文件中的方式，如果不需要则不插入。如果多个类型映射需要相同的片段，则该片段只会插入到您的包装器代码中一次。

有一个片段用于将 Python 整数转换为 C 的 long 类型。还有一个不同的片段，用于将 Python 整数转换为 C 的 int 类型，它调用了 long 片段中定义的例程。我们可以通过修改 long 片段的定义来进行我们想要的更改。SWIG 使用“先到先得”的系统来确定片段的活动定义。也就是说，我们需要在 SWIG 内部进行 long 转换之前定义其片段。SWIG 允许我们通过将片段定义放在 pyfragments.swg 文件中来做到这一点。如果我们将新的片段定义放在 numpy.i 中，它们将被忽略。

辅助函数#

numpy.i 文件包含一些它在内部用于构建类型映射的宏和例程。然而，这些函数可能在你的接口文件的其他地方有用。这些宏和例程以片段的形式实现，上一节中对此进行了简要说明。如果您尝试使用以下一个或多个宏或函数，但编译器报错说无法识别该符号，则需要使用以下方式强制这些片段出现在您的代码中

%fragment("NumPy_Fragments");

在您的 SWIG 接口文件中。

宏#

is_array(a)

如果 a 非 NULL 且可以转换为 PyArrayObject*，则评估为真。

array_type(a)

如果 a 可以转换为 PyArrayObject*，则评估为 a 的整数数据类型代码。

array_numdims(a)

如果 a 可以转换为 PyArrayObject*，则评估为 a 的整数维度数量。

array_dimensions(a)

如果 a 可以转换为 PyArrayObject*，则评估为 npy_intp 类型且长度为 array_numdims(a) 的数组，给出 a 所有维度的长度。

array_size(a,i)

如果 a 可以转换为 PyArrayObject*，则评估为 a 的第 i 个维度的大小。

array_strides(a)

如果 a 可以转换为 PyArrayObject*，则评估为 npy_intp 类型且长度为 array_numdims(a) 的数组，给出 a 所有维度的步长。步长是元素与其沿同一轴的直接相邻元素之间的字节距离。

array_stride(a,i)

如果 a 可以转换为 PyArrayObject*，则评估为 a 的第 i 个步长。

array_data(a)

如果 a 可以转换为 PyArrayObject*，则评估为指向 a 数据缓冲区的 void* 类型指针。

array_descr(a)

如果 a 可以转换为 PyArrayObject*，则返回对 a 的 dtype 属性（PyArray_Descr*）的借用引用。

array_flags(a)

如果 a 可以转换为 PyArrayObject*，则返回一个整数，表示 a 的标志。

array_enableflags(a,f)

如果 a 可以转换为 PyArrayObject*，则设置 a 由 f 表示的标志。

array_is_contiguous(a)

如果 a 是一个连续数组，则评估为真。等同于 (PyArray_ISCONTIGUOUS(a))。

array_is_native(a)

如果 a 的数据缓冲区使用原生字节序，则评估为真。等同于 (PyArray_ISNOTSWAPPED(a))。

array_is_fortran(a)

如果 a 是 FORTRAN 顺序的，则评估为真。

例程#

pytype_string()

返回类型：const char*

参数

  • PyObject* py_obj，一个通用的 Python 对象。

返回描述 py_obj 类型的字符串。

typecode_string()

返回类型：const char*

参数

  • int typecode，一个 NumPy 整数类型代码。

返回描述 NumPy typecode 对应类型的字符串。

type_match()

返回类型：int

参数

  • int actual_type，一个 NumPy 数组的 NumPy 类型代码。

  • int desired_type，期望的 NumPy 类型代码。

确保 actual_type 与 desired_type 兼容。例如，这允许字符和字节类型，或 int 和 long 类型相互匹配。这现在等同于 PyArray_EquivTypenums()。

obj_to_array_no_conversion()

返回类型：PyArrayObject*

参数

  • PyObject* input，一个通用的 Python 对象。

  • int typecode，期望的 NumPy 类型代码。

如果合法，将 input 转换为 PyArrayObject*，并确保其类型为 typecode。如果 input 无法转换，或 typecode 错误，则设置 Python 错误并返回 NULL。

obj_to_array_allow_conversion()

返回类型：PyArrayObject*

参数

  • PyObject* input，一个通用的 Python 对象。

  • int typecode，结果数组期望的 NumPy 类型代码。

  • int* is_new_object，如果未执行转换则返回 0，否则返回 1。

将 input 转换为具有给定 typecode 的 NumPy 数组。成功时，返回一个具有正确类型的有效 PyArrayObject*。失败时，将设置 Python 错误字符串，例程返回 NULL。

make_contiguous()

返回类型：PyArrayObject*

参数

  • PyArrayObject* ary，一个 NumPy 数组。

  • int* is_new_object，如果未执行转换则返回 0，否则返回 1。

  • int min_dims，允许的最小维度数。

  • int max_dims，允许的最大维度数。

检查 ary 是否连续。如果是，返回输入指针并将其标记为非新对象。如果它不连续，则使用原始数据创建一个新的 PyArrayObject*，将其标记为新对象并返回指针。

make_fortran()

返回类型：PyArrayObject*

参数

  • PyArrayObject* ary，一个 NumPy 数组。

  • int* is_new_object，如果未执行转换则返回 0，否则返回 1。

检查 ary 是否 Fortran 连续。如果是，返回输入指针并将其标记为非新对象。如果它不是 Fortran 连续的，则使用原始数据创建一个新的 PyArrayObject*，将其标记为新对象并返回指针。

obj_to_array_contiguous_allow_conversion()

返回类型：PyArrayObject*

参数

  • PyObject* input，一个通用的 Python 对象。

  • int typecode，结果数组期望的 NumPy 类型代码。

  • int* is_new_object，如果未执行转换则返回 0，否则返回 1。

将 input 转换为指定类型的连续 PyArrayObject*。如果输入对象不是连续的 PyArrayObject*，则将创建一个新的，并设置新对象标志。

obj_to_array_fortran_allow_conversion()

返回类型：PyArrayObject*

参数

  • PyObject* input，一个通用的 Python 对象。

  • int typecode，结果数组期望的 NumPy 类型代码。

  • int* is_new_object，如果未执行转换则返回 0，否则返回 1。

将 input 转换为指定类型的 Fortran 连续 PyArrayObject*。如果输入对象不是 Fortran 连续的 PyArrayObject*，则将创建一个新的，并设置新对象标志。

require_contiguous()

返回类型：int

参数

  • PyArrayObject* ary，一个 NumPy 数组。

测试 ary 是否连续。如果是，返回 1。否则，设置 Python 错误并返回 0。

require_native()

返回类型：int

参数

  • PyArray_Object* ary，一个 NumPy 数组。

要求 ary 未进行字节交换。如果数组未进行字节交换，返回 1。否则，设置 Python 错误并返回 0。

require_dimensions()

返回类型：int

参数

  • PyArrayObject* ary，一个 NumPy 数组。

  • int exact_dimensions，期望的维度数量。

要求 ary 具有指定数量的维度。如果数组具有指定数量的维度，返回 1。否则，设置 Python 错误并返回 0。

require_dimensions_n()

返回类型：int

参数

  • PyArrayObject* ary，一个 NumPy 数组。

  • int* exact_dimensions，一个整数数组，表示可接受的维度数量。

  • int n，exact_dimensions 的长度。

要求 ary 具有指定维度数量列表中的一个。如果数组具有指定维度数量中的一个，返回 1。否则，设置 Python 错误字符串并返回 0。

require_size()

返回类型：int

参数

  • PyArrayObject* ary，一个 NumPy 数组。

  • npy_int* size，一个数组，表示每个维度的期望长度。

  • int n，size 的长度。

要求 ary 具有指定的形状。如果数组具有指定形状，返回 1。否则，设置 Python 错误字符串并返回 0。

require_fortran()

返回类型：int

参数

  • PyArrayObject* ary，一个 NumPy 数组。

要求给定的 PyArrayObject 为 Fortran 顺序。如果 PyArrayObject 已是 Fortran 顺序，则不做任何操作。否则，设置 Fortran 顺序标志并重新计算步长。

超出提供的类型映射#

有许多 C 或 C++ 数组/NumPy 数组情况，无法通过简单的 %include "numpy.i" 和后续的 %apply 指令来覆盖。

一个常见示例#

考虑一个合理的点积函数原型

double dot(int len, double* vec1, double* vec2);

我们想要的 Python 接口是

def dot(vec1, vec2):
    """
    dot(PyObject,PyObject) -> double
    """

这里的问题是有一个维度参数和两个数组参数，而我们的类型映射是为适用于单个数组的维度设置的（实际上，SWIG 没有提供一种机制来将 len 与接受两个 Python 输入参数的 vec2 关联起来）。推荐的解决方案如下

%apply (int DIM1, double* IN_ARRAY1) {(int len1, double* vec1),
                                      (int len2, double* vec2)}
%rename (dot) my_dot;
%exception my_dot {
    $action
    if (PyErr_Occurred()) SWIG_fail;
}
%inline %{
double my_dot(int len1, double* vec1, int len2, double* vec2) {
    if (len1 != len2) {
        PyErr_Format(PyExc_ValueError,
                     "Arrays of lengths (%d,%d) given",
                     len1, len2);
        return 0.0;
    }
    return dot(len1, vec1, vec2);
}
%}

如果包含 double dot() 原型的头文件还包含其他您想要包装的原型，以至于您需要 %include 这个头文件，那么您还需要一个 %ignore dot; 指令，放置在 %rename 之后和 %include 指令之前。或者，如果所讨论的函数是类方法，除了 %ignore 之外，您会希望使用 %extend 而不是 %inline。

关于错误处理的说明：请注意，my_dot 返回一个 double 类型的值，但它也可以引发 Python 错误。当向量长度不匹配时，生成的包装函数将返回 0.0 的 Python 浮点表示。由于这并非 NULL，Python 解释器将不知道检查错误。因此，我们为 my_dot 添加了上述 %exception 指令以获得我们想要的行为（请注意 $action 是一个宏，它会扩展为对 my_dot 的有效调用）。通常，您可能希望编写一个 SWIG 宏来执行此任务。

其他情况#

在您遇到其他包装情况时，numpy.i 可能有所帮助。

  • 在某些情况下，您可以使用 %numpy_typemaps 宏为自己的类型实现类型映射。请参阅其他常见类型：bool 或 其他常见类型：复数 部分以获取示例。另一种情况是，如果您的维度类型不是 int（例如 long）

    %numpy_typemaps(double, NPY_DOUBLE, long)

  • 您可以使用 numpy.i 中的代码来编写自己的类型映射。例如，如果您有一个五维数组作为函数参数，您可以将适当的四维类型映射剪切并粘贴到您的接口文件中。对第四维度的修改将是微不足道的。

  • 有时，最好的方法是使用 %extend 指令为您的类定义新方法（或重载现有方法），这些方法接受 PyObject*（可以是或可以转换为 PyArrayObject*），而不是指向缓冲区的指针。在这种情况下，numpy.i 中的辅助例程会非常有用。

  • 编写类型映射可能有点不直观。如果您对为 NumPy 编写 SWIG 类型映射有具体问题，numpy.i 的开发者会关注 Numpy-discussion 和 Swig-user 邮件列表。

最后一点说明#

当您使用 %apply 指令时（这通常是使用 numpy.i 所必需的），它将一直生效，直到您告诉 SWIG 不再需要它为止。如果您正在包装的函数或方法的参数具有常见的名称，例如 length 或 vector，这些类型映射可能会在您不期望或不希望的情况下应用。因此，在完成特定类型映射后，总是最好添加一个 %clear 指令

%apply (double* IN_ARRAY1, int DIM1) {(double* vector, int length)}
%include "my_header.h"
%clear (double* vector, int length);

通常，您应该在需要的地方明确指定这些类型映射签名，并在完成后清除它们。

总结#

开箱即用，numpy.i 提供了支持 NumPy 数组和 C 数组之间转换的类型映射

  • 这可以是 12 种不同的标量类型之一：signed char、unsigned char、short、unsigned short、int、unsigned int、long、unsigned long、long long、unsigned long long、float 和 double。

  • 支持每种数据类型 74 种不同的参数签名，包括

    • 一维、二维、三维和四维数组。

    • 只输入、原地、输出参数、输出参数视图和内存管理的输出参数视图行为。

    • 硬编码维度、数据缓冲区-后-维度规范以及维度-后-数据缓冲区规范。

    • 支持 2D、3D 和 4D 数组的 C 顺序（“最后维度最快”）或 Fortran 顺序（“第一维度最快”）。

numpy.i 接口文件还为包装器开发者提供了其他工具，包括

  • 一个带有三个参数的 SWIG 宏（%numpy_typemaps），用于实现用户选择的 (1) C 数据类型、(2) NumPy 数据类型（假设它们匹配）和 (3) 维度类型这 74 种参数签名。

  • 十四个 C 宏和十五个 C 函数，可用于编写处理未包含在提供的类型映射中的特殊类型映射、扩展或内联函数。请注意，这些宏和函数专门编写，以便与 NumPy C/API 配合使用，无论 NumPy 版本号如何，包括在 1.6 版本后 API 的某些方面被弃用之前和之后。