Как расширить NumPy

Функции без ключевых аргументов

Функции, которые не принимают ключевые аргументы, должны быть написаны так:

static PyObject*
nokeyword_cfunc (PyObject *dummy, PyObject *args)
{
    /* convert Python arguments */
    /* do function */
    /* return something */
}

Аргумент dummy в этом контексте не используется и может быть безопасно проигнорирован. Аргумент args содержит все аргументы, переданные функции в виде кортежа. Вы можете делать все, что угодно на этом этапе, но обычно самый простой способ управления входными аргументами — вызвать PyArg_ParseTuple (args, format_string, адреса_C_переменных…) или PyArg_UnpackTuple (кортеж, “имя”, мин, макс, …). Хорошее описание того, как использовать первую функцию, содержится в справочнике по Python C-API в разделе 5.5 (Разбор аргументов и построение значений). Обратите особое внимание на формат “O&”, который использует функции преобразования для перехода между объектом Python и объектом C. Все остальные функции форматирования можно (по большей части) рассматривать как частные случаи этого общего правила. В NumPy C-API определены несколько функций преобразования, которые могут быть полезны. В частности, функция PyArray_DescrConverter очень полезна для поддержки произвольного задания типов данных. Эта функция преобразует любой допустимый объект типа данных Python в объект PyArray_Descr*.

В исходном коде NumPy есть множество примеров использования PyArg_ParseTuple. Стандартное использование выглядит так:

PyObject *input;
PyArray_Descr *dtype;
if (!PyArg_ParseTuple(args, "OO&", &input,
                      PyArray_DescrConverter,
                      &dtype)) return NULL;

Важно помнить, что при использовании строки формата “O” вы получаете заимствованную ссылку на объект. Однако функции преобразования обычно требуют некоторой обработки памяти. В этом примере, если преобразование успешно, dtype будет содержать новую ссылку на объект PyArray_Descr*, а input — заимствованную ссылку. Поэтому, если это преобразование было бы смешано с другим преобразованием (скажем, в целое число) и преобразование типа данных прошло успешно, но преобразование целого числа потерпело неудачу, то вам нужно будет освободить счетчик ссылок на объект типа данных перед возвращением. Типичный способ сделать это — установить dtype в NULL перед вызовом PyArg_ParseTuple, а затем использовать Py_XDECREF для dtype перед возвращением.

После обработки входных аргументов пишется код, который фактически выполняет работу (вероятно, вызывая другие функции по мере необходимости). Последним этапом функции C является возврат чего-либо. Если возникла ошибка, то необходимо вернуть NULL (убедившись, что ошибка действительно установлена). Если ничего не должно быть возвращено, то увеличьте счетчик Py_None и верните его. Если должен быть возвращен один объект, то он возвращается (убедившись, что у вас есть ссылка на него). Если должны быть возвращены несколько объектов, то нужно вернуть кортеж. Функция Py_BuildValue (строка_формата, c_переменные…) упрощает построение кортежей объектов Python из переменных C. Обратите особое внимание на разницу между ‘N’ и ‘O’ в строке формата, иначе вы можете легко создать утечки памяти. Строка формата ‘O’ увеличивает счетчик ссылок на переменную C PyObject*, а строка формата ‘N’ захватывает ссылку на соответствующую переменную C PyObject*. Вы должны использовать ‘N’, если вы уже создали ссылку на объект и просто хотите предоставить эту ссылку кортежу. Вы должны использовать ‘O’, если у вас есть только заимствованная ссылка на объект и вам нужно создать новую, чтобы предоставить её кортежу.

Функции с ключевыми аргументами

Эти функции очень похожи на функции без ключевых аргументов. Единственное отличие в том, что сигнатура функции выглядит так:

static PyObject*
keyword_cfunc (PyObject *dummy, PyObject *args, PyObject *kwds)
{
...
}

Аргумент kwds содержит словарь Python, ключами которого являются имена ключевых аргументов, а значениями — соответствующие значения ключевых аргументов. Этот словарь можно обработать любым удобным для вас способом. Однако самый простой способ обработки — заменить функцию PyArg_ParseTuple (args, строка_формата, адреса…) вызовом PyArg_ParseTupleAndKeywords (args, kwds, строка_формата, массив_строк_kwlist[], адреса…). Параметр kwlist этой функции представляет собой массив строк, завершающийся NULL и предоставляющий ожидаемые ключевые аргументы. Должна быть одна строка для каждого элемента в строке формата. При использовании этой функции будет поднята ошибка TypeError, если переданы недопустимые ключевые аргументы.

Дополнительную помощь по этой функции вы найдете в разделе 1.8 (Ключевые параметры для функций расширения) руководства по расширению и встраиванию в документации Python.

Счётчик ссылок

Самая большая сложность при написании модулей расширения — это счётчик ссылок. Это важная причина популярности f2py, weave, Cython, ctypes и т. д. Если вы неправильно обработаете счётчики ссылок, могут возникнуть проблемы, от утечек памяти до ошибок сегментации. Единственная стратегия, которую я знаю для корректной обработки счётчиков ссылок, — это труд, упорство и усилия. Сначала вы заставляете себя понять, что каждая переменная Python имеет счётчик ссылок. Затем вы точно понимаете, что делает каждая функция со счётчиком ссылок ваших объектов, чтобы правильно использовать DECREF и INCREF, когда это необходимо. Счётчик ссылок действительно может проверить ваш уровень терпения и старания в программировании. Несмотря на мрачную картину, в большинстве случаев счётчик ссылок довольно прост, а самой распространённой трудностью является то, что вы не используете DECREF для объектов перед преждевременным выходом из процедуры из-за какой-либо ошибки. На втором месте стоит распространённая ошибка — отсутствие владения ссылкой на объект, который передаётся в функцию или макрос, который собирается её украсть ( например PyTuple_SET_ITEM, и большинство функций, принимающих PyArray_Descr объекты).

Обычно вы получаете новую ссылку на переменную при её создании или в качестве результата выполнения некоторой функции (однако существуют некоторые заметные исключения — такие как получение элемента из кортежа или словаря). Когда вы владеете ссылкой, вы несёте ответственность за то, чтобы Py_DECREF (переменная) вызывался, когда переменная больше не нужна (и ни одна другая функция не «украла» её ссылку). Кроме того, если вы передаёте Python-объект функции, которая «украдёт» ссылку, убедитесь, что вы владеете ею (или используйте Py_INCREF чтобы получить свою собственную ссылку). Вы также встретите понятие заимствования ссылки. Функция, которая заимствует ссылку, не изменяет счётчик ссылок объекта и не ожидает «удержать» ссылку. Она просто временно использует объект. При использовании PyArg_ParseTuple или PyArg_UnpackTuple вы получаете заимствованную ссылку на объекты в кортеже и не должны изменять их счётчик ссылок внутри вашей функции. С практикой вы сможете правильно обработать счётчик ссылок, но вначале это может быть сложно.

Одним из распространённых источников ошибок счёта ссылок является функция Py_BuildValue. Внимательно обратите внимание на разницу между символом формата ‘N’ и символом формата ‘O’. Если вы создаёте новый объект в вашей подпрограмме (например, выходной массив), и вы передаёте его обратно в кортеже возвращаемых значений, скорее всего, вам следует использовать символ формата ‘N’ в Py_BuildValue. Символ ‘O’ увеличит счётчик ссылок на единицу. Это оставит вызывающую программу с двумя счётчиками ссылок для нового массива. Когда переменная удаляется, а счётчик ссылок уменьшается на единицу, всё ещё будет этот дополнительный счётчик ссылок, и массив никогда не будет освобождён. У вас будет утечка памяти, вызванная счётчиком ссылок. Использование символа ‘N’ позволит избежать этой ситуации, так как он вернёт вызывающей программе объект (внутри кортежа) с единственным счётчиком ссылок.

Преобразование произвольного последовательного объекта

Основная процедура получения массива из любого Python-объекта, который можно преобразовать в массив, — это PyArray_FromAny. Эта функция очень гибкая с множеством входных аргументов. Несколько макросов делают использование базовой функции проще. PyArray_FROM_OTF, пожалуй, самый полезный из этих макросов для наиболее распространённых случаев. Он позволяет преобразовать произвольный Python-объект в массив определённого встроенного типа данных ( например, float), при этом определяя определённый набор требований ( например, непрерывный, выровненный и доступный для записи). Синтаксис

PyArray_FROM_OTF

Возвращает ndarray из любого объекта Python, obj, который может быть преобразован в массив. Количество измерений в возвращаемом массиве определяется объектом. Желаемый тип данных возвращаемого массива задаётся в typenum, который должен быть одним из перечисленных типов. Требования к возвращаемому массиву могут быть любым сочетанием стандартных флагов массива. Каждый из этих аргументов поясняется более подробно ниже. Вы получаете новую ссылку на массив при успешном выполнении. В случае неудачи возвращается NULL и устанавливается исключение.

obj

Объект может быть любым объектом Python, преобразуемым в ndarray. Если объект уже является (подклассом) ndarray, удовлетворяющим требованиям, то возвращается новая ссылка. В противном случае создаётся новый массив. Содержимое obj копируется в новый массив, если не используется интерфейс массива, чтобы данные не приходилось копировать. Объекты, которые могут быть преобразованы в массив, включают: 1) любой вложенный последовательный объект, 2) любой объект, использующий интерфейс массива, 3) любой объект с методом __array__ (который должен возвращать ndarray), и 4) любой скалярный объект (превращается в массив нулевой размерности). Подклассы ndarray, которые в противном случае удовлетворяют требованиям, будут переданы без изменений. Если вы хотите гарантировать базовый массив ndarray, используйте NPY_ARRAY_ENSUREARRAY в флаге требований. Копия создаётся только при необходимости. Если вы хотите гарантировать копирование, передайте NPY_ARRAY_ENSURECOPY в флаг требований.

typenum

Один из перечисленных типов или NPY_NOTYPE, если тип данных должен определяться самим объектом. Можно использовать C-базовые имена:

NPY_BOOL, NPY_BYTE, NPY_UBYTE, NPY_SHORT, NPY_USHORT, NPY_INT, NPY_UINT, NPY_LONG, NPY_ULONG, NPY_LONGLONG, NPY_ULONGLONG, NPY_DOUBLE, NPY_LONGDOUBLE, NPY_CFLOAT, NPY_CDOUBLE, NPY_CLONGDOUBLE, NPY_OBJECT.

В качестве альтернативы, можно использовать имена с битовой шириной, поддерживаемые платформой. Например:

NPY_INT8, NPY_INT16, NPY_INT32, NPY_INT64, NPY_UINT8, NPY_UINT16, NPY_UINT32, NPY_UINT64, NPY_FLOAT32, NPY_FLOAT64, NPY_COMPLEX64, NPY_COMPLEX128.

Объект будет преобразован к нужному типу только если это возможно без потери точности. В противном случае возвращается NULL и возникает ошибка. Используйте NPY_ARRAY_FORCECAST в флаге требований, чтобы переопределить это поведение.

requirements

Модель памяти для ndarray допускает произвольные шаги в каждом измерении для перехода к следующему элементу массива. Однако часто необходимо взаимодействовать с кодом, который ожидает C-непрерывный или Fortran-непрерывный макет памяти. Кроме того, ndarray может быть невыровнен (адрес элемента не находится на целое кратное размера элемента), что может привести к сбою программы (или, по крайней мере, к более медленной работе), если вы попытаетесь обратиться к указателю в данные массива. Обе эти проблемы могут быть решены путём преобразования объекта Python в массив, который более «удобен» для вашего конкретного использования.

Флаг требований позволяет указать, какой тип массива приемлем. Если переданный объект не удовлетворяет этим требованиям, то создаётся копия, чтобы возвращаемый объект удовлетворял требованиям. Эти ndarray могут использовать очень общий указатель на память. Этот флаг позволяет указать желаемые свойства возвращаемого объекта массива. Все флаги объясняются в главе подробного API. Наиболее часто используемые флаги — NPY_ARRAY_IN_ARRAY, NPY_ARRAY_OUT_ARRAY и NPY_ARRAY_INOUT_ARRAY:

NPY_ARRAY_IN_ARRAY

Этот флаг полезен для массивов, которые должны быть C-непрерывными и выровненными. Такие массивы обычно являются входными массивами для некоторого алгоритма.

NPY_ARRAY_OUT_ARRAY

Этот флаг полезен для задания массива, который является C-непрерывным, выровненным и в который можно записывать. Такой массив обычно возвращается в качестве выходного (хотя обычно такие выходные массивы создаются заново).

NPY_ARRAY_INOUT_ARRAY

Этот флаг полезен для задания массива, который будет использоваться как для входных, так и для выходных данных. PyArray_ResolveWritebackIfCopy должен быть вызван перед Py_DECREF в конце процедуры интерфейса, чтобы записать временные данные обратно в исходный массив, переданный в качестве входного. Использование флага NPY_ARRAY_WRITEBACKIFCOPY требует, чтобы входной объект уже был массивом (потому что другие объекты не могут быть автоматически обновлены таким образом). Если произошла ошибка, используйте PyArray_DiscardWritebackIfCopy (obj) для массива с установленными этими флагами. Это сделает базовой массив доступным для записи без копирования содержимого обратно в исходный массив.

Другие полезные флаги, которые можно объединять как дополнительные требования, включают:

NPY_ARRAY_FORCECAST

Преобразование к нужному типу, даже если это невозможно без потери информации.

NPY_ARRAY_ENSURECOPY

Убедитесь, что полученный массив является копией оригинала.

NPY_ARRAY_ENSUREARRAY

Убедитесь, что полученный объект является фактически ndarray, а не подклассом.

Создание нового ndarray

Часто в коде расширений требуется создать новые массивы. Возможно, нужен выходной массив, и вы не хотите, чтобы вызывающая сторона его предоставляла. Возможно, нужен только временный массив для промежуточного вычисления. В любом случае есть простые способы получения объекта ndarray нужного типа данных. Наиболее универсальная функция для этого — PyArray_NewFromDescr. Все функции создания массивов используют этот многократно используемый код. Из-за своей гибкости его использование может быть немного сложным. В результате существуют более простые формы, которые легче использовать. Эти формы являются частью семейства функций PyArray_SimpleNew, которые упрощают интерфейс, предоставляя значения по умолчанию для распространенных случаев использования.

Доступ к памяти ndarray и чтение элементов ndarray

Если obj является ndarray (PyArrayObject*), то область данных ndarray указана указателем void* PyArray_DATA (obj) или указателем char* PyArray_BYTES (obj). Помните, что (вообще говоря) эта область данных может не быть выровнена в соответствии с типом данных, она может представлять данные с переставленными байтами и/или она может быть не доступной для записи. Если область данных выровнена и имеет родной порядок байтов, то способ получения конкретного элемента массива определяется только массивом переменных npy_intp PyArray_STRIDES (obj). В частности, этот массив целых чисел показывает, сколько байтов необходимо добавить к текущему указателю элемента, чтобы получить следующий элемент в каждом измерении. Для массивов меньше 4 измерений существуют макросы PyArray_GETPTR{k} (obj, …), где {k} — целые числа 1, 2, 3 или 4, которые облегчают использование шагов массива. Аргументы … представляют {k} неотрицательных целочисленных индексов в массиве. Например, предположим, что E — это 3-мерный массив ndarray. Указатель (void*) на элемент E[i,j,k] получается как PyArray_GETPTR3 (E, i, j, k).

Как объяснялось ранее, массивы с непрерывной структурой по стилю C и непрерывной структурой по стилю Fortran имеют особые шаблоны шагов. Два флага массива (NPY_ARRAY_C_CONTIGUOUS и NPY_ARRAY_F_CONTIGUOUS) указывают, соответствует ли шаблон шагов данного массива непрерывной структуре по стилю C или Fortran, или ни одному из них. Соответствие шаблона шагов стандартному шаблону C или Fortran можно проверить с помощью PyArray_IS_C_CONTIGUOUS (obj) и PyArray_ISFORTRAN (obj) соответственно. Большинство сторонних библиотек ожидают непрерывные массивы. Но часто несложно поддерживать общие шаги. Я рекомендую использовать информацию о шагах в вашем собственном коде по возможности и оставлять требования к единственному сегменту для обертывания стороннего кода. Использование информации о шагах, предоставляемой с ndarray, а не требование непрерывного шага уменьшает копирование, которое в противном случае необходимо было бы выполнить.