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, который предоставляет полный объектно-ориентированный доступ к многомерным массивам данных. Поэтому наиболее логичным интерфейсом Python для функции rms была бы (включая строку документации):

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

где seq — массив NumPy значений double, а его длина n извлекается из seq внутри перед передачей в функцию на C. Ещё лучше, поскольку NumPy поддерживает создание массивов из произвольных последовательностей Python, seq может быть практически любой последовательностью (при условии, что каждый элемент может быть преобразован в double) и код обёртки преобразует её во внутренний массив NumPy перед извлечением его данных и длины.

SWIG позволяет определять эти типы преобразований с помощью механизма, называемого typemaps. Этот документ содержит информацию о том, как использовать numpy.i, файл интерфейса SWIG, который определяет набор typemaps, призванных сделать преобразования, связанные с массивами, описанными выше, относительно простыми в реализации. Например, предположим, что прототип функции 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"

Typemaps основаны на списке одного или нескольких аргументов функции, либо по типу, либо по типу и имени. Мы будем называть такие списки подписями. Одна из многих typemaps, определённых в numpy.i, используется выше и имеет подпись (double* IN_ARRAY1, int DIM1). Имена аргументов предполагают, что аргумент double* является одномерным массивом входных данных, а int представляет размер этого измерения. Это точно соответствует шаблону в прототипе rms.

Вероятнее всего, у реальных прототипов, которые необходимо обернуть, не будет аргументов с именами IN_ARRAY1 и DIM1. Мы используем директиву SWIG %apply для применения typemap для одномерных массивов входных данных типа double к фактическому прототипу, используемому в rms. Для эффективного использования numpy.i необходимо знать, какие typemaps доступны и что они делают.

Файл интерфейса 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 }

Typemaps из numpy.i отвечают за следующие строки кода: 12–20, 25 и 30. Строка 10 анализирует входные данные для функции rms. Из строковой переменной формата "O:rms" можно увидеть, что список аргументов должен представлять собой единственный объект Python (указанный O перед двоеточием), указатель которого хранится в obj0. Ряд функций, предоставленных numpy.i, вызывается для создания и проверки возможного преобразования из общего объекта Python в массив NumPy. Эти функции объяснены в разделе Вспомогательные функции, но, надеюсь, их названия понятны. В строке 12 мы используем obj0 для создания массива NumPy. В строке 17 мы проверяем корректность результата: что он не равен нулю и имеет одно измерение произвольной длины. После проверки этих состояний мы извлекаем буфер данных и длину в строках 19 и 20, чтобы вызвать основную функцию C в строке 22. Строка 25 выполняет управление памятью в случае, если мы создали новый массив, который больше не нужен.

В этом коде есть значительное количество обработки ошибок. Обратите внимание, что SWIG_fail — это макрос для goto fail, ссылающийся на метку в строке 28. Если пользователь предоставляет неправильное количество аргументов, это будет обнаружено в строке 10. Если создание массива NumPy завершится неудачей или создаст массив с неправильным количеством измерений, эти ошибки будут обнаружены в строке 17. И наконец, если ошибка обнаружена, память всё ещё обрабатывается правильно в строке 30.

Обратите внимание, что если сигнатура функции C была в другом порядке:

double rms(int n, double* seq);

то SWIG не сопоставит подпись typemap, указанную выше, со списком аргументов для rms. К счастью, numpy.i имеет набор typemaps, в которых указатель данных задан последним:

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

Это просто поменяет определения arg1 и arg2 в строках 3 и 4 сгенерированного кода выше и их присвоение в строках 19 и 20.

Использование numpy.i

Файл numpy.i в настоящее время находится в подкаталоге tools/swig в каталоге установки numpy. Как правило, вы захотите скопировать его в каталог, где вы разрабатываете свои обёртки.

Простой модуль, использующий только один файл интерфейса 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().

Доступные typemaps

Директивы typemap, предоставляемые numpy.i для массивов различных типов данных, например, double и int, и измерений различных типов, например, int или long, идентичны друг другу, за исключением спецификаций типов C и NumPy. Поэтому typemaps реализованы (обычно за кулисами) с помощью макроса:

%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 для реализации 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, который должен быть одним из многих типов целых чисел.

Подписи typemaps в значительной степени различаются по имени указателя буфера. Имена с 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 в 1D, но не в 2D или 3D. Это связано со спецификой синтаксиса типомэпов SWIG и его нельзя избежать. Обратите внимание, что для этих типов типомэпов 1D функция Python будет принимать один аргумент, представляющий DIM1.

Argout View массивы

Argoutview массивы используются, когда ваш код C предоставляет вам представление своих внутренних данных и не требует выделения памяти пользователем. Это может быть опасно. Практически невозможно гарантировать, что внутренние данные из кода C будут существовать в течение всего срока существования массива NumPy, который их оборачивает. Если пользователь уничтожит объект, предоставляющий представление данных, до уничтожения массива NumPy, то использование этого массива может привести к ошибке обращения к памяти или сегменту нарушению. Тем не менее, существуют ситуации, работая с большими наборами данных, когда у вас нет другого выбора.

Код C для обертывания argoutview массивов характеризуется указателями: указателями на измерения и двойными указателями на данные, чтобы эти значения могли быть переданы обратно пользователю. Поэтому подписи типомэпов argoutview:

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 View массивы

Недавнее дополнение к 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++. Поэтому мы не можем предоставить типомэпы вида:

%numpy_typemaps(bool, NPY_BOOL, int)

Если у вас возникла ситуация, когда функция или метод возвращает указатель на массив, ваш лучший вариант — написать свою версию обертываемой функции, либо с %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, который не имеет встроенных комплексных типов. 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 и попытаетесь передать его обернутой 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 определяет активное определение для фрагмента, используя систему «первый пришёл, первый обслужен». То есть, нам нужно определить фрагмент для преобразований long до того, как SWIG сделает это внутренне. SWIG позволяет нам сделать это, поместив определения наших фрагментов в файл pyfragments.swg. Если мы поместим новые определения фрагментов в numpy.i, они будут проигнорированы.

Функции-помощники

Файл numpy.i содержит несколько макросов и процедур, которые он использует во внутренней работе для построения своих typemap. Однако, эти функции могут быть полезны и в других местах вашего интерфейсного файла. Эти макросы и процедуры реализованы как фрагменты, кратко описанные в предыдущем разделе. Если вы попытаетесь использовать один или несколько из следующих макросов или функций, но ваш компилятор сообщит, что он не распознаёт символ, то вам необходимо принудительно вставить эти фрагменты в ваш код, используя:

%fragment("NumPy_Fragments");

в вашем интерфейсном файле SWIG.

Макросы

is_array(a): Вычисляется как true, если a не NULL и может быть приведено к PyArrayObject*.
array_type(a): Вычисляется в целочисленный код типа данных a, предполагая, что a может быть приведено к PyArrayObject*.
array_numdims(a): Вычисляется в целочисленное количество измерений a, предполагая, что a может быть приведено к PyArrayObject*.
array_dimensions(a): Вычисляется в массив типа npy_intp и длиной array_numdims(a), дающий длины всех измерений a, предполагая, что a может быть приведено к PyArrayObject*.
array_size(a,i): Вычисляется в размер i-го измерения a, предполагая, что a может быть приведено к PyArrayObject*.
array_strides(a): Вычисляется в массив типа npy_intp и длиной array_numdims(a), дающий шаги всех измерений a, предполагая, что a может быть приведено к PyArrayObject*. Шаг - это расстояние в байтах между элементом и его непосредственным соседом вдоль той же оси.
array_stride(a,i): Вычисляется в i-й шаг a, предполагая, что a может быть приведено к PyArrayObject*.
array_data(a): Вычисляется в указатель типа void*, указывающий на буфер данных a, предполагая, что a может быть приведено к PyArrayObject*.
array_descr(a): Возвращает ссылку на заимствованный объект dtype (PyArray_Descr*) a, предполагая, что a может быть приведено к PyArrayObject*.
array_flags(a): Возвращает целое число, представляющее флаги a, предполагая, что a может быть приведено к PyArrayObject*.
array_enableflags(a,f): Устанавливает флаг, представленный f для a, предполагая, что a может быть приведено к PyArrayObject*.
array_is_contiguous(a): Вычисляется как true, если a является непрерывным массивом. Эквивалентно (PyArray_ISCONTIGUOUS(a)).
array_is_native(a): Вычисляется как true, если буфер данных a использует родной порядок байтов. Эквивалентно (PyArray_ISNOTSWAPPED(a)).
array_is_fortran(a): Вычисляется как true, если 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()