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

引言#

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

double rms(double* seq, int n);

seq 究竟是什么。它是一个要就地更改的单个值吗？它是一个数组吗？如果是，它的长度是多少？它是仅输入的吗？仅输出？输入输出？SWIG 无法确定这些细节，也不会尝试这样做。

如果我们设计了 rms，我们可能会将其设计为一个例程，该例程接收一个名为 seq 的长度为 n 的 double 值的仅输入数组，并返回均方根。但是，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 将在传递给 C 例程之前从 seq 内部提取。更好的是，由于 NumPy 支持从任意 Python 序列构造数组，seq 本身可以是一个几乎任意的序列（只要每个元素都可以转换为 double），包装器代码会在内部将其转换为 NumPy 数组，然后再提取其数据和长度。

SWIG 允许通过称为 *类型映射* 的机制定义这些类型的转换。本文档提供有关如何使用 numpy.i 的信息，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 接口文件将生成如下所示的包装器代码：

PyObject *_wrap_rms(PyObject *args) {
 PyObject *resultobj = 0;
 double *arg1 = (double *) 0 ;
 int arg2 ;
 double result;
 PyArrayObject *array1 = NULL ;
 int is_new_object1 = 0 ;
 PyObject * obj0 = 0 ;
 9
 if (!PyArg_ParseTuple(args,(char *)"O:rms",&obj0)) SWIG_fail;
 {
   array1 = obj_to_array_contiguous_allow_conversion(
                obj0, NPY_DOUBLE, &is_new_object1);
   npy_intp size[1] = {
     -1
   };
   if (!array1 || !require_dimensions(array1, 1) ||
       !require_size(array1, size, 1)) SWIG_fail;
   arg1 = (double*) array1->data;
   arg2 = (int) array1->dimensions[0];
 }
 result = (double)rms(arg1,arg2);
 resultobj = SWIG_From_double((double)(result));
 {
   if (is_new_object1 && array1) Py_DECREF(array1);
 }
 return resultobj;
fail:
 {
   if (is_new_object1 && array1) Py_DECREF(array1);
 }
 return NULL;
}

来自 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 顺序（或一维）数组。

输入数组#

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

一维

( DATA_TYPE IN_ARRAY1[ANY] )
( DATA_TYPE* IN_ARRAY1, int DIM1 )
( int DIM1, DATA_TYPE* IN_ARRAY1 )

二维

( 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 )

三维

( 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 )

四维

(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 数组。就地签名如下：

一维

( DATA_TYPE INPLACE_ARRAY1[ANY] )
( DATA_TYPE* INPLACE_ARRAY1, int DIM1 )
( int DIM1, DATA_TYPE* INPLACE_ARRAY1 )

二维

( 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 )

三维

( 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 )

四维

(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 顺序。

N 维

(DATA_TYPE* INPLACE_ARRAY_FLAT, DIM_TYPE DIM_FLAT)

输出参数数组#

输出参数数组是在 C 中作为输入参数出现的数组，但实际上是输出数组。当有多个输出变量且单个返回参数不足时，这种模式经常出现。在 Python 中，返回多个参数的常规方法是将它们打包到一个序列（元组、列表等）中并返回该序列。这就是输出参数类型映射所做的工作。如果使用这些输出参数类型映射的包装函数具有多个返回参数，则根据 Python 的版本，它们将被打包到元组或列表中。Python 用户不会传入这些数组，它们只是被返回。对于指定维度的案例，Python 用户必须提供该维度作为参数。输出参数签名如下：

一维

( DATA_TYPE ARGOUT_ARRAY1[ANY] )
( DATA_TYPE* ARGOUT_ARRAY1, int DIM1 )
( int DIM1, DATA_TYPE* ARGOUT_ARRAY1 )

二维

( DATA_TYPE ARGOUT_ARRAY2[ANY][ANY] )

三维

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

四维

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

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

请注意，我们支持一维 DATA_TYPE* argout 类型映射，但不支持二维或三维。这是由于 SWIG 类型映射语法的一个特性，无法避免。请注意，对于这些类型的一维类型映射，Python 函数将接收一个表示 DIM1 的单个参数。

Argout 视图数组#

Argoutview 数组用于您的 C 代码提供其内部数据的视图，并且不需要用户分配任何内存的情况。这可能很危险。几乎无法保证 C 代码的内部数据在封装它的 NumPy 数组的整个生命周期中都将存在。如果用户在销毁 NumPy 数组之前销毁了提供数据视图的对象，则使用该数组可能会导致错误的内存引用或段错误。然而，在处理大型数据集的情况下，您别无选择。

用于 argoutview 数组的 C 代码包装的特点是使用指针：指向维度的指针和指向数据的双重指针，以便可以将这些值传递回用户。因此，argoutview 类型映射签名如下所示：

一维

( DATA_TYPE** ARGOUTVIEW_ARRAY1, DIM_TYPE* DIM1 )
( DIM_TYPE* DIM1, DATA_TYPE** ARGOUTVIEW_ARRAY1 )

二维

( 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 )

三维

( 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)

四维

(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)

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

内存管理的 Argout 视图数组#

numpy.i 的最新添加是允许使用指向已管理内存的视图的 argout 数组的类型映射。

一维

(DATA_TYPE** ARGOUTVIEWM_ARRAY1, DIM_TYPE* DIM1)
(DIM_TYPE* DIM1, DATA_TYPE** ARGOUTVIEWM_ARRAY1)

二维

(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)

三维

(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)

四维

(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)

来修复数据长度问题，并且输入数组将正常工作，但就地数组可能会发生类型检查失败。

其他常用类型：complex#

也不自动支持复数浮点类型的类型映射转换。这是因为 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 整型，则会引发溢出错误。当您在 Python 代码中引入 NumPy 标量数组时，您可能会从 NumPy 数组中提取一个整数，并尝试将其传递给 SWIG 包装的 C/C++ 函数（该函数需要一个int 类型），但是 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): 计算结果为一个类型为npy_intp且长度为array_numdims(a)的数组，给出a所有维度的长度，假设a可以转换为PyArrayObject*。
array_size(a,i): 假设a可以转换为PyArrayObject*，则计算结果为a的第i维大小。
array_strides(a): 计算结果为一个类型为npy_intp且长度为array_numdims(a)的数组，给出a所有维度的步长，假设a可以转换为PyArrayObject*。步长是元素与其沿同一轴的直接邻居之间的字节距离。
array_stride(a,i): 假设a可以转换为PyArrayObject*，则计算结果为a的第i个步长。
array_data(a): 假设a可以转换为PyArrayObject*，则计算结果为一个指向a数据缓冲区的void*类型指针。
array_descr(a): 返回对a的 dtype 属性（PyArray_Descr*）的借用引用，假设a可以转换为PyArrayObject*。
array_flags(a): 返回一个整数，表示a的标志，假设a可以转换为PyArrayObject*。
array_enableflags(a,f): 设置a中由f表示的标志，假设a可以转换为PyArrayObject*。
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或其他常用类型：complex部分。另一种情况是，如果您的维度不是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 种不同的参数签名，包括：
- 一维、二维、三维和四维数组。
- 仅输入、就地、argout、argoutview 和内存管理 argoutview 行为。
- 硬编码维度、数据缓冲区后维度规范和维度后数据缓冲区规范。
- 对于二维、三维和四维数组，都支持 C 顺序（“最后一维最快”）或 Fortran 顺序（“第一维最快”）。

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

一个 SWIG 宏（%numpy_typemaps），带三个参数，用于实现用户选择的 (1) C 数据类型、(2) NumPy 数据类型（假设它们匹配）和 (3) 维度类型的 74 个参数签名。
十四个 C 宏和十五个 C 函数，可用于编写专门的类型映射、扩展或内联函数，以处理提供的类型映射未涵盖的情况。请注意，这些宏和函数的编码专门用于与 NumPy C/API 协同工作，无论 NumPy 版本号如何，都在 API 的 1.6 版本之后某些方面弃用之前和之后。