Интерфейс массивов (Array API)

Структура массива и доступ к данным

Эти макросы обращаются к членам структуры PyArrayObject и определены в ndarraytypes.h. Аргумент arr может быть любым PyObject*, непосредственно интерпретируемым как PyArrayObject* (любой экземпляр PyArray_Type и его подтипов).

intPyArray_NDIM(PyArrayObject*arr)

Количество измерений в массиве.

intPyArray_FLAGS(PyArrayObject*arr)

Возвращает целое число, представляющее флаги массива.

intPyArray_TYPE(PyArrayObject*arr)

Возвращает (встроенный) тип элементов этого массива.

intPyArray_SETITEM(PyArrayObject*arr, void*itemptr, PyObject*obj)

Преобразует obj и помещает его в массив arr по адресу itemptr. Возвращает -1 при ошибке или 0 при успехе.

voidPyArray_ENABLEFLAGS(PyArrayObject*arr, intflags)

Добавлена в версии 1.7.

Включает указанные флаги массива. Данная функция не выполняет валидацию и предполагает, что вы знаете, что делаете.

voidPyArray_CLEARFLAGS(PyArrayObject*arr, intflags)

Добавлена в версии 1.7.

Очищает указанные флаги массива. Данная функция не выполняет валидацию и предполагает, что вы знаете, что делаете.

void*PyArray_DATA(PyArrayObject*arr)

char*PyArray_BYTES(PyArrayObject*arr)

Эти два макроса подобны и возвращают указатель на буфер данных массива. Первый макрос можно (и следует) использовать для присваивания указателя, а второй — для общих операций. Если вы не гарантируете непрерывность и/или выравнивание массива, убедитесь, что понимаете, как обращаться к данным в массиве, чтобы избежать проблем с памятью и/или выравниванием.

npy_intp*PyArray_DIMS(PyArrayObject*arr)

Возвращает указатель на размерности/форму массива. Количество элементов совпадает с количеством измерений массива. Может вернуть NULL для 0-мерных массивов.

npy_intp*PyArray_SHAPE(PyArrayObject*arr)

Добавлена в версии 1.7.

Синоним для PyArray_DIMS, используемый для согласованности с использованием shape в Python.

npy_intp*PyArray_STRIDES(PyArrayObject*arr)

Возвращает указатель на шаги массива. Количество элементов совпадает с количеством измерений массива.

npy_intpPyArray_DIM(PyArrayObject*arr, intn)

Возвращает размерность в n-м измерении.

npy_intpPyArray_STRIDE(PyArrayObject*arr, intn)

Возвращает шаг в n-м измерении.

npy_intpPyArray_ITEMSIZE(PyArrayObject*arr)

Возвращает размер элемента для элементов этого массива.

Обратите внимание, что в старом API, устаревшем с версии 1.7, тип возвращаемого значения этой функции был int.

npy_intpPyArray_SIZE(PyArrayObject*arr)

Возвращает общий размер (количество элементов) массива.

npy_intpPyArray_Size(PyArrayObject*obj)

Возвращает 0, если obj не является подклассом ndarray. В противном случае возвращает общее количество элементов в массиве. Более безопасная версия PyArray_SIZE (obj).

npy_intpPyArray_NBYTES(PyArrayObject*arr)

Возвращает общее количество байт, занимаемых массивом.

PyObject*PyArray_BASE(PyArrayObject*arr)

Возвращает базовый объект массива. В большинстве случаев это объект, владеющий памятью, на которую указывает массив.

Если вы создаёте массив с помощью API C и указываете собственную память, используйте функцию PyArray_SetBaseObject для задания базового объекта, владеющего этой памятью.

Если установлены (устаревшие) флаги NPY_ARRAY_UPDATEIFCOPY или NPY_ARRAY_WRITEBACKIFCOPY, это имеет другое значение: base — массив, в который будет скопирован текущий массив при разрешении копии. Это перегрузка свойства base для двух функций, вероятно, изменится в будущей версии NumPy.

PyArray_Descr*PyArray_DESCR(PyArrayObject*arr)

Возвращает ссылку на свойство dtype массива (не изменяющую его).

PyArray_Descr*PyArray_DTYPE(PyArrayObject*arr)

Добавлена в версии 1.7.

Синоним для PyArray_DESCR, названный для согласованности с использованием ‘dtype’ в Python.

PyObject*PyArray_GETITEM(PyArrayObject*arr, void*itemptr)

Получает объект Python встроенного типа из ndarray, arr, по указанному адресу itemptr. В случае неудачи возвращает NULL.

numpy.ndarray.item идентично PyArray_GETITEM.

Доступ к данным

Эти функции и макросы обеспечивают лёгкий доступ к элементам ndarray из C. Они работают для всех массивов. Однако при доступе к данным в массиве необходимо учитывать, если они не в порядке байтовой последовательности машины, не выровнены или не доступны для записи. То есть обязательно учитывайте состояние флагов, если не знаете, что делаете, или заранее не гарантировали, что массив доступен для записи, выровнен и в порядке байтовой последовательности машины, используя PyArray_FromAny. Если вы хотите обрабатывать все типы массивов, функция copyswap для каждого типа полезна для обработки некорректных массивов. Некоторые платформы (например, Solaris) не любят невыровненные данные и аварийно завершат работу, если вы обратитесь к невыровненному указателю. Другие платформы (например, x86 Linux) просто будут работать медленнее с невыровненными данными.

void*PyArray_GetPtr(PyArrayObject*aobj, npy_intp*ind)

Возвращает указатель на данные ndarray, aobj, по N-мерному индексу, заданному массивом ind (размер которого должен быть не меньше aobj ->nd). Возможно, вам потребуется привести возвращённый указатель к типу данных ndarray.

void*PyArray_GETPTR1(PyArrayObject*obj, npy_intpi)

void*PyArray_GETPTR2(PyArrayObject*obj, npy_intpi, npy_intpj)

void*PyArray_GETPTR3(PyArrayObject*obj, npy_intpi, npy_intpj, npy_intpk)

void*PyArray_GETPTR4(PyArrayObject*obj, npy_intpi, npy_intpj, npy_intpk, npy_intpl)

Быстрый, встроенный доступ к элементу по заданным координатам в ndarray, obj, который должен иметь соответственно 1, 2, 3 или 4 измерения (это не проверяется). Соответствующие координаты i, j, k и l могут быть любыми целыми числами, но будут интерпретированы как npy_intp. Возможно, вам потребуется привести возвращённый указатель к типу данных ndarray.

Создание массивов

Из исходных данных

PyObject*PyArray_NewFromDescr(PyTypeObject*subtype, PyArray_Descr*descr, intnd, npy_intpconst*dims, npy_intpconst*strides, void*data, intflags, PyObject*obj)

Эта функция захватывает ссылку на descr. Самый простой способ получить её — использовать PyArray_DescrFromType.

Это основная функция создания массивов. Большинство новых массивов создаются с помощью этой гибкой функции.

Возвращаемый объект — это объект Python-типа subtype, который должен быть подтипом PyArray_Type. Массив имеет nd измерений, описанных в dims. Описание типа данных нового массива — descr.

Если subtype относится к подклассу массива, а не к базовому типу &PyArray_Type, то obj — это объект, передаваемый методу __array_finalize__ подкласса.

Если data — NULL, то будет выделена новая неинициализированная память, и flags может быть ненулевым, чтобы указать на фортрановский непрерывный массив. Используйте PyArray_FILLWBYTE для инициализации памяти.

Если data не NULL, предполагается, что он указывает на память, которая будет использоваться для массива, и аргумент flags используется в качестве новых флагов для массива (за исключением состояния флага NPY_ARRAY_OWNDATA, NPY_ARRAY_WRITEBACKIFCOPY и NPY_ARRAY_UPDATEIFCOPY нового массива будут сброшены).

Кроме того, если data ненулевой, то можно также указать strides. Если strides — NULL, размер шагов массива вычисляются как непрерывный в стиле C (по умолчанию) или непрерывный в стиле Fortran (flags ненулевой для data = NULL или flags & NPY_ARRAY_F_CONTIGUOUS ненулевой ненулевого data). Любые заданные dims и strides копируются в новые массивы размеров и шагов для нового объекта массива.

PyArray_CheckStrides может помочь проверить информацию о шагах, отличных от NULL.

Если data предоставлен, он должен оставаться активным в течение всего жизненного цикла массива. Один из способов управления этим — через PyArray_SetBaseObject

PyObject*PyArray_NewLikeArray(PyArrayObject*prototype, NPY_ORDERorder, PyArray_Descr*descr, intsubok)

Новое в версии 1.6.

Эта функция захватывает ссылку на descr, если он не равен NULL. Эта функция создания массивов позволяет удобно создавать новый массив, соответствующий формату и расположению памяти существующего массива, возможно изменяя расположение и/или тип данных.

Когда order равен NPY_ANYORDER, порядок результата — NPY_FORTRANORDER, если prototype — фортрановский массив, NPY_CORDER в противном случае. Когда order равен NPY_KEEPORDER, порядок результата соответствует порядку prototype, даже если оси prototype не упорядочены в C или Fortran.

Если descr равен NULL, используется тип данных prototype.

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

PyObject*PyArray_New(PyTypeObject*subtype, intnd, npy_intpconst*dims, inttype_num, npy_intpconst*strides, void*data, intitemsize, intflags, PyObject*obj)

Аналогично PyArray_NewFromDescr (…) за исключением того, что вы указываете описание типа данных с помощью type_num и itemsize, где type_num соответствует встроенному (или пользовательскому) типу. Если тип всегда имеет одинаковое количество байтов, то itemsize игнорируется. В противном случае itemsize указывает конкретный размер этого массива.

PyObject*PyArray_SimpleNew(intnd, npy_intpconst*dims, inttypenum)

Создает новый неинициализированный массив типа typenum, размер которого в каждом из nd измерений задается целочисленным массивом dims. Память для массива не инициализирована (за исключением случая, когда typenum равен NPY_OBJECT, в этом случае каждый элемент массива устанавливается в NULL). Аргумент typenum позволяет указать любой встроенный тип данных, например, NPY_FLOAT или NPY_LONG. Память для массива можно обнулить, если это необходимо, с помощью PyArray_FILLWBYTE (return_object, 0). Эта функция не может быть использована для создания массива с гибким типом (размер элемента не указан).

PyObject*PyArray_SimpleNewFromData(intnd, npy_intpconst*dims, inttypenum, void*data)

Создать обёртку массива вокруг data, на который указывает заданный указатель. Флаги массива будут иметь значение по умолчанию, что область данных корректна и непрерывна в стиле C. Форма массива задаётся массивом dims длиной nd. Тип данных массива указывается параметром typenum. Если данные поступают из другого объекта Python с учётом ссылок, счётчик ссылок на этот объект должен быть увеличен после передачи указателя, а член base возвращаемого ndarray должен указывать на объект Python, владеющий данными. Это гарантирует, что предоставленная память не будет освобождена, пока возвращаемый массив существует. Для освобождения памяти как только ndarray будет удалён, установите флаг OWNDATA на возвращаемом ndarray.

PyObject*PyArray_SimpleNewFromDescr(intnd, npy_intconst*dims, PyArray_Descr*descr)

Эта функция заимствует ссылку на descr.

Создать новый массив с предоставленным описанием типа данных descr, формой, определённой nd и dims.

voidPyArray_FILLWBYTE(PyObject*obj, intval)

Заполнить массив, на который указывает obj —который должен быть (подклассом) ndarray—содержимым val (оценивается как байт). Эта макрокоманда вызывает memset, поэтому obj должен быть непрерывным.

PyObject*PyArray_Zeros(intnd, npy_intpconst*dims, PyArray_Descr*dtype, intfortran)

Создать новый nd-мерный массив с формой, заданной dims, и типом данных, заданным dtype. Если fortran имеет ненулевое значение, создаётся массив в порядке Fortran, в противном случае — в порядке C. Заполнить память нулями (или объектом 0, если dtype соответствует NPY_OBJECT).

PyObject*PyArray_ZEROS(intnd, npy_intpconst*dims, inttype_num, intfortran)

Макроформа PyArray_Zeros, принимающая номер типа вместо объекта типа данных.

PyObject*PyArray_Empty(intnd, npy_intpconst*dims, PyArray_Descr*dtype, intfortran)

Создать новый nd-мерный массив с формой, заданной dims, и типом данных, заданным dtype. Если fortran имеет ненулевое значение, создаётся массив в порядке Fortran, в противном случае — в порядке C. Массив не инициализируется, если тип данных не соответствует NPY_OBJECT, в этом случае массив заполняется Py_None.

PyObject*PyArray_EMPTY(intnd, npy_intpconst*dims, inttypenum, intfortran)

Макроформа PyArray_Empty, принимающая номер типа, typenum, вместо объекта типа данных.

PyObject*PyArray_Arange(doublestart, doublestop, doublestep, inttypenum)

Создать новый одномерный массив типа данных typenum, который изменяется от start до stop (исключая) с шагом step. Эквивалентно arange (start, stop, step, dtype).

PyObject*PyArray_ArangeObj(PyObject*start, PyObject*stop, PyObject*step, PyArray_Descr*descr)

Создать новый одномерный массив типа данных, определяемого descr, который изменяется от start до stop (исключая) с шагом step. Эквивалентно arange( start, stop, step, typenum ).

intPyArray_SetBaseObject(PyArrayObject*arr, PyObject*obj)

New in version 1.7.

Эта функция берет в собственность ссылку на obj и устанавливает её в качестве базового свойства arr.

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

Значение возврата 0 при успехе, -1 при ошибке.

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

Из других объектов

PyObject*PyArray_FromAny(PyObject*op, PyArray_Descr*dtype, intmin_depth, intmax_depth, intrequirements, PyObject*context)

Это основная функция, используемая для получения массива из любого вложенного последовательности или объекта, предоставляющего интерфейс массива, op. Параметры позволяют указать требуемый dtype, минимальное (min_depth) и максимальное (max_depth) количество допустимых измерений, а также другие требования к массиву. Эта функция заимствует ссылку на аргумент dtype, который должен быть структурой PyArray_Descr, указывающей желаемый тип данных (включая необходимый порядок байтов). Аргумент dtype может быть NULL, указывая, что любой тип данных (и порядок байтов) приемлем. Если флаг NPY_ARRAY_FORCECAST отсутствует в flags, этот вызов сгенерирует ошибку, если тип данных не может быть безопасно получен из объекта. Если вы хотите использовать NULL для dtype и убедиться, что массив не переставлен, используйте PyArray_CheckFromAny. Значение 0 для любого из параметров глубины приводит к игнорированию параметра. Любой из следующих флагов массива может быть добавлен (например, с использованием |) для получения аргумента требования. Если ваш код может обрабатывать общие (например, с шагами, с переставленными байтами или невыровненные массивы), то требования могут быть 0. Также, если op не является массивом (или не предоставляет интерфейс массива), будет создан новый массив (и заполнен из op с использованием протокола последовательности). Новый массив будет иметь NPY_ARRAY_DEFAULT в качестве своего члена флагов. Аргумент context не используется.

NPY_ARRAY_C_CONTIGUOUS

Убедитесь, что возвращаемый массив является непрерывным в стиле C.

NPY_ARRAY_F_CONTIGUOUS

Убедитесь, что возвращаемый массив является непрерывным в стиле Fortran.

NPY_ARRAY_ALIGNED

Убедитесь, что возвращаемый массив выровнен на соответствующих границах для своего типа данных. Выровненный массив имеет указатель данных и каждый множитель шага кратным множителю выравнивания для описателя типа данных.

NPY_ARRAY_WRITEABLE

Убедитесь, что возвращаемый массив может быть записан.

NPY_ARRAY_ENSURECOPY

Убедитесь, что создана копия объекта op. Если этот флаг отсутствует, данные не копируются, если этого можно избежать.

NPY_ARRAY_ENSUREARRAY

Убедитесь, что результат является массивом базового класса ndarray. По умолчанию, если op является экземпляром подкласса ndarray, возвращается экземпляр того же самого подкласса. Если этот флаг установлен, вместо этого будет возвращен объект ndarray.

NPY_ARRAY_FORCECAST

Принудительно выполнить приведение к выходному типу, даже если это нельзя сделать безопасно. Без этого флага приведение данных будет происходить только в том случае, если это можно сделать безопасно, в противном случае генерируется ошибка.

NPY_ARRAY_WRITEBACKIFCOPY

Если op уже является массивом, но не удовлетворяет требованиям, то создается копия (которая удовлетворит требованиям). Если этот флаг присутствует и должна быть создана копия (объекта, который уже является массивом), то соответствующий флаг NPY_ARRAY_WRITEBACKIFCOPY устанавливается в возвращаемой копии, и op делается только для чтения. Необходимо убедиться, что вызов PyArray_ResolveWritebackIfCopy для копирования содержимого обратно в op, и массив op будет снова делаться доступным для записи. Если op изначально недоступен для записи, или если это не массив, то генерируется ошибка.

NPY_ARRAY_UPDATEIFCOPY

Устаревший. Используйте NPY_ARRAY_WRITEBACKIFCOPY, который аналогичен. Этот флаг «автоматически» копирует данные обратно при освобождении возвращаемого массива, что не поддерживается во всех реализациях Python.

NPY_ARRAY_BEHAVED

NPY_ARRAY_ALIGNED | NPY_ARRAY_WRITEABLE

NPY_ARRAY_CARRAY

NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_BEHAVED

NPY_ARRAY_CARRAY_RO

NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_ALIGNED

NPY_ARRAY_FARRAY

NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_BEHAVED

NPY_ARRAY_FARRAY_RO

NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_ALIGNED

NPY_ARRAY_DEFAULT

NPY_ARRAY_CARRAY

NPY_ARRAY_IN_ARRAY

NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_ALIGNED

NPY_ARRAY_IN_FARRAY

NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_ALIGNED

NPY_OUT_ARRAY

NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_WRITEABLE | NPY_ARRAY_ALIGNED

NPY_ARRAY_OUT_ARRAY

NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_ALIGNED | NPY_ARRAY_WRITEABLE

NPY_ARRAY_OUT_FARRAY

NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_WRITEABLE | NPY_ARRAY_ALIGNED

NPY_ARRAY_INOUT_ARRAY

NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_WRITEABLE | NPY_ARRAY_ALIGNED | NPY_ARRAY_WRITEBACKIFCOPY | NPY_ARRAY_UPDATEIFCOPY

NPY_ARRAY_INOUT_FARRAY

NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_WRITEABLE | NPY_ARRAY_ALIGNED | NPY_ARRAY_WRITEBACKIFCOPY | NPY_ARRAY_UPDATEIFCOPY

intPyArray_GetArrayParamsFromObject(PyObject*op, PyArray_Descr*requested_dtype, npy_boolwriteable, PyArray_Descr**out_dtype, int*out_ndim, npy_intp*out_dims, PyArrayObject**out_arr, PyObject*context)

Устарело начиная с версии NumPy: 1.19

Если NumPy не обнаружит проблем, эта функция будет быстро удалена без замены.

Изменено в версии NumPy: 1.19

context никогда не используется. Его использование приводит к ошибке.

Добавлена в версии 1.6.

PyObject*PyArray_CheckFromAny(PyObject*op, PyArray_Descr*dtype, intmin_depth, intmax_depth, intrequirements, PyObject*context)

Практически идентично PyArray_FromAny (…) за исключением того, что requirements может содержать NPY_ARRAY_NOTSWAPPED (переопределяя спецификацию в dtype) и NPY_ARRAY_ELEMENTSTRIDES, которое указывает, что массив должен быть выровнен в том смысле, что шаги являются кратными размеру элемента.

В версиях NumPy 1.6 и ранее указанные флаги не имели префикса _ARRAY_. Эта форма имён констант устарела в 1.7.

NPY_ARRAY_NOTSWAPPED

Убедитесь, что возвращаемый массив имеет описатель типа данных в порядке байтов машины, переопределяя любую спецификацию в аргументе dtype. Обычно требование к порядку байтов определяется аргументом dtype. Если этот флаг установлен, а аргумент dtype не указывает на описатель порядка байтов машины (или равен NULL, и объект уже является массивом с описателем типа данных, который не находится в порядке байтов машины), тогда создается новый описатель типа данных и используется с полем порядка байтов, установленным на родной.

NPY_ARRAY_BEHAVED_NS

NPY_ARRAY_ALIGNED | NPY_ARRAY_WRITEABLE | NPY_ARRAY_NOTSWAPPED

NPY_ARRAY_ELEMENTSTRIDES

Убедитесь, что шаги возвращаемого массива являются кратными размеру элемента.

PyObject*PyArray_FromArray(PyArrayObject*op, PyArray_Descr*newtype, intrequirements)

Специальный случай PyArray_FromAny, когда op уже является массивом, но ему нужно быть определенного типа newtype (включая порядок байтов) или имеет определенные requirements.

PyObject*PyArray_FromStructInterface(PyObject*op)

Возвращает объект ndarray из Python-объекта, который экспонирует атрибут __array_struct__ и следует протоколу интерфейса массива. Если объект не содержит этого атрибута, то возвращается заимствованная ссылка на Py_NotImplemented.

PyObject*PyArray_FromInterface(PyObject*op)

Возвращает объект ndarray из Python-объекта, который экспонирует атрибут __array_interface__, следуя протоколу интерфейса массива. Если объект не содержит этого атрибута, то возвращается заимствованная ссылка на Py_NotImplemented.

PyObject*PyArray_FromArrayAttr(PyObject*op, PyArray_Descr*dtype, PyObject*context)

Возвращает объект ndarray из объекта Python, который предоставляет метод __array__. Метод __array__ может принимать 0 или 1 аргумент ([dtype]). context не используется.

PyObject*PyArray_ContiguousFromAny(PyObject*op, inttypenum, intmin_depth, intmax_depth)

Эта функция возвращает (стиль C) непрерывный и корректный массив функций из любого вложенного последовательности или объекта интерфейса массива, экспортирующего объект op, типа, заданного перечисленным typenum, минимальной глубиной min_depth и максимальной глубиной max_depth. Эквивалентно вызову PyArray_FromAny с требованиями, установленными в NPY_ARRAY_DEFAULT, и значением member type_num аргумента типа, установленным в typenum.

PyObject*PyArray_ContiguousFromObject(PyObject*op, inttypenum, intmin_depth, intmax_depth)

Эта функция возвращает хорошо работающий массив C-стиля из любого вложенного последовательности или объекта, экспортирующего интерфейс массива. Минимальное количество измерений, которые может иметь массив, задаётся значением min_depth, а максимальное – max_depth. Это эквивалентно вызову PyArray_FromAny с требованиями NPY_ARRAY_DEFAULT и NPY_ARRAY_ENSUREARRAY.

PyObject*PyArray_FromObject(PyObject*op, inttypenum, intmin_depth, intmax_depth)

Возвращает выровненный массив в порядке байтов по умолчанию из любой вложенной последовательности или объекта, экспортирующего интерфейс массива, op, типа, заданного перечисленным typenum. Минимальное количество измерений массива задаётся min_depth, а максимальное – max_depth. Это эквивалентно вызову PyArray_FromAny с требованиями, установленными в BEHAVED.

PyObject*PyArray_EnsureArray(PyObject*op)

Эта функция заимствует ссылку на op и гарантирует, что op является базовым ndarray. Она обрабатывает массивы скаляров, но в противном случае вызывает PyArray_FromAny ( op, NULL, 0, 0, NPY_ARRAY_ENSUREARRAY, NULL).

PyObject*PyArray_FromString(char*string, npy_intpslen, PyArray_Descr*dtype, npy_intpnum, char*sep)

Создаёт одномерный ndarray одного типа из двоичных или (ASCII) текстовых string длиной slen. Тип данных создаваемого массива задаётся dtype. Если num равно -1, то копируется вся строка и возвращается массив соответствующего размера, в противном случае num является количеством элементов для копирования из строки. Если sep равно NULL (или “”), то строка интерпретируется как двоичные данные, в противном случае подстроки, разделенные sep, преобразуются в элементы типа данных dtype. Некоторые типы данных могут быть нечитаемы в текстовом режиме, и в этом случае будет возбуждено исключение. Все ошибки возвращают NULL.

PyObject*PyArray_FromFile(FILE*fp, PyArray_Descr*dtype, npy_intpnum, char*sep)

Создаёт одномерный ndarray одного типа из двоичного или текстового файла. Указатель на открытый файл – fp, тип данных создаваемого массива – dtype. Он должен соответствовать данным в файле. Если num равно -1, то чтение продолжается до конца файла и возвращается массив соответствующего размера, в противном случае num – количество элементов для чтения. Если sep равно NULL (или “”), то чтение из файла происходит в двоичном режиме, в противном случае чтение из файла происходит в текстовом режиме с sep, задающим разделитель элементов. Некоторые типы массивов не могут быть прочитаны в текстовом режиме, и в этом случае возбуждается исключение.

PyObject*PyArray_FromBuffer(PyObject*buf, PyArray_Descr*dtype, npy_intpcount, npy_intpoffset)

Создаёт одномерный массив ndarray одного типа из объекта, buf, который экспортирует протокол буфера (или имеет атрибут __buffer__, возвращающий объект, экспортирующий протокол буфера). Сначала будет использоваться доступ к изменяемому буферу, а затем — к только для чтения. Флаг NPY_ARRAY_WRITEABLE возвращаемого массива укажет, какой из вариантов был успешным. Данные предполагаются начиная с offset байтов от начала области памяти объекта. Тип данных в буфере будет интерпретироваться в зависимости от описателя типа данных, dtype. Если count отрицательно, он будет определён по размеру буфера и запрошенному размеру элемента, в противном случае count представляет, сколько элементов должно быть преобразовано из буфера.

intPyArray_CopyInto(PyArrayObject*dest, PyArrayObject*src)

Копирует данные из исходного массива, src, в целевой массив, dest, выполняя преобразование типа данных при необходимости. В случае ошибки возвращает -1 (в противном случае 0). Форма src должна быть совместима с формой dest. Области данных dest и src не должны перекрываться.

intPyArray_MoveInto(PyArrayObject*dest, PyArrayObject*src)

Перемещает данные из исходного массива, src, в целевой массив, dest, выполняя преобразование типа данных при необходимости. В случае ошибки возвращает -1 (в противном случае 0). Форма src должна быть совместима с формой dest. Области данных dest и src могут перекрываться.

PyArrayObject*PyArray_GETCONTIGUOUS(PyObject*op)

Если op уже (в стиле C) непрерывный и корректный, то возвращает ссылку, иначе — копию массива (непрерывную и корректную). Параметр op должен быть (подклассом) ndarray, и проверка на это не выполняется.

PyObject*PyArray_FROM_O(PyObject*obj)

Преобразует obj в массив ndarray. Аргумент может быть любым вложенным списком или объектом, экспортирующим интерфейс массива. Это макроформа PyArray_FromAny с использованием NULL, 0, 0, 0 для других аргументов. Ваш код должен быть способен обрабатывать любой описатель типа данных и любую комбинацию флагов данных для использования этого макроса.

PyObject*PyArray_FROM_OF(PyObject*obj, intrequirements)

Аналогично PyArray_FROM_O, но может принимать аргумент requirements, указывающий свойства, которые должен иметь результирующий массив. Доступные требования, которые можно применить: NPY_ARRAY_C_CONTIGUOUS, NPY_ARRAY_F_CONTIGUOUS, NPY_ARRAY_ALIGNED, NPY_ARRAY_WRITEABLE, NPY_ARRAY_NOTSWAPPED, NPY_ARRAY_ENSURECOPY, NPY_ARRAY_WRITEBACKIFCOPY, NPY_ARRAY_UPDATEIFCOPY, NPY_ARRAY_FORCECAST и NPY_ARRAY_ENSUREARRAY. Также могут использоваться стандартные комбинации флагов:

PyObject*PyArray_FROM_OT(PyObject*obj, inttypenum)

Аналогично PyArray_FROM_O, но может принимать аргумент typenum, указывающий номер типа возвращаемого массива.

PyObject*PyArray_FROM_OTF(PyObject*obj, inttypenum, intrequirements)

Комбинация PyArray_FROM_OF и PyArray_FROM_OT, позволяющая предоставить и аргумент typenum, и аргумент flags.

PyObject*PyArray_FROMANY(PyObject*obj, inttypenum, intmin, intmax, intrequirements)

Аналогично PyArray_FromAny, за исключением того, что тип данных задается с помощью номера типа. PyArray_DescrFromType (typenum) передается непосредственно в PyArray_FromAny. Эта макрокоманда также добавляет NPY_ARRAY_DEFAULT к требованиям, если NPY_ARRAY_ENSURECOPY передается в качестве требований.

PyObject*PyArray_CheckAxis(PyObject*obj, int*axis, intrequirements)

Капсулирует функциональность функций и методов, которые принимают ключевое слово axis= и работают должным образом с None в качестве аргумента axis. Входной массив — obj, в то время как *axis — преобразованное целое число (так что >=MAXDIMS — это значение None), а requirements предоставляет необходимые свойства obj. Результатом является преобразованная версия входных данных, удовлетворяющая требованиям, и, при необходимости, произошла операция сглаживания. В выходных данных отрицательные значения *axis преобразуются, а новое значение проверяется на согласованность с формой obj.

Обработка типов

Общий контроль типа Python

intPyArray_Check(PyObject*op)

Возвращает истинное значение, если op — это объект Python, тип которого является подтипом PyArray_Type.

intPyArray_CheckExact(PyObject*op)

Возвращает истинное значение, если op — это объект Python с типом PyArray_Type.

intPyArray_HasArrayInterface(PyObject*op, PyObject*out)

Если op реализует любую часть интерфейса массива, то out будет содержать новую ссылку на только что созданный массив ndarray, использующий интерфейс, или out будет содержать NULL в случае ошибки при преобразовании. В противном случае out будет содержать заимствованную ссылку на Py_NotImplemented, и условие ошибки не будет установлено.

intPyArray_HasArrayInterfaceType(PyObject*op, PyArray_Descr*dtype, PyObject*context, PyObject*out)

Если op реализует любую часть интерфейса массива, то out будет содержать новую ссылку на только что созданный массив ndarray, использующий интерфейс, или out будет содержать NULL в случае ошибки при преобразовании. В противном случае out будет содержать заимствованную ссылку на Py_NotImplemented, и условие ошибки не будет установлено. Эта версия позволяет установить тип данных в части интерфейса массива, которая ищет атрибут __array__. context не используется.

intPyArray_IsZeroDim(PyObject*op)

Возвращает истинное значение, если op является экземпляром (или подклассом) PyArray_Type и имеет 0 размерностей.

PyArray_IsScalar(op, cls)

Возвращает истинное значение, если op является экземпляром Py{cls}ArrType_Type.

intPyArray_CheckScalar(PyObject*op)

Возвращает истинное значение, если op является скаляром массива (экземпляром подтипа PyGenericArr_Type) или экземпляром (или подклассом) PyArray_Type с размерностью 0.

intPyArray_IsPythonNumber(PyObject*op)

Возвращает истинное значение, если op является экземпляром встроенного числового типа (int, float, complex, long, bool).

intPyArray_IsPythonScalar(PyObject*op)

Возвращает истинное значение, если op является встроенным скалярным объектом Python (int, float, complex, bytes, str, long, bool).

intPyArray_IsAnyScalar(PyObject*op)

Возвращает истинное значение, если op — это либо скалярный объект Python (см. PyArray_IsPythonScalar), либо скаляр массива (экземпляр подтипа PyGenericArr_Type).

intPyArray_CheckAnyScalar(PyObject*op)

Возвращает истинное значение, если op является объектом Python скалярного типа (см. PyArray_IsPythonScalar), массивом скаляра (экземпляр подтипа PyGenericArr_Type) или экземпляром подтипа PyArray_Type с размерностью 0.

Проверка типа данных

Для макросов typenum аргумент — целое число, представляющее перечисление типа данных массива. Для макросов проверки типа массива аргумент должен быть PyObject*, который может быть непосредственно интерпретирован как PyArrayObject*.

intPyTypeNum_ISUNSIGNED(intnum)

intPyDataType_ISUNSIGNED(PyArray_Descr*descr)

intPyArray_ISUNSIGNED(PyArrayObject*obj)

Тип представляет беззнаковое целое число.

intPyTypeNum_ISSIGNED(intnum)

intPyDataType_ISSIGNED(PyArray_Descr*descr)

intPyArray_ISSIGNED(PyArrayObject*obj)

Тип представляет знаковое целое число.

intPyTypeNum_ISINTEGER(intnum)

intPyDataType_ISINTEGER(PyArray_Descr*descr)

intPyArray_ISINTEGER(PyArrayObject*obj)

Тип представляет любое целое число.

intPyTypeNum_ISFLOAT(intnum)

intPyDataType_ISFLOAT(PyArray_Descr*descr)

intPyArray_ISFLOAT(PyArrayObject*obj)

Тип представляет любое число с плавающей точкой.

intPyTypeNum_ISCOMPLEX(intnum)

intPyDataType_ISCOMPLEX(PyArray_Descr*descr)

intPyArray_ISCOMPLEX(PyArrayObject*obj)

Тип представляет любое комплексное число с плавающей точкой.

intPyTypeNum_ISNUMBER(intnum)

intPyDataType_ISNUMBER(PyArray_Descr*descr)

intPyArray_ISNUMBER(PyArrayObject*obj)

Тип представляет любое целое число, число с плавающей точкой или комплексное число с плавающей точкой.

intPyTypeNum_ISSTRING(intnum)

intPyDataType_ISSTRING(PyArray_Descr*descr)

intPyArray_ISSTRING(PyArrayObject*obj)

Тип представляет строковый тип данных.

intPyTypeNum_ISPYTHON(intnum)

intPyDataType_ISPYTHON(PyArray_Descr*descr)

intPyArray_ISPYTHON(PyArrayObject*obj)

Тип представляет перечисление, соответствующее одному из стандартных скалярных типов Python (bool, int, float или complex).

intPyTypeNum_ISFLEXIBLE(intnum)

intPyDataType_ISFLEXIBLE(PyArray_Descr*descr)

intPyArray_ISFLEXIBLE(PyArrayObject*obj)

Тип представляет один из гибких типов массивов ( NPY_STRING, NPY_UNICODE или NPY_VOID ).

intPyDataType_ISUNSIZED(PyArray_Descr*descr)

Тип не имеет информации о размере и может быть изменён. Должен вызываться только для гибких типов данных. Типы, привязанные к массиву, всегда будут иметь размер, поэтому макрос в форме массива не существует.

Изменено в версии 1.18.

Для структурированных типов данных без полей эта функция теперь возвращает False.

intPyTypeNum_ISUSERDEF(intnum)

intPyDataType_ISUSERDEF(PyArray_Descr*descr)

intPyArray_ISUSERDEF(PyArrayObject*obj)

Тип представляет пользовательский тип.

intPyTypeNum_ISEXTENDED(intnum)

intPyDataType_ISEXTENDED(PyArray_Descr*descr)

intPyArray_ISEXTENDED(PyArrayObject*obj)

Тип является либо гибким, либо пользовательским.

intPyTypeNum_ISOBJECT(intnum)

intPyDataType_ISOBJECT(PyArray_Descr*descr)

intPyArray_ISOBJECT(PyArrayObject*obj)

Тип представляет тип данных объекта.

intPyTypeNum_ISBOOL(intnum)

intPyDataType_ISBOOL(PyArray_Descr*descr)

intPyArray_ISBOOL(PyArrayObject*obj)

Тип представляет булевый тип данных.

intPyDataType_HASFIELDS(PyArray_Descr*descr)

intPyArray_HASFIELDS(PyArrayObject*obj)

Тип имеет связанные с ним поля.

intPyArray_ISNOTSWAPPED(PyArrayObject*m)

Возвращает истинное значение, если область данных ndarray m находится в машинном порядке байтов в соответствии с описателем типа данных массива.

intPyArray_ISBYTESWAPPED(PyArrayObject*m)

Возвращает истинное значение, если область данных ndarray m не находится в машинном порядке байтов в соответствии с описателем типа данных массива.

npy_boolPyArray_EquivTypes(PyArray_Descr*type1, PyArray_Descr*type2)

Возвращает NPY_TRUE, если type1 и type2 фактически представляют эквивалентные типы для данной платформы (член fortran каждого типа игнорируется). Например, на 32-битных платформах, NPY_LONG и NPY_INT являются эквивалентными. В противном случае возвращает NPY_FALSE.

npy_boolPyArray_EquivArrTypes(PyArrayObject*a1, PyArrayObject*a2)

Возвращает NPY_TRUE, если массивы a1 и a2 имеют эквивалентные типы для данной платформы.

npy_boolPyArray_EquivTypenums(inttypenum1, inttypenum2)

Специальный случай PyArray_EquivTypes (…) , не принимающий гибкие типы данных, но, возможно, более простой в вызове.

intPyArray_EquivByteorders(intb1, intb2)

Истинно, если символы порядка байтов b1 и b2 ( NPY_LITTLE, NPY_BIG, NPY_NATIVE, NPY_IGNORE ) либо равны, либо эквивалентны по своему определению родного порядка байтов. Таким образом, на машине с порядком байтов little-endian NPY_LITTLE и NPY_NATIVE эквивалентны, в то время как на машине с порядком байтов big-endian они не эквивалентны.

Преобразование типов данных

PyObject*PyArray_Cast(PyArrayObject*arr, inttypenum)

В основном для обратной совместимости с Numeric C-API и для простых преобразований к негибким типам. Возвращает новый объект массива с элементами из arr, преобразованными к типу данных typenum, который должен быть одним из перечисленных типов и не быть гибким типом.

PyObject*PyArray_CastToType(PyArrayObject*arr, PyArray_Descr*type, intfortran)

Возвращает новый массив заданного типа type, преобразуя элементы из arr соответствующим образом. Аргумент fortran задаёт порядок элементов в выходном массиве.

intPyArray_CastTo(PyArrayObject*out, PyArrayObject*in)

Начиная с версии 1.6, эта функция просто вызывает PyArray_CopyInto, которая обрабатывает преобразование.

Преобразует элементы массива in в массив out. Выходной массив должен быть доступным для записи, иметь количество элементов, являющееся целым кратным количеству элементов входного массива (в выходной массив могут быть помещены несколько копий), и иметь тип данных, являющийся одним из встроенных типов. Возвращает 0 при успехе и -1 в случае ошибки.

PyArray_VectorUnaryFunc*PyArray_GetCastFunc(PyArray_Descr*from, inttotype)

Возвращает функцию низкоуровневого преобразования для преобразования из данного описателя в число встроенного типа. Если функция преобразования не существует, возвращает NULL и устанавливает ошибку. Использование этой функции вместо прямого доступа к from ->f->cast позволит поддерживать любые пользовательские функции преобразования, добавленные в словарь преобразований описателей.

intPyArray_CanCastSafely(intfromtype, inttotype)

Возвращает ненулевое значение, если массив типа данных fromtype может быть преобразован к массиву типа данных totype без потери информации. Исключение составляет случай, когда 64-битные целые числа разрешается преобразовать в 64-битные числа с плавающей точкой, даже если это может привести к потере точности для больших целых чисел, чтобы избежать распространения использования длинных двойных значений без явных запросов. Гибкие типы массивов не проверяются по их длинам в этой функции.

intPyArray_CanCastTo(PyArray_Descr*fromtype, PyArray_Descr*totype)

PyArray_CanCastTypeTo заменяет эту функцию в NumPy 1.6 и более поздних версиях.

Эквивалентно PyArray_CanCastTypeTo(fromtype, totype, NPY_SAFE_CASTING).

intPyArray_CanCastTypeTo(PyArray_Descr*fromtype, PyArray_Descr*totype, NPY_CASTINGcasting)

Добавлена в версии 1.6.

Возвращает ненулевое значение, если массив типа данных fromtype (который может включать гибкие типы) может быть безопасно преобразован к массиву типа данных totype (который может включать гибкие типы) в соответствии с правилом преобразования casting. Для простых типов с NPY_SAFE_CASTING, это в основном обёртка вокруг PyArray_CanCastSafely, но для гибких типов, таких как строки или юникод, она производит результаты, учитывающие их размеры. Целые и вещественные типы могут быть преобразованы к строковому или юникодовому типу только с помощью NPY_SAFE_CASTING, если строковый или юникодовый тип достаточно велик, чтобы вместить максимальное значение целочисленного/вещественного типа, из которого происходит преобразование.

intPyArray_CanCastArrayTo(PyArrayObject*arr, PyArray_Descr*totype, NPY_CASTINGcasting)

Добавлена в версии 1.6.

Возвращает ненулевое значение, если arr может быть преобразован к totype в соответствии с правилом преобразования, заданным в casting. Если arr является скаляром массива, его значение принимается во внимание, и ненулевое значение возвращается также, когда значение не вызовет переполнения или усечения до целого числа при преобразовании к типу меньшего размера.

Это почти то же самое, что и результат PyArray_CanCastTypeTo(PyArray_MinScalarType(arr), totype, casting), но она также обрабатывает особый случай, возникающий из-за того, что набор значений uint не является подмножеством значений int для типов с одинаковым количеством битов.

PyArray_Descr*PyArray_MinScalarType(PyArrayObject*arr)

Новый в версии 1.6.

Если arr — массив, возвращает его дескриптор типа данных, но если arr — скалярный массив (имеет 0 измерений), находит тип данных наименьшего размера, в который значение можно преобразовать без переполнения или усечения до целого числа.

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

PyArray_Descr*PyArray_PromoteTypes(PyArray_Descr*type1, PyArray_Descr*type2)

Новый в версии 1.6.

Находит тип данных наименьшего размера и вида, в который type1 и type2 можно безопасно преобразовать. Эта функция симметрична и ассоциативна. Результат строкового или unicode типа будет иметь соответствующий размер для хранения максимального значения входных типов, преобразованных в строку или unicode.

PyArray_Descr*PyArray_ResultType(npy_intpnarrs, PyArrayObject**arrs, npy_intpndtypes, PyArray_Descr**dtypes)

Новый в версии 1.6.

Это применяется к повышению типа ко всем входным данным, используя правила NumPy для объединения скаляров и массивов, чтобы определить тип выходных данных набора операндов. Это тот же тип результата, что и у функций ufuncs. Конкретный алгоритм, используемый следующим образом.

Категории определяются путем проверки, являются ли булевые, целочисленные (int/uint) или вещественные (float/complex) максимальным видом всех массивов и скаляров.

Если существуют только скаляры или максимальная категория скаляров выше, чем максимальная категория массивов, типы данных объединяются с PyArray_PromoteTypes для получения возвращаемого значения.

В противном случае PyArray_MinScalarType вызывается для каждого массива, и результирующие типы данных объединяются с PyArray_PromoteTypes для получения возвращаемого значения.

Набор целочисленных значений не является подмножеством набора беззнаковых значений для типов с одинаковым количеством битов, что не отражается в PyArray_MinScalarType, но обрабатывается как специальный случай в PyArray_ResultType.

intPyArray_ObjectType(PyObject*op, intmintype)

Эта функция устарела и заменена на PyArray_MinScalarType и/или PyArray_ResultType.

Эта функция полезна для определения общего типа, в который можно преобразовать два или более массивов. Она работает только для негибких типов массивов, так как информация о размере элемента не передается. Аргумент mintype представляет собой минимальный допустимый тип, а op представляет собой объект, который будет преобразован в массив. Возвращаемое значение — это перечислительный номер типа, представляющий тип данных, которым должен обладать op.

voidPyArray_ArrayType(PyObject*op, PyArray_Descr*mintype, PyArray_Descr*outtype)

Эта функция устарела и заменена на PyArray_ResultType.

Эта функция работает аналогично PyArray_ObjectType (…) за исключением обработки гибких массивов. Аргумент mintype может иметь член itemsize, и у аргумента outtype будет член itemsize, по крайней мере, такой же большой, но возможно и больше, в зависимости от объекта op.

PyArrayObject**PyArray_ConvertToCommonType(PyObject*op, int*n)

Функциональность, которую она предоставляет, в значительной степени устарела и заменена итератором NpyIter, представленным в версии 1.6, с флагом NPY_ITER_COMMON_DTYPE или с одинаковым параметром dtype для всех операндов.

Преобразуйте последовательность объектов Python, содержащихся в op, в массив ndarrays, каждый из которых имеет одинаковый тип данных. Тип выбирается так же, как PyArray_ResultType. Длина последовательности возвращается в n, и возвращаемое значение — массив длиной n указателей на PyArrayObject (или NULL в случае ошибки). Возвращаемый массив должен быть освобожден вызывающим эту функцию (используя PyDataMem_FREE ), а все массивы в нём DECREF , иначе произойдёт утечка памяти. Приведённый ниже пример кода шаблона демонстрирует типичное использование:

Изменено в версии 1.18.0: Смесь скаляров и нульмерных массивов теперь производит тип, способный содержать скалярное значение. Раньше приоритет отдавался типу данных массивов.

mps = PyArray_ConvertToCommonType(obj, &n);
if (mps==NULL) return NULL;
{code}
<before return>
for (i=0; i<n; i++) Py_DECREF(mps[i]);
PyDataMem_FREE(mps);
{return}

char*PyArray_Zero(PyArrayObject*arr)

Указатель на только что созданную память размером arr ->itemsize, содержащую представление 0 для данного типа. Возвращаемый указатель ret необходимо освободить с помощью PyDataMem_FREE (ret), когда он больше не нужен.

char*PyArray_One(PyArrayObject*arr)

Указатель на только что созданную память размером arr ->itemsize, содержащую представление 1 для данного типа. Возвращаемый указатель ret необходимо освободить с помощью PyDataMem_FREE (ret), когда он больше не нужен.

intPyArray_ValidType(inttypenum)

Возвращает NPY_TRUE, если typenum представляет собой допустимый номер типа (встроенный, пользовательский или код символа). В противном случае эта функция возвращает NPY_FALSE.

Новые типы данных

voidPyArray_InitArrFuncs(PyArray_ArrFuncs*f)

Инициализирует все указатели на функции и члены в NULL.

intPyArray_RegisterDataType(PyArray_Descr*dtype)

Регистрирует тип данных как новый пользовательский тип данных для массивов. Тип должен иметь большинство своих элементов заполненными. Это не всегда проверяется, и ошибки могут привести к сегменту. В частности, член typeobj структуры dtype должен быть заполнен типом Python, который имеет фиксированный размер элемента, соответствующий члену elsize в dtype. Также член f должен иметь необходимые функции: nonzero, copyswap, copyswapn, getitem, setitem и cast (некоторые из функций cast могут быть NULL, если поддержка не требуется). Для избежания путаницы вы должны выбрать уникальный символьный тип-код, но это не навязано и не используется внутри.

Возвращается уникальный номер пользовательского типа, идентифицирующий тип. Указатель на новую структуру можно получить из PyArray_DescrFromType с использованием возвращенного номера типа. Если произошла ошибка, возвращается -1. Если этот dtype уже зарегистрирован (проверяется только по адресу указателя), возвращается ранее назначенный номер типа.

intPyArray_RegisterCastFunc(PyArray_Descr*descr, inttotype, PyArray_VectorUnaryFunc*castfunc)

Регистрирует функцию низкоуровневого преобразования castfunc для преобразования из типа данных descr в заданный номер типа данных totype. Любая старая функция преобразования перезаписывается. В случае успеха возвращается 0, в случае неудачи -1.

intPyArray_RegisterCanCast(PyArray_Descr*descr, inttotype, NPY_SCALARKINDscalar)

Регистрирует номер типа данных totype как преобразуемый из объекта типа данных descr заданного типа scalar. Используйте scalar = NPY_NOSCALAR, чтобы зарегистрировать, что массив типа данных descr может быть безопасно преобразован в тип данных, номер которого totype.

Специальные функции для NPY_OBJECT

intPyArray_INCREF(PyArrayObject*op)

Используется для массива op, содержащего любые объекты Python. Увеличивает счетчик ссылок каждого объекта в массиве в соответствии с типом данных op. Если произошла ошибка, возвращается -1, в противном случае 0.

voidPyArray_Item_INCREF(char*ptr, PyArray_Descr*dtype)

Функция для увеличения счетчика ссылок всех объектов в позиции ptr в соответствии с типом данных dtype. Если ptr — начало структурированного типа с объектом в любом смещении, это (рекурсивно) увеличит счетчик ссылок всех объектов в структурированном типе.

intPyArray_XDECREF(PyArrayObject*op)

Используется для массива op, содержащего любые объекты Python. Уменьшает счетчик ссылок каждого объекта в массиве в соответствии с типом данных op. Нормальное значение возврата — 0. Если произошла ошибка, возвращается -1.

voidPyArray_Item_XDECREF(char*ptr, PyArray_Descr*dtype)

Функция для уменьшения счетчика ссылок всех объектов в позиции ptr, как указано в типе данных dtype. Это работает рекурсивно, поэтому если сам dtype имеет поля с типами данных, содержащими объекты, все поля объектов будут уменьшены 'd.

voidPyArray_FillObjectArray(PyArrayObject*arr, PyObject*obj)

Заполняет только что созданный массив одним значением obj во всех позициях со структурированными данными типа объект. Проверка не выполняется, но arr должен иметь тип данных NPY_OBJECT и быть односегментным и неинициализированным (нет предыдущих объектов в позиции). Используйте PyArray_XDECREF (arr), если вам нужно уменьшить все элементы массива объектов перед вызовом этой функции.

intPyArray_SetUpdateIfCopyBase(PyArrayObject*arr, PyArrayObject*base)

Предварительное условие: arr является копией base (хотя, возможно, с другими шагами, порядком и т. д.). Установите флаг UPDATEIFCOPY и arr->base, чтобы при уничтожении arr он копировал любые изменения обратно в base. УСТАРЕВШАЯ функция, используйте PyArray_SetWritebackIfCopyBase.

Возвращает 0 в случае успеха, -1 в случае неудачи.

intPyArray_SetWritebackIfCopyBase(PyArrayObject*arr, PyArrayObject*base)

Предварительное условие: arr является копией base (хотя, возможно, с другими шагами, порядком и т. д.). Устанавливает флаг NPY_ARRAY_WRITEBACKIFCOPY и arr->base, и устанавливает base в READONLY. Вызовите PyArray_ResolveWritebackIfCopy перед вызовом Py_DECREF для копирования любых изменений обратно в base и сброса флага READONLY.

Возвращает 0 в случае успеха, -1 в случае неудачи.

Флаги массива

Атрибут flags структуры PyArrayObject содержит важную информацию о памяти, используемой массивом (на который указывает член data). Эта информация о флагах должна быть точной, иначе могут возникнуть странные результаты и даже сегменты.

Существует 6 (бинарных) флагов, описывающих область памяти, используемую буфером данных. Эти константы определены в arrayobject.h и определяют битовую позицию флага. Python предоставляет удобный интерфейс на основе атрибутов, а также интерфейс типа словаря для получения (и, при необходимости, установки) этих флагов.

Области памяти всех типов могут быть указаны с помощью ndarray, что требует этих флагов. Если вы получаете произвольные PyArrayObject в коде C, вы должны учитывать установленные флаги. Если вам нужно гарантировать определённый тип массива (например, NPY_ARRAY_C_CONTIGUOUS и NPY_ARRAY_BEHAVED), то передайте эти требования в функцию PyArray_FromAny.

Основные флаги массива

ndarray может иметь сегмент данных, который не является простым непрерывным блоком хорошо организованной памяти, которую можно изменять. Он может не быть выровнен с границами слов (что очень важно на некоторых платформах). Данные могут быть в другом порядке байтов, чем распознаёт машина. Они могут быть не доступны для записи. Они могут быть в порядке Fortran-непрерывности. Флаги массива используются для указания того, что можно сказать о данных, связанных с массивом.

В версиях NumPy 1.6 и более ранних версиях следующие флаги не имели пространства имён макроса _ARRAY. Такая форма имён констант устарела в версии 1.7.

NPY_ARRAY_C_CONTIGUOUS

Область данных имеет порядок непрерывности в стиле C (индекс последнего элемента изменяется быстрее всего).

NPY_ARRAY_F_CONTIGUOUS

Область данных имеет порядок непрерывности в стиле Fortran (индекс первого элемента изменяется быстрее всего).

NPY_ARRAY_OWNDATA

Область данных принадлежит этому массиву.

NPY_ARRAY_ALIGNED

Область данных и все элементы массива должным образом выровнены.

NPY_ARRAY_WRITEABLE

Область данных может быть изменена.

Обратите внимание, что вышеперечисленные 3 флага определены таким образом, что новый, хорошо организованный массив имеет эти флаги, установленные как true.

NPY_ARRAY_WRITEBACKIFCOPY

Область данных представляет собой (хорошо организованную) копию, информация которой должна быть передана обратно в исходный массив, когда вызывается PyArray_ResolveWritebackIfCopy.

Это специальный флаг, который устанавливается, если этот массив представляет собой копию, созданную потому, что пользователь потребовал определённые флаги в PyArray_FromAny, и копия другого массива была обязательна (и пользователь запросил установку этого флага в такой ситуации). Атрибут base затем указывает на «плохо организованный» массив (который установлен в состояние read_only). :c:func`PyArray_ResolveWritebackIfCopy` скопирует его содержимое обратно в «плохо организованный» массив (с приведением типов, если необходимо) и сбросит «плохо организованный» массив до NPY_ARRAY_WRITEABLE. Если «плохо организованный» массив изначально не был NPY_ARRAY_WRITEABLE, то PyArray_FromAny вернул бы ошибку, потому что NPY_ARRAY_WRITEBACKIFCOPY не был бы возможен.

NPY_ARRAY_UPDATEIFCOPY

Устаревшая версия NPY_ARRAY_WRITEBACKIFCOPY, которая зависит от dealloc для запуска записи обратно. Для обеспечения обратной совместимости, PyArray_ResolveWritebackIfCopy вызывается в dealloc, но полагаться на это поведение устарело и не поддерживается в PyPy.

PyArray_UpdateFlags (obj, flags) обновит obj->flags для flags, которые могут быть любыми из NPY_ARRAY_C_CONTIGUOUS, NPY_ARRAY_F_CONTIGUOUS, NPY_ARRAY_ALIGNED или NPY_ARRAY_WRITEABLE.

Сочетания флагов массива

NPY_ARRAY_BEHAVED

NPY_ARRAY_ALIGNED | NPY_ARRAY_WRITEABLE

NPY_ARRAY_CARRAY

NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_BEHAVED

NPY_ARRAY_CARRAY_RO

NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_ALIGNED

NPY_ARRAY_FARRAY

NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_BEHAVED

NPY_ARRAY_FARRAY_RO

NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_ALIGNED

NPY_ARRAY_DEFAULT

NPY_ARRAY_CARRAY

NPY_ARRAY_UPDATE_ALL

NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_ALIGNED

Флаги-константы

Эти константы используются в PyArray_FromAny (и его макроформах) для указания желаемых свойств нового массива.

NPY_ARRAY_FORCECAST

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

NPY_ARRAY_ENSURECOPY

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

NPY_ARRAY_ENSUREARRAY

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

Проверка флагов

Для всех этих макросов arr должен быть экземпляром (подкласса) PyArray_Type.

intPyArray_CHKFLAGS(PyObject*arr, intflags)

Первый параметр, arr, должен быть массивом ndarray или его подклассом. Параметр flags должен быть целым числом, представляющим битовую комбинацию возможных флагов массива: NPY_ARRAY_C_CONTIGUOUS, NPY_ARRAY_F_CONTIGUOUS, NPY_ARRAY_OWNDATA, NPY_ARRAY_ALIGNED, NPY_ARRAY_WRITEABLE, NPY_ARRAY_WRITEBACKIFCOPY, NPY_ARRAY_UPDATEIFCOPY.

intPyArray_IS_C_CONTIGUOUS(PyObject*arr)

Возвращает истинное значение, если arr является непрерывным в стиле C.

intPyArray_IS_F_CONTIGUOUS(PyObject*arr)

Возвращает истинное значение, если arr является непрерывным в стиле Fortran.

intPyArray_ISFORTRAN(PyObject*arr)

Возвращает истинное значение, если arr является непрерывным в стиле Fortran и не непрерывным в стиле C. PyArray_IS_F_CONTIGUOUS — правильный способ проверки непрерывности в стиле Fortran.

intPyArray_ISWRITEABLE(PyObject*arr)

Возвращает истинное значение, если область данных arr может быть изменена.

intPyArray_ISALIGNED(PyObject*arr)

Возвращает истинное значение, если область данных arr правильно выровнена на машине.

intPyArray_ISBEHAVED(PyObject*arr)

Возвращает истинное значение, если область данных arr выровнена, может быть изменена и имеет порядок байтов машины в соответствии с её описанием.

intPyArray_ISBEHAVED_RO(PyObject*arr)

Возвращает истинное значение, если область данных arr выровнена и имеет порядок байтов машины.

intPyArray_ISCARRAY(PyObject*arr)

Возвращает истинное значение, если область данных arr непрерывна в стиле C, и PyArray_ISBEHAVED (arr) возвращает истинное значение.

intPyArray_ISFARRAY(PyObject*arr)

Возвращает истинное значение, если область данных arr непрерывна в стиле Fortran, и PyArray_ISBEHAVED (arr) возвращает истинное значение.

intPyArray_ISCARRAY_RO(PyObject*arr)

Возвращает истинное значение, если область данных arr непрерывна в стиле C, выровнена и имеет порядок байтов машины.

intPyArray_ISFARRAY_RO(PyObject*arr)

Возвращает истинное значение, если область данных arr непрерывна в стиле Fortran, выровнена и имеет порядок байтов машины.

intPyArray_ISONESEGMENT(PyObject*arr)

Возвращает истинное значение, если область данных arr состоит из одного непрерывного сегмента (в стиле C или Fortran).

voidPyArray_UpdateFlags(PyArrayObject*arr, intflagmask)

Флаги массива NPY_ARRAY_C_CONTIGUOUS, NPY_ARRAY_ALIGNED и NPY_ARRAY_F_CONTIGUOUS могут быть вычислены из объекта массива. Эта функция обновляет один или несколько из этих флагов arr, как указано в flagmask, выполнив необходимое вычисление.

Альтернативный API методов массива

Преобразование

PyObject*PyArray_GetField(PyArrayObject*self, PyArray_Descr*dtype, intoffset)

Эквивалентно ndarray.getfield (self, dtype, offset). Эта функция берет в свои владения ссылку на PyArray_Descr и возвращает новый массив заданного dtype, используя данные текущего массива в указанной offset в байтах. offset плюс размер элемента нового типа массива должны быть меньше self ->descr->elsize, иначе возникает ошибка. Используются те же размеры и шаги, что и в исходном массиве. Поэтому эта функция позволяет извлечь поле из структурированного массива. Но она также может использоваться для выбора определённых байтов или групп байтов из любого типа массива.

intPyArray_SetField(PyArrayObject*self, PyArray_Descr*dtype, intoffset, PyObject*val)

Эквивалентно ndarray.setfield (self, val, dtype, offset). Установить поле, начинающееся с offset в байтах и заданного типа dtype на значение val. offset плюс размер элемента dtype должен быть меньше размера элемента self ->descr или произойдет ошибка. В противном случае аргумент val преобразуется в массив и копируется в указанное поле. При необходимости элементы val повторяются для заполнения целевого массива, но количество элементов в целевом массиве должно быть целым кратным количеству элементов в val.

PyObject*PyArray_Byteswap(PyArrayObject*self, npy_boolinplace)

Эквивалентно ndarray.byteswap (self, inplace). Возвращает массив, область данных которого переставлена местами. Если inplace ненулевое, то выполняется перестановка байтов на месте и возвращается ссылка на self. В противном случае создаётся копия с перестановкой байтов и self остаётся неизменным.

PyObject*PyArray_NewCopy(PyArrayObject*old, NPY_ORDERorder)

Эквивалентно ndarray.copy (self, fortran). Создаёт копию массива old. Возвращаемый массив всегда выровнен и доступен для записи, и данные интерпретируются так же, как в исходном массиве. Если order — NPY_CORDER, то возвращается массив, непрерывный в стиле C. Если order — NPY_FORTRANORDER, то возвращается массив, непрерывный в стиле Fortran. Если order — NPY_ANYORDER, то возвращаемый массив непрерывный в стиле Fortran только в том случае, если исходный массив непрерывный в этом стиле; в противном случае он непрерывный в стиле C.

PyObject*PyArray_ToList(PyArrayObject*self)

Эквивалентно ndarray.tolist (self). Возвращает вложенный Python список из self.

PyObject*PyArray_ToString(PyArrayObject*self, NPY_ORDERorder)

Эквивалентно ndarray.tobytes (self, order). Возвращает байты этого массива в виде строки Python.

PyObject*PyArray_ToFile(PyArrayObject*self, FILE*fp, char*sep, char*format)

Записывает содержимое self в указатель на файл fp в непрерывном стиле C. Записывает данные как двоичные байты, если sep — это строка “” или NULL. В противном случае записывает содержимое self как текст, используя строку sep в качестве разделителя элементов. Каждый элемент будет выведен в файл. Если строка format не NULL или “”, то это строка формата Python print statement, показывающая, как элементы должны быть записаны.

intPyArray_Dump(PyObject*self, PyObject*file, intprotocol)

Записывает объект в self в указанный file (либо строка, либо объект Python файла). Если file — это строка Python, она рассматривается как имя файла, которое затем открывается в двоичном режиме. Используется заданный protocol (если protocol отрицательный, или используется наивысший доступный).

Это простой обертка над cPickle.dump(self, file, protocol).

PyObject*PyArray_Dumps(PyObject*self, intprotocol)

Записывает объект в self в строку Python и возвращает её. Используется предоставленный протокол Pickle protocol (или самый высокий доступный, если protocol отрицательный).

intPyArray_FillWithScalar(PyArrayObject*arr, PyObject*obj)

Заполняет массив arr заданным скалярным объектом obj. Объект сначала преобразуется в тип данных arr, а затем копируется в каждую ячейку. Возвращает -1 в случае ошибки, иначе 0.

PyObject*PyArray_View(PyArrayObject*self, PyArray_Descr*dtype, PyTypeObject*ptype)

Эквивалентно ndarray.view (self, dtype). Возвращает новый вид массива self, возможно с другим типом данных dtype и другим подклассом массива ptype.

Если dtype является NULL, то возвращаемый массив будет иметь тот же тип данных, что и self. Новый тип данных должен быть совместим с размером self. Либо размеры элементов должны быть идентичны, либо self должен быть односегментным, и общее количество байтов должно быть одинаковым. В последнем случае размерности возвращаемого массива будут изменены в последней (или первой для массивов, упорядоченных по Fortran) размерности. Область данных возвращаемого массива и self точно одинакова.

Изменение формы массива

PyObject*PyArray_Newshape(PyArrayObject*self, PyArray_Dims*newshape, NPY_ORDERorder)

Результат будет новым массивом (ссылающимся на ту же область памяти, что и self, если возможно), но с формой, заданной newshape. Если новая форма несовместима со смещениями self, то будет возвращена копия массива с новой указанной формой.

PyObject*PyArray_Reshape(PyArrayObject*self, PyObject*shape)

Эквивалентно ndarray.reshape (self, shape), где shape — последовательность. Преобразует shape в структуру PyArray_Dims и вызывает PyArray_Newshape внутри. Для обратной совместимости — Не рекомендуется

PyObject*PyArray_Squeeze(PyArrayObject*self)

Эквивалентно ndarray.squeeze (self). Возвращает новый вид self, из формы которого удалены все размерности длиной 1.

PyObject*PyArray_SwapAxes(PyArrayObject*self, inta1, inta2)

Эквивалентно ndarray.swapaxes (self, a1, a2). Возвращаемый массив — новый вид данных в self с переставленными осями a1 и a2.

PyObject*PyArray_Resize(PyArrayObject*self, PyArray_Dims*newshape, intrefcheck, NPY_ORDERfortran)

Эквивалентно ndarray.resize (self, newshape, refcheck = refcheck, order= fortran ). Эта функция работает только с односегментными массивами. Она изменяет форму self на месте и перераспределит память для self, если newshape имеет другое общее количество элементов, чем старая форма. Если необходимо перераспределение, то self должен владеть своими данными, иметь self - >base==NULL, иметь self - >weakrefs==NULL, и (если refcheck не равен 0) не ссылаться ни на какой другой массив. Аргумент fortran может быть NPY_ANYORDER, NPY_CORDER или NPY_FORTRANORDER. В настоящее время он не оказывает влияния. В конечном итоге он может использоваться для определения того, как операция изменения размера должна рассматривать данные при построении массива с другими измерениями. Возвращает None при успехе и NULL при ошибке.

PyObject*PyArray_Transpose(PyArrayObject*self, PyArray_Dims*permute)

Эквивалентно ndarray.transpose (self, permute). Переставляет оси объекта ndarray self в соответствии со структурой данных permute и возвращает результат. Если permute — NULL, то полученный массив имеет оси, переставленные в обратном порядке. Например, если self имеет форму \(10\times20\times30\), и permute .ptr равно (0,2,1), то форма результата — \(10\times30\times20\). Если permute — NULL, то форма результата — \(30\times20\times10\).

PyObject*PyArray_Flatten(PyArrayObject*self, NPY_ORDERorder)

Эквивалентно ndarray.flatten (self, order). Возвращает одномерную копию массива. Если order равен NPY_FORTRANORDER, элементы сканируются в порядке Fortran (быстрее изменяется первая размерность). Если order равен NPY_CORDER, элементы self сканируются в порядке C (быстрее изменяется последняя размерность). Если order равен NPY_ANYORDER, то используется результат PyArray_ISFORTRAN (self) для определения порядка выравнивания.

PyObject*PyArray_Ravel(PyArrayObject*self, NPY_ORDERorder)

Эквивалентно self.ravel(order). Имеет ту же основную функциональность, что и PyArray_Flatten (self, order), за исключением случая, когда order равен 0 и self является непрерывным в стиле C. В этом случае форма изменяется, но копия не создаётся.

Выбор элементов и манипуляции ими

PyObject*PyArray_TakeFrom(PyArrayObject*self, PyObject*indices, intaxis, PyArrayObject*ret, NPY_CLIPMODEclipmode)

Эквивалентно ndarray.take (self, indices, axis, ret, clipmode), за исключением того, что axis = None в Python соответствует axis = NPY_MAXDIMS в C. Извлекает элементы из self, указанные целочисленными indices вдоль заданной оси axis. Аргумент clipmode может принимать значения NPY_RAISE, NPY_WRAP или NPY_CLIP, указывающие, что делать с индексами за пределами границ. Аргумент ret может указывать на массив вывода вместо создания его внутри.

PyObject*PyArray_PutTo(PyArrayObject*self, PyObject*values, PyObject*indices, NPY_CLIPMODEclipmode)

Эквивалентно self.put(values, indices, clipmode). Размещает values в self по соответствующим (уплощенным) indices. Если values слишком маленький, он будет повторяться по мере необходимости.

PyObject*PyArray_PutMask(PyArrayObject*self, PyObject*values, PyObject*mask)

Размещает values в self там, где соответствующие позиции (используя уплощенный контекст) в mask истинны. Массивы mask и self должны иметь одинаковое общее количество элементов. Если values слишком маленький, он будет повторяться по мере необходимости.

PyObject*PyArray_Repeat(PyArrayObject*self, PyObject*op, intaxis)

Эквивалентно ndarray.repeat (self, op, axis). Копирует элементы self, op раз вдоль заданной оси axis. Либо op является скалярным целым числом, либо последовательностью длины self ->dimensions[ axis ], указывающей, сколько раз повторить каждый элемент вдоль оси.

PyObject*PyArray_Choose(PyArrayObject*self, PyObject*op, PyArrayObject*ret, NPY_CLIPMODEclipmode)

Эквивалентно ndarray.choose (self, op, ret, clipmode). Создаёт новый массив, выбирая элементы из последовательности массивов в op на основе целочисленных значений в self. Все массивы должны быть совместимы с одной формой, а элементы в self должны быть в диапазоне от 0 до len(op). Результат помещается в ret, если он не NULL, в противном случае создаётся новый массив результата. Аргумент clipmode определяет поведение, когда элементы в self не находятся в диапазоне от 0 до len(op).

NPY_RAISE

вызывает ValueError;

NPY_WRAP

значения < 0 оборачиваются путём добавления len(op), а значения >= len(op) - путём вычитания len(op) до тех пор, пока они не попадут в нужный диапазон;

NPY_CLIP

все значения обрезаются до области [0, len(op)).

PyObject*PyArray_Sort(PyArrayObject*self, intaxis, NPY_SORTKINDkind)

Эквивалентно ndarray.sort (self, axis, kind). Возвращает массив с элементами self, отсортированными по оси axis. Массив сортируется с использованием алгоритма, обозначенного kind, представляющего собой целое число/перечисление, указывающее тип используемого алгоритма сортировки.

PyObject*PyArray_ArgSort(PyArrayObject*self, intaxis)

Эквивалентно ndarray.argsort (self, axis). Возвращает массив индексов, такой что выбор этих индексов по заданной axis оси вернёт отсортированную версию self. Если self ->descr имеет определённые поля данных, то используется self->descr->names для определения порядка сортировки. Сравнение, в котором первое поле равно, будет использовать второе поле и так далее. Чтобы изменить порядок сортировки структурированного массива, создайте новый тип данных с другим порядком имён и создайте представление массива с этим новым типом данных.

PyObject*PyArray_LexSort(PyObject*sort_keys, intaxis)

Принимая последовательность массивов (sort_keys) одинаковой формы, возвращает массив индексов (подобный PyArray_ArgSort (…)), которые отсортируют массивы лексикографически. Лексикографическая сортировка означает, что когда два ключа оказываются равными, порядок определяется сравнением последующих ключей. Для типов должна быть определена сортировка слиянием (которая оставляет равные элементы неподвижными). Сортировка выполняется путём сортировки индексов сначала по первому sort_key, затем по второму sort_key и так далее. Это эквивалентно команде Python lexsort(sort_keys, axis). Из-за того, как работает сортировка слиянием, необходимо понимать порядок, в котором должны стоять sort_keys (обратный порядку, который вы использовали бы при сравнении двух элементов).

Если эти массивы собраны в структурированном массиве, то PyArray_Sort (…) также можно использовать для непосредственной сортировки массива.

PyObject*PyArray_SearchSorted(PyArrayObject*self, PyObject*values, NPY_SEARCHSIDEside, PyObject*perm)

Эквивалентно ndarray.searchsorted (self, values, side, perm). Предполагая, что self - одномерный массив в порядке возрастания, то результат - массив индексов такой же формы, как values, такой что, если элементы в values были вставлены перед индексами, порядок self сохранялся бы. Проверка того, что self отсортирован по возрастанию, не производится.

Аргумент side указывает, должен ли возвращённый индекс быть индексом первого подходящего местоположения (если NPY_SEARCHLEFT) или последнего (если NPY_SEARCHRIGHT).

Аргумент sorter, если он не NULL, должен быть одномерным массивом целочисленных индексов такой же длины, как self, которые сортируют его по возрастанию. Это обычно результат вызова PyArray_ArgSort (…). Для поиска требуемых точек вставки используется бинарный поиск.

intPyArray_Partition(PyArrayObject*self, PyArrayObject*ktharray, intaxis, NPY_SELECTKINDwhich)

Эквивалентно ndarray.partition (self, ktharray, axis, kind). Разделяет массив так, чтобы значения элемента, индексированного ktharray, находились в позициях, которые они занимали бы, если бы массив был полностью отсортирован, и помещает все элементы меньше, чем k-тый, перед ним, а все элементы, равные или большие, - после него. Порядок всех элементов внутри разделов не определён. Если self->descr имеет определённые поля данных, то используется self->descr->names для определения порядка сортировки. Сравнение, в котором первое поле равно, будет использовать второе поле и так далее. Чтобы изменить порядок сортировки структурированного массива, создайте новый тип данных с другим порядком имён и создайте представление массива с этим новым типом данных. Возвращает ноль при успехе и -1 при ошибке.

PyObject*PyArray_ArgPartition(PyArrayObject*op, PyArrayObject*ktharray, intaxis, NPY_SELECTKINDwhich)

Эквивалентно ndarray.argpartition (self, ktharray, axis, kind). Возвращает массив индексов, такой что выбор этих индексов вдоль заданной axis оси вернёт разбиение self.

PyObject*PyArray_Diagonal(PyArrayObject*self, intoffset, intaxis1, intaxis2)

Эквивалентно ndarray.diagonal (self, offset, axis1, axis2 ). Возвращает диагонали со смещением offset для 2-мерных массивов, определённых axis1 и axis2.

npy_intpPyArray_CountNonzero(PyArrayObject*self)

Добавлена в версии 1.6.

Подсчитывает количество ненулевых элементов в массиве self.

PyObject*PyArray_Nonzero(PyArrayObject*self)

Эквивалентно ndarray.nonzero (self). Возвращает кортеж массивов индексов, которые выбирают ненулевые элементы из self. Если (nd= PyArray_NDIM ( self ))==1, возвращается один массив индексов. Массивы индексов имеют тип данных NPY_INTP. Если возвращается кортеж (nd \(\neq\) 1), то его длина равна nd.

PyObject*PyArray_Compress(PyArrayObject*self, PyObject*condition, intaxis, PyArrayObject*out)

Эквивалентно ndarray.compress (self, condition, axis ). Возвращает элементы вдоль axis, соответствующие истинным элементам из condition.

Вычисление

PyObject*PyArray_ArgMax(PyArrayObject*self, intaxis, PyArrayObject*out)

Эквивалентно ndarray.argmax (self, axis). Возвращает индекс наибольшего элемента в self вдоль оси axis.

PyObject*PyArray_ArgMin(PyArrayObject*self, intaxis, PyArrayObject*out)

Эквивалентно ndarray.argmin (self, axis). Возвращает индекс наименьшего элемента в self вдоль оси axis.

PyObject*PyArray_Max(PyArrayObject*self, intaxis, PyArrayObject*out)

Эквивалентно ndarray.max (self, axis). Возвращает наибольший элемент в self вдоль заданной оси axis. Если результат — единственный элемент, возвращает скаляр NumPy вместо ndarray.

PyObject*PyArray_Min(PyArrayObject*self, intaxis, PyArrayObject*out)

Эквивалентно ndarray.min (self, axis). Возвращает наименьший элемент в self вдоль заданной оси axis. Если результат — единственный элемент, возвращает скаляр NumPy вместо ndarray.

PyObject*PyArray_Ptp(PyArrayObject*self, intaxis, PyArrayObject*out)

Эквивалентно ndarray.ptp (self, axis). Возвращает разницу между максимальным элементом массива self вдоль оси axis и минимальным элементом массива self вдоль оси axis. Если результат состоит из одного элемента, возвращается скаляр NumPy, а не ndarray.

PyObject*PyArray_Mean(PyArrayObject*self, intaxis, intrtype, PyArrayObject*out)

Эквивалентно ndarray.mean (self, axis, rtype). Возвращает среднее значение элементов вдоль заданной оси axis, используя перечисленный тип rtype в качестве типа данных для суммирования. Поведение суммы по умолчанию достигается с использованием NPY_NOTYPE для rtype.

PyObject*PyArray_Trace(PyArrayObject*self, intoffset, intaxis1, intaxis2, intrtype, PyArrayObject*out)

Эквивалентно ndarray.trace (self, offset, axis1, axis2, rtype). Возвращает сумму (используя rtype как тип данных суммирования) по диагональным элементам с offset, заданным двумерными массивами с axis1 и axis2. Положительное значение offset выбирает диагонали выше главной диагонали. Отрицательное значение offset выбирает диагонали ниже главной диагонали.

PyObject*PyArray_Clip(PyArrayObject*self, PyObject*min, PyObject*max)

Эквивалентно ndarray.clip (self, min, max). Обрезает массив self, так что значения, большие, чем max, устанавливаются равными max, а значения, меньшие, чем min, устанавливаются равными min.

PyObject*PyArray_Conjugate(PyArrayObject*self)

Эквивалентно ndarray.conjugate (self). Возвращает комплексно сопряжённое значение self. Если self не имеет комплексного типа данных, возвращает self со ссылкой.

PyObject*PyArray_Round(PyArrayObject*self, intdecimals, PyArrayObject*out)

Эквивалентно ndarray.round (self, decimals, out). Возвращает массив с элементами, округленными до ближайшего десятичного разряда. Десятичный разряд определяется как цифра \(10^{-\textrm{decimals}}\), так что отрицательные значения decimals вызывают округление до ближайших 10-к, 100-к и т. д. Если out NULL, то выходной массив создаётся, иначе результат помещается в out, который должен иметь правильный размер и тип.

PyObject*PyArray_Std(PyArrayObject*self, intaxis, intrtype, PyArrayObject*out)

Эквивалентно ndarray.std (self, axis, rtype). Возвращает стандартное отклонение, используя данные вдоль оси axis, преобразованные к типу данных rtype.

PyObject*PyArray_Sum(PyArrayObject*self, intaxis, intrtype, PyArrayObject*out)

Эквивалентно ndarray.sum (self, axis, rtype). Возвращает одномерный вектор сумм элементов в self вдоль оси axis. Суммирование выполняется после преобразования данных к типу данных rtype.

PyObject*PyArray_CumSum(PyArrayObject*self, intaxis, intrtype, PyArrayObject*out)

Эквивалентно ndarray.cumsum (self, axis, rtype). Возвращает кумулятивные 1-d суммы элементов в self вдоль axis. Выполняет суммирование после преобразования данных к типу данных rtype.

PyObject*PyArray_Prod(PyArrayObject*self, intaxis, intrtype, PyArrayObject*out)

Эквивалентно ndarray.prod (self, axis, rtype). Возвращает 1-d произведения элементов в self вдоль axis. Выполняет произведение после преобразования данных к типу данных rtype.

PyObject*PyArray_CumProd(PyArrayObject*self, intaxis, intrtype, PyArrayObject*out)

Эквивалентно ndarray.cumprod (self, axis, rtype). Возвращает 1-d кумулятивные произведения элементов в self вдоль axis. Выполняет произведение после преобразования данных к типу данных rtype.

PyObject*PyArray_All(PyArrayObject*self, intaxis, PyArrayObject*out)

Эквивалентно ndarray.all (self, axis). Возвращает массив со значениями True для каждого 1-d подмассива self, определённого axis, в котором все элементы равны True.

PyObject*PyArray_Any(PyArrayObject*self, intaxis, PyArrayObject*out)

Эквивалентно ndarray.any (self, axis). Возвращает массив со значениями True для каждого 1-d подмассива self, определённого axis, в котором любой из элементов равен True.

Функции

Функции массивов

intPyArray_AsCArray(PyObject**op, void*ptr, npy_intp*dims, intnd, inttypenum, intitemsize)

Иногда бывает полезно обращаться к многомерному массиву как к массиву на С, чтобы алгоритмы можно было реализовать с использованием синтаксиса C-style a[i][j][k]. Эта функция возвращает указатель ptr, который моделирует такой массив на С, для 1-, 2- и 3-мерных массивов.

Параметры

• op – Указатель на любой объект Python. Этот объект Python будет заменён на эквивалентный корректный, непрерывный массив ndarray заданного типа данных, указанного в последних двух аргументах. Убедитесь, что взятие ссылки на входной объект таким образом оправдано.
• ptr – Указатель на переменную (ctype* для 1-d, ctype** для 2-d или ctype*** для 3-d), где ctype — эквивалентный тип С для типа данных. По возвращении ptr будет доступен как 1-d, 2-d или 3-d массив.
• dims – Массив вывода, содержащий форму объекта массива. Этот массив задаёт границы любых циклов, которые будут выполняться.
• nd – Размеры массива (1, 2 или 3).
• typenum – Ожидаемый тип данных массива.
• itemsize – Этот аргумент необходим только тогда, когда typenum представляет собой гибкий массив. В противном случае он должен быть равен 0.

intPyArray_Free(PyObject*op, void*ptr)

Должен вызываться с теми же объектами и областями памяти, возвращёнными из PyArray_AsCArray (…). Эта функция очищает память, которая в противном случае могла бы утечь.

PyObject*PyArray_Concatenate(PyObject*obj, intaxis)

Объединяет последовательность объектов в obj вместе вдоль axis в один массив. Если размеры или типы несовместимы, возникает ошибка.

PyObject*PyArray_InnerProduct(PyObject*obj1, PyObject*obj2)

Вычисляет произведение-сумму по последним измерениям obj1 и obj2. Ни один массив не сопряжён.

PyObject*PyArray_MatrixProduct(PyObject*obj1, PyObject*obj)

Вычислить произведение-сумму по последнему измерению массива obj1 и предпоследнему измерению obj2. Для двумерных массивов это матричное произведение. Ни один массив не конъюгируется.

PyObject*PyArray_MatrixProduct2(PyObject*obj1, PyObject*obj, PyArrayObject*out)

Новое в версии 1.6.

То же, что и PyArray_MatrixProduct, но результат сохраняется в out. Результирующий массив должен иметь правильную форму, тип и быть C-непрерывным, иначе возникает исключение.

PyObject*PyArray_EinsteinSum(char*subscripts, npy_intpnop, PyArrayObject**op_in, PyArray_Descr*dtype, NPY_ORDERorder, NPY_CASTINGcasting, PyArrayObject*out)

Новое в версии 1.6.

Применяет соглашение об эйнштейновской сумме к предоставленным операндам массива, возвращая новый массив или помещая результат в out. Строка в subscripts — это список индексных букв, разделенных запятыми. Количество операндов — в nop, а op_in — массив, содержащий эти операнды. Тип данных результата можно принудительно задать с помощью dtype, порядок вывода можно принудительно задать с помощью order (NPY_KEEPORDER рекомендуется), а когда dtype указан, casting указывает, насколько допускается преобразование данных.

Дополнительные сведения см. в функции einsum.

PyObject*PyArray_CopyAndTranspose(PyObject*op)

Специализированная функция копирования и транспонирования, которая работает только с двумерными массивами. Возвращаемый массив — это транспонированная копия op.

PyObject*PyArray_Correlate(PyObject*op1, PyObject*op2, intmode)

Вычислить одномерную корреляцию одномерных массивов op1 и op2. Корреляция вычисляется в каждой точке вывода путем умножения op1 на сдвинутую версию op2 и суммирования результата. Вследствие сдвига необходимые значения за пределами заданного диапазона op1 и op2 интерпретируются как ноль. Режим определяет, сколько сдвигов вернуть: 0 — вернуть только сдвиги, для которых не нужно было предполагать нулевые значения; 1 — вернуть объект того же размера, что и op1; 2 — вернуть все возможные сдвиги (принимается любое перекрытие).

Примечания

Это не вычисляет обычную корреляцию: если op2 больше, чем op1, аргументы меняются местами, и конъюгат никогда не берется для комплексных массивов. См. PyArray_Correlate2 для обычной корреляции обработки сигналов.

PyObject*PyArray_Correlate2(PyObject*op1, PyObject*op2, intmode)

Обновленная версия PyArray_Correlate, которая использует обычное определение корреляции для одномерных массивов. Корреляция вычисляется в каждой точке вывода путем умножения op1 на сдвинутую версию op2 и суммирования результата. Вследствие сдвига необходимые значения за пределами заданного диапазона op1 и op2 интерпретируются как ноль. Режим определяет, сколько сдвигов вернуть: 0 — вернуть только сдвиги, для которых не нужно было предполагать нулевые значения; 1 — вернуть объект того же размера, что и op1; 2 — вернуть все возможные сдвиги (принимается любое перекрытие).

Примечания

Вычислить z следующим образом:

z[k] = sum_n op1[n] * conj(op2[n+k])

PyObject*PyArray_Where(PyObject*condition, PyObject*x, PyObject*y)

Если и x и y — NULL, то возвратить PyArray_Nonzero (condition). В противном случае, и x, и y должны быть заданы, и возвращаемый объект имеет форму condition и содержит элементы x и y, где condition соответственно True или False.

Другие функции

npy_boolPyArray_CheckStrides(intelsize, intnd, npy_intpnumbytes, npy_intpconst*dims, npy_intpconst*newstrides)

Определяет, является ли массив newstrides массивом шагов, согласованным с памятью массива с nd измерениями и формой dims и размером элемента elsize. Проверяется массив newstrides, чтобы убедиться, что переход по предоставленному количеству байтов в каждом направлении никогда не означает перехода более чем на numbytes, которое предполагается размером доступного сегмента памяти. Если numbytes равно 0, то вычисляется эквивалентное значение numbytes, предполагая, что nd, dims и elsize относятся к массиву с одним сегментом. Возвращает NPY_TRUE, если newstrides приемлемо, в противном случае возвращает NPY_FALSE.

npy_intpPyArray_MultiplyList(npy_intpconst*seq, intn)

intPyArray_MultiplyIntList(intconst*seq, intn)

Обе эти процедуры умножают массив целых чисел длиной n, seq, и возвращают результат. Проверка переполнения не выполняется.

intPyArray_CompareLists(npy_intpconst*l1, npy_intpconst*l2, intn)

Для двух массивов целых чисел длины n, l1 и l2, возвращает 1, если списки идентичны; в противном случае возвращает 0.

Вспомогательные данные со семантикой объектов

typeNpyAuxData

При работе с более сложными типами данных, которые состоят из других типов данных, таких как тип данных struct, для создания внутренних циклов, которые манипулируют типами данных, требуется передача дополнительных данных. NumPy поддерживает эту идею через структуру NpyAuxData, предписывая несколько соглашений, чтобы это было возможно.

Определение NpyAuxData похоже на определение класса в C++, но семантика объектов должна отслеживаться вручную, так как API написан на C. Вот пример функции, которая удваивает элемент, используя функцию копирования элемента в качестве примитива.

typedef struct {
    NpyAuxData base;
    ElementCopier_Func *func;
    NpyAuxData *funcdata;
} eldoubler_aux_data;

void free_element_doubler_aux_data(NpyAuxData *data)
{
    eldoubler_aux_data *d = (eldoubler_aux_data *)data;
    /* Free the memory owned by this auxdata */
    NPY_AUXDATA_FREE(d->funcdata);
    PyArray_free(d);
}

NpyAuxData *clone_element_doubler_aux_data(NpyAuxData *data)
{
    eldoubler_aux_data *ret = PyArray_malloc(sizeof(eldoubler_aux_data));
    if (ret == NULL) {
        return NULL;
    }

    /* Raw copy of all data */
    memcpy(ret, data, sizeof(eldoubler_aux_data));

    /* Fix up the owned auxdata so we have our own copy */
    ret->funcdata = NPY_AUXDATA_CLONE(ret->funcdata);
    if (ret->funcdata == NULL) {
        PyArray_free(ret);
        return NULL;
    }

    return (NpyAuxData *)ret;
}

NpyAuxData *create_element_doubler_aux_data(
                            ElementCopier_Func *func,
                            NpyAuxData *funcdata)
{
    eldoubler_aux_data *ret = PyArray_malloc(sizeof(eldoubler_aux_data));
    if (ret == NULL) {
        PyErr_NoMemory();
        return NULL;
    }
    memset(&ret, 0, sizeof(eldoubler_aux_data));
    ret->base->free = &free_element_doubler_aux_data;
    ret->base->clone = &clone_element_doubler_aux_data;
    ret->func = func;
    ret->funcdata = funcdata;

    return (NpyAuxData *)ret;
}

typeNpyAuxData_FreeFunc

Тип указателя на функцию для освобождения NpyAuxData.

typeNpyAuxData_CloneFunc

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

voidNPY_AUXDATA_FREE(NpyAuxData*auxdata)

Макрос, который вызывает соответствующую функцию освобождения auxdata, не выполняет никаких действий, если auxdata равен NULL.

NpyAuxData*NPY_AUXDATA_CLONE(NpyAuxData*auxdata)

Макрос, который вызывает соответствующую функцию клонирования auxdata, возвращая глубокую копию вспомогательных данных.

Итераторы массивов

Начиная с NumPy 1.6.0, эти итераторы массивов устарели, заменены новым итератором массива NpyIter.

Итератор массива — это простой способ быстро и эффективно получить доступ к элементам N-мерного массива. В разделе 2 приведены более подробное описание и примеры этого полезного подхода к циклическому прохождению массива.

PyObject*PyArray_IterNew(PyObject*arr)

Возвращает объект итератора массива из массива arr. Это эквивалентно arr. flat. Объект итератора массива упрощает циклическое прохождение N-мерного несмежного массива в C-подобном смежном порядке.

PyObject*PyArray_IterAllButAxis(PyObject*arr, int*axis)

Возвращает итератор массива, который будет перебирать все оси, кроме той, которая указана в *axis. Полученный итератор нельзя использовать с PyArray_ITER_GOTO1D. Этот итератор можно использовать для написания чего-то подобного тому, что делают ufunc, где цикл по наибольшей оси выполняется отдельной подпрограммой. Если *axis отрицательный, то *axis устанавливается на ось с наименьшим шагом, и эта ось используется.

PyObject*PyArray_BroadcastToShape(PyObject*arr, npy_intpconst*dimensions, intnd)

Возвращает итератор массива, который выполняется с расширением до перебора как массива формы, заданной dimensions и nd.

intPyArrayIter_Check(PyObject*op)

Возвращает true, если op является итератором массива (или экземпляром подкласса типа итератора массива).

voidPyArray_ITER_RESET(PyObject*iterator)

Сбросить iterator в начало массива.

voidPyArray_ITER_NEXT(PyObject*iterator)

Увеличивает индекс и члены dataptr объекта iterator, чтобы они указывали на следующий элемент массива. Если массив не является (в стиле C) непрерывным, также увеличивается массив N-мерных координат.

void*PyArray_ITER_DATA(PyObject*iterator)

Указатель на текущий элемент массива.

voidPyArray_ITER_GOTO(PyObject*iterator, npy_intp*destination)

Устанавливает индекс, dataptr и члены координат объекта iterator в местоположение в массиве, указанное N-мерным массивом C, destination, размер которого должен быть по крайней мере iterator ->nd_m1+1.

voidPyArray_ITER_GOTO1D(PyObject*iterator, npy_intpindex)

Устанавливает индекс и dataptr объекта iterator в местоположение в массиве, указанное целым числом index, которое указывает на элемент в массиве в стиле C.

intPyArray_ITER_NOTDONE(PyObject*iterator)

Возвращает TRUE, пока итератор не прошел все элементы, иначе FALSE.

Вещание (многочисленные итераторы)

PyObject*PyArray_MultiIterNew(intnum, ...)

Упрощенный интерфейс для вещания. Эта функция принимает количество массивов для вещания, а затем дополнительные num аргументов. Эти аргументы преобразуются в массивы, и создаются итераторы. Затем вызывается PyArray_Broadcast для полученного объекта многомерного итератора. Полученный объект многомерного итератора с вещанием возвращается. Затем операцию вещания можно выполнить с помощью одного цикла и с помощью PyArray_MultiIter_NEXT (..)

voidPyArray_MultiIter_RESET(PyObject*multi)

Сбросить все итераторы в начало в объекте многомерного итератора multi.

voidPyArray_MultiIter_NEXT(PyObject*multi)

Перевести каждый итератор в объекте многомерного итератора multi на следующий (расширенный) элемент.

void*PyArray_MultiIter_DATA(PyObject*multi, inti)

Возвращает указатель на данные i-го итератора в объекте многомерного итератора.

voidPyArray_MultiIter_NEXTi(PyObject*multi, inti)

Перемещает указатель только i-го итератора.

voidPyArray_MultiIter_GOTO(PyObject*multi, npy_intp*destination)

Перемещает каждый итератор в объекте многомерного итератора multi в заданное \(N\) -мерное значение destination, где \(N\) - количество измерений в расширенном массиве.

voidPyArray_MultiIter_GOTO1D(PyObject*multi, npy_intpindex)

Перемещает каждый итератор в объекте многомерного итератора multi в соответствующее местоположение индекса index в сплющенном массиве с вещанием.

intPyArray_MultiIter_NOTDONE(PyObject*multi)

Возвращает TRUE, пока многомерный итератор не перебрал все элементы (результата вещания), иначе FALSE.

intPyArray_Broadcast(PyArrayMultiIterObject*mit)

Эта функция описывает правила вещания. Контейнер mit должен уже содержать итераторы для всех массивов, которые нужно распространить. По возвращении эти итераторы будут скорректированы таким образом, чтобы итерация над каждым из них одновременно выполняла вещание. Возвращается отрицательное число, если произошла ошибка.

intPyArray_RemoveSmallest(PyArrayMultiIterObject*mit)

Эта функция принимает объект многомерного итератора, который был предварительно «расширен», находит измерение с наименьшей «суммой шагов» в расширенном результате и адаптирует все итераторы таким образом, чтобы не итерироваться по этому измерению (эффективно делая их длиной 1 в этом измерении). Соответствующее измерение возвращается, если mit ->nd равно 0, тогда возвращается -1. Эта функция полезна для создания процедур, похожих на ufunc, которые правильно расширяют свои входные данные, а затем вызывают одно-мерную процедуру со строками в качестве внутреннего цикла. Эта одно-мерная версия обычно оптимизирована для скорости, и поэтому цикл должен выполняться по оси, которая не потребует больших прыжков по шагам.

Итератор окрестности

Итераторы окрестности являются подклассами объекта итератора и могут использоваться для итерирования по окрестности точки. Например, вы можете итерироваться по каждому вокселю 3d изображения и для каждого такого вокселя итерироваться по гиперкубу. Итератор окрестности автоматически обрабатывает границы, что делает этот код намного проще писать, чем ручное управление границами, за счет незначительной накладной.

PyObject*PyArray_NeighborhoodIterNew(PyArrayIterObject*iter, npy_intpbounds, intmode, PyArrayObject*fill_value)

Эта функция создает новый итератор окрестности из существующего итератора. Окрестность будет вычислена относительно позиции, на которую в данный момент указывает iter, границы определяют форму итератора окрестности, а аргумент режима — режим обработки границ.

Ожидается, что аргумент bounds будет (2 * iter->ao->nd) массивом, например, диапазон bound[2*i]->bounds[2*i+1] определяет диапазон, в котором нужно перемещаться для измерения i (оба диапазона включаются в пройденные координаты). Границы должны быть упорядочены для каждого измерения (bounds[2*i] <= bounds[2*i+1]).

Режим должен быть одним из:

NPY_NEIGHBORHOOD_ITER_ZERO_PADDING

Заполнение нулями. Значения за пределами границ будут равны 0.

NPY_NEIGHBORHOOD_ITER_ONE_PADDING

Заполнение единицами. Значения за пределами границ будут равны 1.

NPY_NEIGHBORHOOD_ITER_CONSTANT_PADDING

Заполнение константами. Значения за пределами границ будут такими же, как у первого элемента в fill_value.

NPY_NEIGHBORHOOD_ITER_MIRROR_PADDING

Заполнение зеркальным отражением. Значения за пределами границ будут такими, как если бы элементы массива были зеркально отражены. Например, для массива [1, 2, 3, 4], x[-2] будет 2, x[-2] будет 1, x[4] будет 4, x[5] будет 1 и т.д…

NPY_NEIGHBORHOOD_ITER_CIRCULAR_PADDING

Циклическое заполнение. Значения за пределами границ будут такими, как если бы массив повторялся. Например, для массива [1, 2, 3, 4], x[-2] будет 3, x[-2] будет 4, x[4] будет 1, x[5] будет 2 и т.д…

Если режим — постоянное заполнение (NPY_NEIGHBORHOOD_ITER_CONSTANT_PADDING), fill_value должен указывать на объект массива, который содержит значение заполнения (первый элемент будет значением заполнения, если массив содержит более одного элемента). В других случаях fill_value может быть NULL.

• Итератор хранит ссылку на iter
• Возвращает NULL при ошибке (в этом случае счетчик ссылок iter не меняется)
• Сам iter может быть итератором окрестности: это может быть полезно для автоматической обработки границ
• объект, возвращаемый этой функцией, безопасен для использования в качестве обычного итератора
• Если позиция iter изменена, любое последующее обращение к PyArrayNeighborhoodIter_Next является неопределенным поведением, и необходимо вызвать PyArrayNeighborhoodIter_Reset.

PyArrayIterObject *iter;
PyArrayNeighborhoodIterObject *neigh_iter;
iter = PyArray_IterNew(x);

/*For a 3x3 kernel */
bounds = {-1, 1, -1, 1};
neigh_iter = (PyArrayNeighborhoodIterObject*)PyArrayNeighborhoodIter_New(
     iter, bounds, NPY_NEIGHBORHOOD_ITER_ZERO_PADDING, NULL);

for(i = 0; i < iter->size; ++i) {
     for (j = 0; j < neigh_iter->size; ++j) {
             /* Walk around the item currently pointed by iter->dataptr */
             PyArrayNeighborhoodIter_Next(neigh_iter);
     }

     /* Move to the next point of iter */
     PyArrayIter_Next(iter);
     PyArrayNeighborhoodIter_Reset(neigh_iter);
}

intPyArrayNeighborhoodIter_Reset(PyArrayNeighborhoodIterObject*iter)

Сбрасывает позицию итератора в первую точку окрестности. Это необходимо каждый раз, когда изменяется аргумент iter, переданный в PyArray_NeighborhoodIterObject (см. пример)

intPyArrayNeighborhoodIter_Next(PyArrayNeighborhoodIterObject*iter)

После этого вызова iter->dataptr указывает на следующую точку окрестности. Вызов этой функции после посещения каждой точки окрестности является неопределенным поведением.

Массивовые скаляры

PyObject*PyArray_Return(PyArrayObject*arr)

Эта функция заимствует ссылку на arr.

Эта функция проверяет, является ли arr массивом размерности 0, и если да, возвращает соответствующий скаляр массива. Она должна использоваться всякий раз, когда в Python могут быть возвращены массивы размерности 0.

PyObject*PyArray_Scalar(void*data, PyArray_Descr*dtype, PyObject*itemsize)

Возвращает объект массивового скаляра заданного перечисленного typenum и itemsize, копируя данные из памяти, на которую указывает data. Если swap не равно нулю, эта функция переставляет байты данных, если это необходимо, для типа данных, так как скаляры массивов всегда имеют правильный порядок байтов машины.

PyObject*PyArray_ToScalar(void*data, PyArrayObject*arr)

Возвращает объект массивового скаляра типа и размера элемента, указанного объектом массива arr, скопированный из памяти, на которую указывает data, и меняет порядок байтов, если данные в arr не в порядке байтов машины.

PyObject*PyArray_FromScalar(PyObject*scalar, PyArray_Descr*outcode)

Возвращает массив размерности 0 типа, определяемого outcode из scalar, который должен быть объектом массивового скаляра. Если outcode равен NULL, тип определяется из scalar.

voidPyArray_ScalarAsCtype(PyObject*scalar, void*ctypeptr)

Возвращает в ctypeptr указатель на фактическое значение в скаляре массива. Проверка ошибок отсутствует, поэтому scalar должен быть объектом скаляра массива, а ctypeptr должен иметь достаточно места для хранения правильного типа. Для типов с гибким размером в память ctypeptr копируется указатель на данные, для всех других типов фактические данные копируются в адрес, на который указывает ctypeptr.

voidPyArray_CastScalarToCtype(PyObject*scalar, void*ctypeptr, PyArray_Descr*outcode)

Возвращает данные (приведенные к типу данных, указанному в outcode) из скаляра массива scalar в память, на которую указывает ctypeptr (размер которого должен быть достаточным для обработки входных данных).

PyObject*PyArray_TypeObjectFromType(inttype)

Возвращает объект скалярного типа по номеру типа type. Эквивалентно PyArray_DescrFromType (type)->typeobj, за исключением учёта ссылок и проверки ошибок. Возвращает новую ссылку на объект типа при успехе или NULL при ошибке.

NPY_SCALARKINDPyArray_ScalarKind(inttypenum, PyArrayObject**arr)

См. функцию PyArray_MinScalarType для альтернативного механизма, введённого в NumPy 1.6.0.

Возвращает тип скаляра, представленного typenum и массива в *arr (если arr не NULL). Массив предполагается нулевой размерности и используется только если typenum представляет целое число со знаком. Если arr не NULL и первый элемент отрицательный, то возвращается NPY_INTNEG_SCALAR, в противном случае NPY_INTPOS_SCALAR. Возможные возвращаемые значения перечислены в NPY_SCALARKIND.

intPyArray_CanCoerceScalar(charthistype, charneededtype, NPY_SCALARKINDscalar)

См. функцию PyArray_ResultType для получения подробностей о повышении типа в NumPy, обновлённом в NumPy 1.6.0.

Реализует правила приведения скаляров. Скаляры неявно приводятся от thistype к neededtype только если эта функция возвращает ненулевое значение. Если scalar равен NPY_NOSCALAR, то эта функция эквивалентна PyArray_CanCastSafely. Правило заключается в том, что скаляры одного KIND могут быть приведены к массивам того же KIND. Это правило означает, что скаляры высокой точности никогда не приведут к повышению точности массивов низкой точности одного KIND.

Описания типов данных

intPyArray_DescrCheck(PyObject*obj)

Возвращает истинное значение, если obj является объектом типа данных ( PyArray_Descr* ).

PyArray_Descr*PyArray_DescrNew(PyArray_Descr*obj)

Возвращает новый объект типа данных, скопированный из obj (поля ссылки просто обновляются, так что новый объект указывает на тот же словарь полей, если таковой имеется).

PyArray_Descr*PyArray_DescrNewFromType(inttypenum)

Создаёт новый объект типа данных из встроенного (или зарегистрированного пользователем) типа данных, указанного typenum. Все встроенные типы не должны изменять свои поля. Это создаёт новую копию структуры PyArray_Descr, чтобы вы могли заполнить её по мере необходимости. Эта функция особенно нужна для типов данных с гибким размером, которым необходимо новое значение elsize, чтобы иметь смысл при построении массива.

PyArray_Descr*PyArray_DescrNewByteorder(PyArray_Descr*obj, charnewendian)

Создаёт новый объект типа данных с установленным порядком байтов в соответствии с newendian. Все связанные объекты типов данных (в членах subdescr и fields объекта типа данных) также изменяются (рекурсивно).

Значение newendian — одна из этих макрокоманд:

NPY_IGNORE

NPY_SWAP

NPY_NATIVE

NPY_LITTLE

NPY_BIG

Если встречается порядок байтов NPY_IGNORE, он остаётся без изменений. Если newendian равен NPY_SWAP, то все порядки байтов меняются. Другие допустимые значения newendian — NPY_NATIVE, NPY_LITTLE и NPY_BIG, которые все приводят к тому, что у возвращаемого описателя типа данных (и всех связанных с ним описателей типов данных) устанавливается соответствующий порядок байтов.

PyArray_Descr*PyArray_DescrFromObject(PyObject*op, PyArray_Descr*mintype)

Определяет подходящий объект типа данных из объекта op (который должен быть объектом "вложенной" последовательности) и минимального описателя типа данных mintype (который может быть NULL). Поведение аналогично array(op).dtype. Не путайте эту функцию с PyArray_DescrConverter. Эта функция по существу просматривает все объекты во (вложенной) последовательности и определяет тип данных из найденных элементов.

PyArray_Descr*PyArray_DescrFromScalar(PyObject*scalar)

Возвращает объект типа данных из объекта массива-скаляра. Проверка того, что scalar является скаляром массива, не выполняется. Если подходящий тип данных определить невозможно, по умолчанию возвращается тип данных NPY_OBJECT.

PyArray_Descr*PyArray_DescrFromType(inttypenum)

Возвращает объект типа данных, соответствующий typenum. typenum может быть одним из перечисленных типов, кодом символа для одного из перечисленных типов или пользовательским типом. Если вы хотите использовать массив с гибким размером, вам нужно flexible typenum и установить результат elsize параметр на желаемый размер. Значение typenum должно быть одним из NPY_TYPES.

intPyArray_DescrConverter(PyObject*obj, PyArray_Descr**dtype)

Преобразует любой совместимый объект Python, obj, в объект типа данных в dtype. Большое количество объектов Python может быть преобразовано в объекты типа данных. Полное описание см. в Объекты типов данных (dtype). Этот вариант преобразователя преобразует объекты None в объект типа данных NPY_DEFAULT_TYPE. Эту функцию можно использовать с символом кода “O&” в PyArg_ParseTuple обработке.

intPyArray_DescrConverter2(PyObject*obj, PyArray_Descr**dtype)

Преобразует любой совместимый объект Python, obj, в объект типа данных в dtype. Этот вариант преобразователя преобразует объекты None таким образом, что возвращаемым типом данных является NULL. Эту функцию также можно использовать с символом “O&” в обработке PyArg_ParseTuple.

intPyarray_DescrAlignConverter(PyObject*obj, PyArray_Descr**dtype)

Аналогично PyArray_DescrConverter, за исключением того, что объекты, подобные C-структурам, выравниваются на границах слов так, как это делает компилятор.

intPyarray_DescrAlignConverter2(PyObject*obj, PyArray_Descr**dtype)

Аналогично PyArray_DescrConverter2, за исключением того, что объекты, подобные C-структурам, выравниваются на границах слов так, как это делает компилятор.

PyObject*PyArray_FieldNames(PyObject*dict)

Принимает словарь полей, dict, например, прикрепленный к объекту типа данных, и создаёт упорядоченный список имён полей, как хранится в поле names объекта PyArray_Descr .

Утилиты преобразования

Для использования с PyArg_ParseTuple

Все эти функции могут быть использованы в PyArg_ParseTuple (…) с форматом спецификатора “O&”, чтобы автоматически преобразовать любой объект Python в требуемый объект C. Все эти функции возвращают NPY_SUCCEED при успехе и NPY_FAIL при неудаче. Первый аргумент для всех этих функций — это объект Python. Второй аргумент — это адрес типа C, в который нужно преобразовать объект Python.

intPyArray_Converter(PyObject*obj, PyObject**address)

Преобразует любой объект Python в PyArrayObject. Если PyArray_Check (obj) ИСТИНА, то его счётчик ссылок увеличивается, а ссылка помещается в address. Если obj не является массивом, то он преобразуется в массив с помощью PyArray_FromAny. Независимо от возвращаемого значения, вы должны DECREF объект, возвращённый этой функцией в address, когда закончите с ним.

intPyArray_OutputConverter(PyObject*obj, PyArrayObject**address)

Это по умолчанию преобразователь для выходных массивов, передаваемых функциям. Если obj равен Py_None или NULL, то *address будет NULL, но вызов успешно выполнится. Если PyArray_Check (obj) истинно, то он будет возвращён в *address без увеличения счётчика ссылок.

intPyArray_IntpConverter(PyObject*obj, PyArray_Dims*seq)

Преобразование любого Python-последовательности obj, меньшей чем NPY_MAXDIMS, в C-массив npy_intp. Python-объект также может быть единственным числом. Переменная seq - указатель на структуру с полями ptr и len. При успешном возвращении seq ->ptr содержит указатель на память, которую необходимо освободить, вызвав PyDimMem_FREE, чтобы избежать утечки памяти. Ограничение на размер памяти позволяет удобно использовать этот преобразователь для последовательностей, предназначенных для интерпретации как форм массива.

intPyArray_BufferConverter(PyObject*obj, PyArray_Chunk*buf)

Преобразование любого Python-объекта obj с интерфейсом (односегментного) буфера в переменную с полями, которые подробно описывают использование объекта его куска памяти. Переменная buf - указатель на структуру с полями base, ptr, len и flags. Структура PyArray_Chunk бинарно совместима с Python-объектом буфера (через его поле len на 32-битных платформах и поле ptr на 64-битных платформах или в Python 2.5). При возвращении поле base устанавливается в obj (или его base, если obj уже является объектом буфера, указывающим на другой объект). Если вам нужно сохранить память, убедитесь, что INCREF поле base. Кусок памяти указан полем buf ->ptr и имеет длину buf ->len. Поле flags в buf имеет значение NPY_ARRAY_ALIGNED с установленным флагом NPY_ARRAY_WRITEABLE, если obj имеет интерфейс записываемого буфера.

intPyArray_AxisConverter(PyObject*obj, int*axis)

Преобразование Python-объекта obj, представляющего аргумент оси, в правильное значение для передачи функциям, которые принимают целочисленную ось. В частности, если obj равен None, axis устанавливается в NPY_MAXDIMS, что интерпретируется правильно функциями C-API, которые принимают аргументы оси.

intPyArray_BoolConverter(PyObject*obj, npy_bool*value)

Преобразование любого Python-объекта obj в NPY_TRUE или NPY_FALSE и помещение результата в value.

intPyArray_ByteorderConverter(PyObject*obj, char*endian)

Преобразование Python-строк в соответствующий символ порядка байтов: ‘>’, ‘<’, ‘s’, ‘=’, или ‘|’.

intPyArray_SortkindConverter(PyObject*obj, NPY_SORTKIND*sort)

Преобразование Python-строк в один из NPY_QUICKSORT (начинается с ‘q’ или ‘Q’), NPY_HEAPSORT (начинается с ‘h’ или ‘H’), NPY_MERGESORT (начинается с ‘m’ или ‘M’) или NPY_STABLESORT (начинается с ‘t’ или ‘T’). NPY_MERGESORT и NPY_STABLESORT являются псевдонимами друг друга для обратной совместимости и могут ссылаться на один из нескольких стабильных алгоритмов сортировки в зависимости от типа данных.

intPyArray_SearchsideConverter(PyObject*obj, NPY_SEARCHSIDE*side)

Преобразование Python-строк в один из NPY_SEARCHLEFT (начинается с ‘l’ или ‘L’), или NPY_SEARCHRIGHT (начинается с ‘r’ или ‘R’).

intPyArray_OrderConverter(PyObject*obj, NPY_ORDER*order)

Преобразование Python-строк ‘C’, ‘F’, ‘A’, и ‘K’ в перечисление NPY_ORDER NPY_CORDER, NPY_FORTRANORDER, NPY_ANYORDER, и NPY_KEEPORDER.

intPyArray_CastingConverter(PyObject*obj, NPY_CASTING*casting)

Преобразовать строковые значения Python «no», «equiv», «safe», «same_kind», и «unsafe» в перечисление NPY_CASTING NPY_NO_CASTING, NPY_EQUIV_CASTING, NPY_SAFE_CASTING, NPY_SAME_KIND_CASTING и NPY_UNSAFE_CASTING.

intPyArray_ClipmodeConverter(PyObject*object, NPY_CLIPMODE*val)

Преобразовать строковые значения Python «clip», «wrap», и «raise» в перечисление NPY_CLIPMODE NPY_CLIP, NPY_WRAP и NPY_RAISE.

intPyArray_ConvertClipmodeSequence(PyObject*object, NPY_CLIPMODE*modes, intn)

Преобразует последовательность режимов обрезки или единственный режим обрезки в массив значений NPY_CLIPMODE. Число режимов обрезки n должно быть известно перед вызовом этой функции. Эта функция предназначена для поддержки функций, позволяющих задавать разные режимы обрезки для каждого измерения.

Другие преобразования

intPyArray_PyIntAsInt(PyObject*op)

Преобразует все типы объектов Python (включая массивы и массивоподобные скаляры) в стандартное целое число. В случае ошибки возвращается -1 и устанавливается исключение. Может оказаться полезной макрос:

#define error_converting(x) (((x) == -1) && PyErr_Occurred())

npy_intpPyArray_PyIntAsIntp(PyObject*op)

Преобразует все типы объектов Python (включая массивы и массивоподобные скаляры) в целое число размером указателя платформы. В случае ошибки возвращается -1 и устанавливается исключение.

intPyArray_IntpFromSequence(PyObject*seq, npy_intp*vals, intmaxvals)

Преобразует любую последовательность Python (или единственное число Python), переданную в качестве seq, в (до) maxvals целых чисел размера указателя и помещает их в массив vals. Последовательность может быть меньше, чем maxvals, а количество преобразованных объектов возвращается.

intPyArray_TypestrConvert(intitemsize, intgentype)

Преобразует символы типов (с itemsize) в базовые перечислимые типы данных. Признаются и преобразуются символы типов строк, соответствующие знаковым и беззнаковым целым числам, числам с плавающей запятой и комплексным числам с плавающей запятой. Другие значения gentype возвращаются без изменения. Эта функция может использоваться, например, для преобразования строки «f4» в NPY_FLOAT32.

Разное

Импорт API

Для использования C-API из другого модуля расширения необходимо вызвать функцию import_array. Если модуль расширения полностью содержится в одном файле .c, то этого достаточно. Однако, если модуль расширения включает в себя несколько файлов, где требуется C-API, необходимо выполнить дополнительные шаги.

voidimport_array(void)

Эта функция должна быть вызвана в секции инициализации модуля, который будет использовать C-API. Она импортирует модуль, где хранится таблица указателей функций, и устанавливает соответствующую переменную.

PY_ARRAY_UNIQUE_SYMBOL

NO_IMPORT_ARRAY

Используя эти определения, вы можете использовать C-API в нескольких файлах для одного модуля расширения. В каждом файле вы должны определить PY_ARRAY_UNIQUE_SYMBOL с каким-то именем, которое будет содержать C-API (например, myextension_ARRAY_API). Это необходимо сделать до включения файла numpy/arrayobject.h. В процедуре инициализации модуля вызывайте import_array. Кроме того, в файлах, не содержащих процедуру инициализации модуля, необходимо определить NO_IMPORT_ARRAY перед включением numpy/arrayobject.h.

Предположим, у меня есть два файла coolmodule.c и coolhelper.c, которые должны быть скомпилированы и объединены в один модуль расширения. Предположим, что coolmodule.c содержит необходимую функцию инициализации модуля initcool (с вызовом функции import_array()). Тогда coolmodule.c будет содержать вверху:

#define PY_ARRAY_UNIQUE_SYMBOL cool_ARRAY_API
#include numpy/arrayobject.h

С другой стороны, coolhelper.c будет содержать вверху:

#define NO_IMPORT_ARRAY
#define PY_ARRAY_UNIQUE_SYMBOL cool_ARRAY_API
#include numpy/arrayobject.h

Вы также можете поместить две последние строки в локальный заголовок расширения, при условии, что вы убедитесь в том, что NO_IMPORT_ARRAY определен до включения этого файла.

Внутренне эти определения работают следующим образом:

• Если ни то, ни другое не определено, C-API объявляется как static void**, поэтому он видимый только внутри единицы компиляции, которая включает numpy/arrayobject.h.
• Если PY_ARRAY_UNIQUE_SYMBOL определено, но NO_IMPORT_ARRAY нет, C-API объявляется как void**, чтобы он также был видим для других единиц компиляции.
• Если NO_IMPORT_ARRAY определено, независимо от того, определено ли PY_ARRAY_UNIQUE_SYMBOL, C-API объявляется как extern void**, поэтому ожидается, что он определен в другой единице компиляции.
• Всякий раз, когда PY_ARRAY_UNIQUE_SYMBOL определено, оно также изменяет имя переменной, содержащей C-API, которое по умолчанию равно PyArray_API, на то, что определено в макросе.

Проверка версии API

Поскольку расширения Python не используются так же, как обычные библиотеки на большинстве платформ, некоторые ошибки не могут быть автоматически обнаружены во время сборки или даже во время выполнения. Например, если вы создаете расширение, использующее функцию, доступную только для numpy >= 1.3.0, и вы импортируете расширение позднее с numpy 1.2, вы не получите ошибку импорта (но практически наверняка получите ошибку сегментации при вызове функции). Вот почему предоставляется несколько функций для проверки версий numpy. Макросы NPY_VERSION и NPY_FEATURE_VERSION соответствуют версии numpy, используемой для сборки расширения, тогда как версии, возвращаемые функциями PyArray_GetNDArrayCVersion и PyArray_GetNDArrayCFeatureVersion, соответствуют версии numpy во время выполнения.

Правила совместимости ABI и API можно сформулировать следующим образом:

• Всякий раз, когда NPY_VERSION != PyArray_GetNDArrayCVersion(), расширение необходимо перекомпилировать (несовместимость ABI).
• NPY_VERSION == PyArray_GetNDArrayCVersion() и NPY_FEATURE_VERSION <= PyArray_GetNDArrayCFeatureVersion() означает обратную совместимость изменений.

Несовместимость ABI автоматически обнаруживается в каждой версии numpy. Обнаружение несовместимости API было добавлено в numpy 1.4.0. Если вы хотите поддерживать множество различных версий numpy с одним бинарным расширением, необходимо скомпилировать расширение с наименьшим возможным значением NPY_FEATURE_VERSION.

NPY_VERSION

Текущая версия объекта ndarray (проверьте, определена ли эта переменная, чтобы гарантировать, что используется заголовок numpy/arrayobject.h).

NPY_FEATURE_VERSION

Текущая версия C-API.

unsigned intPyArray_GetNDArrayCVersion(void)

Просто возвращает значение NPY_VERSION. NPY_VERSION изменяется всякий раз, когда происходит обратная несовместимость на уровне ABI. Однако, поскольку она находится в C-API, сравнение результата этой функции со значением, определенным в текущем заголовке, позволяет проверить, изменился ли C-API, что требует перекомпиляции модулей расширения, использующих C-API. Это автоматически проверяется в функции import_array.

unsigned intPyArray_GetNDArrayCFeatureVersion(void)

Добавлено в версии 1.4.0.

Просто возвращает значение NPY_FEATURE_VERSION. NPY_FEATURE_VERSION изменяется при изменении API (например, добавлении функции). Измененное значение не всегда требует перекомпиляции.

Внутренняя гибкость

intPyArray_SetNumericOps(PyObject*dict)

NumPy хранит внутреннюю таблицу Python-вызываемых объектов, используемых для реализации арифметических операций для массивов, а также определенных методов вычисления массивов. Эта функция позволяет пользователю заменить любые или все эти Python-объекты своими версиями. Ключи словаря dict — это имена функций для замены, а соответствующие значения — Python-вызываемые объекты для использования. Следует быть осторожным, чтобы функция, используемая для замены внутренней операции массива, не вызывала обратную связь с этой внутренней операцией массива (если вы не разработали функцию для обработки этого), иначе может возникнуть неопределенная бесконечная рекурсия (что может привести к сбою программы). Имена ключей, которые представляют операции, которые могут быть заменены:

add, subtract, multiply, divide, remainder, power, square, reciprocal, ones_like, sqrt, negative, positive, absolute, invert, left_shift, right_shift, bitwise_and, bitwise_xor, bitwise_or, less, less_equal, equal, not_equal, greater, greater_equal, floor_divide, true_divide, logical_or, logical_and, floor, ceil, maximum, minimum, rint.

Эти функции включены здесь, потому что они используются по крайней мере один раз в методах объекта массива. Функция возвращает -1 (без установки ошибки Python), если один из объектов, которому присваивается значение, не является вызываемым.

Устарело начиная с версии 1.16.

PyObject*PyArray_GetNumericOps(void)

Возвращает Python-словарь, содержащий вызываемые Python-объекты, хранящиеся во внутренней таблице арифметических операций. Ключи этого словаря указаны в описании для PyArray_SetNumericOps.

Устарело начиная с версии 1.16.

voidPyArray_SetStringFunction(PyObject*op, intrepr)

Эта функция позволяет вам изменить методы tp_str и tp_repr объекта массива на любую Python-функцию. Таким образом, вы можете изменить то, что происходит для всех массивов, когда вызывается str(arr) или repr(arr) из Python. Функция, которая будет вызываться, передается как op. Если repr не равно нулю, то эта функция будет вызываться в ответ на repr(arr), в противном случае функция будет вызываться в ответ на str(arr). Проверка на то, является ли op вызываемым, не выполняется. Вызываемый объект, переданный в op, должен ожидать аргумент массива и должен возвращать строку для печати.

Управление памятью

char*PyDataMem_NEW(size_tnbytes)

voidPyDataMem_FREE(char*ptr)

char*PyDataMem_RENEW(void*ptr, size_tnewbytes)

Макросы для выделения, освобождения и перераспределения памяти. Эти макросы используются во внутренней работе для создания массивов.

npy_intp*PyDimMem_NEW(intnd)

voidPyDimMem_FREE(char*ptr)

npy_intp*PyDimMem_RENEW(void*ptr, size_tnewnd)

Макросы для выделения, освобождения и перераспределения памяти для размеров и шагов.

void*PyArray_malloc(size_tnbytes)

voidPyArray_free(void*ptr)

void*PyArray_realloc(npy_intp*ptr, size_tnbytes)

Эти макросы используют различные аллокаторы памяти в зависимости от константы NPY_USE_PYMEM. Системный аллокатор malloc используется, когда NPY_USE_PYMEM равен 0, если NPY_USE_PYMEM равен 1, тогда используется аллокатор памяти Python.

NPY_USE_PYMEM

intPyArray_ResolveWritebackIfCopy(PyArrayObject*obj)

Если у obj.flags есть NPY_ARRAY_WRITEBACKIFCOPY или (устаревшее) NPY_ARRAY_UPDATEIFCOPY, эта функция очищает флаги, DECREF значения obj->base и делает его доступным для записи, и устанавливает obj->base в NULL. Затем она копирует obj->data в obj->base->data, и возвращает состояние ошибки операции копирования. Это противоположность PyArray_SetWritebackIfCopyBase. Обычно это вызывается после завершения работы с obj, незадолго до Py_DECREF(obj). Может быть вызвано несколько раз или с NULL входом. См. также PyArray_DiscardWritebackIfCopy.

Возвращает 0, если ничего не было сделано, -1 при ошибке и 1, если действие было выполнено.

Поддержка потоков

Эти макросы имеют смысл только если NPY_ALLOW_THREADS принимает значение True во время компиляции модуля расширения. В противном случае эти макросы эквивалентны пробелам. Python использует единую глобальную блокировку интерпретатора (GIL) для каждого процесса Python, чтобы только один поток мог выполняться одновременно (даже на многоядерных машинах). При вызове компилированной функции, которая может занимать время для вычисления (и не имеет побочных эффектов для других потоков, таких как обновление глобальных переменных), GIL должен быть освобожден, чтобы другие потоки Python могли работать, пока выполняются длительные вычисления. Это можно сделать, используя две группы макросов. Как правило, если один макрос в группе используется в блоке кода, все они должны использоваться в том же блоке кода. В настоящее время NPY_ALLOW_THREADS определяется как python-определенная константа WITH_THREADS, за исключением случаев, когда переменная среды NPY_NOSMP установлена, в этом случае NPY_ALLOW_THREADS определяется как 0.

NPY_ALLOW_THREADS

WITH_THREADS

Группа 1

Эта группа используется для вызова кода, который может занимать некоторое время, но не использует вызовы Python C-API. Таким образом, GIL должен быть освобожден во время его вычисления.

NPY_BEGIN_ALLOW_THREADS

Эквивалентно Py_BEGIN_ALLOW_THREADS, за исключением того, что для определения того, заменяется ли макрос пробелом или нет, используется NPY_ALLOW_THREADS.

NPY_END_ALLOW_THREADS

Эквивалентно Py_END_ALLOW_THREADS, за исключением того, что для определения того, заменяется ли макрос пробелом или нет, используется NPY_ALLOW_THREADS.

NPY_BEGIN_THREADS_DEF

Размещается в области объявления переменных. Этот макрос подготавливает переменную для хранения состояния Python.

NPY_BEGIN_THREADS

Размещается непосредственно перед кодом, которому не нужен интерпретатор Python (без вызовов Python C-API). Этот макрос сохраняет состояние Python и освобождает GIL.

NPY_END_THREADS

Размещается непосредственно после кода, которому не нужен интерпретатор Python. Этот макрос приобретает GIL и восстанавливает состояние Python из сохранённой переменной.

voidNPY_BEGIN_THREADS_DESCR(PyArray_Descr*dtype)

Полезно для освобождения GIL только в том случае, если dtype не содержит произвольных объектов Python, которые могут потребовать интерпретатор Python во время выполнения цикла.

voidNPY_END_THREADS_DESCR(PyArray_Descr*dtype)

Полезно для получения GIL в ситуациях, когда он был освобожден с помощью формы BEGIN этого макроса.