numpy.i: SWIG 的 NumPy 接口文件#
引言#
Simple Wrapper and Interface Generator (或 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 将在传递给 C 例程之前在内部从 seq 中提取。更好的是，由于 NumPy 支持从任意 Python 序列构建数组，seq 本身可以是一个几乎任意的序列（只要每个元素都可以转换为 double），并且包装代码将内部将其转换为 NumPy 数组，然后再提取其数据和长度。
SWIG 允许通过一种称为类型映射（typemaps）的机制来定义此类转换。本文档提供了有关如何使用 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 接口文件将生成如下的包装代码：
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 charunsigned charshortunsigned shortintunsigned intlongunsigned longlong longunsigned long longfloatdouble
在以下描述中，我们引用了一个通用的 DATA_TYPE，它可以是上面列出的任何 C 数据类型，以及 DIM_TYPE，它应该是众多整数类型之一。
类型映射签名主要通过缓冲区指针的名称来区分。名称包含 FARRAY 的是 Fortran 顺序数组，名称包含 ARRAY 的是 C 顺序（或一维）数组。
输入数组#
输入数组定义为传递给例程但不会原地修改或返回给用户的数组。因此，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 数组#
Argout 数组是在 C 中出现在输入参数中，但实际上是输出数组的数组。当有多个输出变量且单个返回值不足以满足需求时，这种模式很常见。在 Python 中，返回多个参数的约定方式是将它们打包到一个序列（元组、列表等）中并返回该序列。这就是 argout 类型映射所做的。如果使用这些 argout 类型映射的包装函数有多个返回值，它们将被打包到元组或列表中，具体取决于 Python 版本。Python 用户不传递这些数组，它们只是被返回。对于指定了维度的场景，Python 用户必须将该维度作为参数提供。argout签名是
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 中，数组会被为您分配并作为新的数组对象返回。
请注意，我们支持一维的 DATA_TYPE* argout 类型映射，但不支持二维或三维。这是由于 SWIG 类型映射语法的怪癖所致，无法避免。请注意，对于这类一维类型映射，Python 函数将接受一个代表 DIM1 的单个参数。
Argout 视图数组#
Argoutview 数组适用于 C 代码为您提供其内部数据的视图，并且不需要用户分配任何内存的情况。这可能很危险。几乎无法保证 C 代码的内部数据会在封装它的 NumPy 数组的整个生命周期内都保持存在。如果用户在销毁 NumPy 数组之前销毁了提供数据视图的对象，那么使用该数组可能会导致错误的内存引用或段错误。尽管如此，在处理大型数据集的情况下，有时您别无选择。
要为 argoutview 数组包装的 C 代码的特征是指针：指向维度的指针和指向数据的双指针，以便这些值可以传递回用户。因此，argout视图类型映射签名是
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)
请注意，不支持带有硬编码维度的数组。这些数组无法遵循这些类型映射的双指针签名。
内存管理的 Argout 视图数组#
numpy.i 的一个近期新增功能是类型映射，它允许 argout 数组视图指向已管理的内存。
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 的 bool 是一个字节，而 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 类型的数组提供自动类型转换。然而，似乎不太可能存在人们会使用 SWIG 来生成 Python 接口的独立（非 Python、非 NumPy）应用程序代码，该代码也使用这些复数类型的定义。更有可能的是，这些应用程序代码将定义自己的复数类型，或者在 C++ 的情况下，使用 std::complex。假设这些数据结构与 Python 和 NumPy 的复数类型兼容，那么如上所示的 %numpy_typemap 扩展（将用户的复数类型替换为第一个参数）应该可以工作。
NumPy 数组标量和 SWIG#
SWIG 对数值类型具有复杂的类型检查。例如，如果您的 C/C++ 例程需要整数作为输入，SWIG 生成的代码将同时检查 Python 整数和 Python 长整数，并在提供的 Python 整数太大而无法转换为 C 整数时引发溢出错误。随着 NumPy 标量数组引入到您的 Python 代码中，您可能会从 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)
假设
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*，则计算结果为类型为void*的指针，指向a的数据缓冲区。- array_descr(a)
假设
a可以转换为PyArrayObject*，则返回a的 dtype 属性 (PyArray_Descr*) 的借用引用。- array_flags(a)
假设
a可以转换为PyArrayObject*，则返回一个表示a标志的整数。- array_enableflags(a,f)
假设
a可以转换为PyArrayObject*，则设置f所表示的a的标志。- 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兼容。例如，这允许字符和字节类型，或整数和长整数类型匹配。这现在等同于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 与 vec2 关联的机制，后者接受两个 Python 输入参数）。推荐的解决方案是
%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 float 表示。由于这不是 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 种不同的参数签名，包括
一维、二维、三维和四维数组。
仅输入、原地、输出、输出视图和内存管理的输出视图行为。
硬编码维度、数据缓冲区然后是维度规范，以及维度然后是数据缓冲区规范。
C 顺序（“最后一个维度最快”）或 Fortran 顺序（“第一个维度最快”）对二维、三维和四维数组的支持。
numpy.i 接口文件还为包装开发者提供了其他工具，包括
一个带有三个参数的 SWIG 宏（
%numpy_typemaps），用于实现 74 个参数签名，为用户选择（1）C 数据类型、（2）NumPy 数据类型（假设它们匹配）和（3）维度类型。十四个 C 宏和十五个 C 函数，可用于编写处理所提供类型映射未涵盖的特殊情况的专用类型映射、扩展或内联函数。请注意，这些宏和函数经过专门编码，可与 NumPy C/API 配合使用，而与 NumPy 版本号无关，无论是在 API 的某些方面在 1.6 版本之后被弃用之前还是之后。