API массивов

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

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

int PyArray_NDIM(PyArrayObject *arr)

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

int PyArray_FLAGS(PyArrayObject* arr)

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

int PyArray_TYPE(PyArrayObject* arr)

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

int PyArray_SETITEM(PyArrayObject* arr, void* itemptr, PyObject* obj)

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

void PyArray_ENABLEFLAGS(PyArrayObject* arr, int flags)

Введено в версии 1.7.

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

void PyArray_CLEARFLAGS(PyArrayObject* arr, int flags)

Введено в версии 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_intp PyArray_DIM(PyArrayObject* arr, int n)

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

npy_intp PyArray_STRIDE(PyArrayObject* arr, int n)

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

npy_intp PyArray_ITEMSIZE(PyArrayObject* arr)

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

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

npy_intp PyArray_SIZE(PyArrayObject* arr)

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

npy_intp PyArray_Size(PyArrayObject* obj)

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

npy_intp PyArray_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_intp i)

void* PyArray_GETPTR2(PyArrayObject* obj, npy_intp i, npy_intp j)

void* PyArray_GETPTR3(PyArrayObject* obj, npy_intp i, npy_intp j, npy_intp k)

void* PyArray_GETPTR4(PyArrayObject* obj, npy_intp i, npy_intp j, npy_intp k, npy_intp l)

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

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

Из исходного кода

PyObject* PyArray_NewFromDescr(PyTypeObject* subtype, PyArray_Descr* descr, int nd, npy_intp const* dims, npy_intp const* strides, void* data, int flags, 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 не равно NULL, то также можно указать strides. Если strides равно NULL, то шаги массива вычисляются как непрерывные в стиле C (по умолчанию) или непрерывные в стиле Fortran (flags отлично от нуля для data = NULL или flags & NPY_ARRAY_F_CONTIGUOUS отлично от нуля для не-NULL data). Любые указанные dims и strides копируются в новые выделенные массивы измерений и шагов для нового объекта массива.

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

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

PyObject* PyArray_NewLikeArray(PyArrayObject* prototype, NPY_ORDER order, PyArray_Descr* descr, int subok)

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

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

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

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

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

PyObject* PyArray_New(PyTypeObject* subtype, int nd, npy_intp const* dims, int type_num, npy_intp const* strides, void* data, int itemsize, int flags, PyObject* obj)

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

PyObject* PyArray_SimpleNew(int nd, npy_intp const* dims, int typenum)

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

PyObject* PyArray_SimpleNewFromData(int nd, npy_intp const* dims, int typenum, void* data)

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

PyObject* PyArray_SimpleNewFromDescr(int nd, npy_int const* dims, PyArray_Descr* descr)

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

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

void PyArray_FILLWBYTE(PyObject* obj, int val)

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

PyObject* PyArray_Zeros(int nd, npy_intp const* dims, PyArray_Descr* dtype, int fortran)

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

PyObject* PyArray_ZEROS(int nd, npy_intp const* dims, int type_num, int fortran)

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

PyObject* PyArray_Empty(int nd, npy_intp const* dims, PyArray_Descr* dtype, int fortran)

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

PyObject* PyArray_EMPTY(int nd, npy_intp const* dims, int typenum, int fortran)

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

PyObject* PyArray_Arange(double start, double stop, double step, int typenum)

Создаёт новый одномерный массив типа 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 ).

int PyArray_SetBaseObject(PyArrayObject* arr, PyObject* obj)

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

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

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

Возвращаемое значение равно 0 при успехе и -1 при ошибке.

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

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

PyObject* PyArray_FromAny(PyObject* op, PyArray_Descr* dtype, int min_depth, int max_depth, int requirements, 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

int PyArray_GetArrayParamsFromObject(PyObject* op, PyArray_Descr* requested_dtype, npy_bool writeable, 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, int min_depth, int max_depth, int requirements, PyObject* context)

Практически идентична функции PyArray_FromAny (…) за исключением того, что требования могут содержать 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, int requirements)

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

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, int typenum, int min_depth, int max_depth)

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

PyObject* PyArray_ContiguousFromObject(PyObject* op, int typenum, int min_depth, int max_depth)

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

PyObject* PyArray_FromObject(PyObject* op, int typenum, int min_depth, int max_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_intp slen, PyArray_Descr* dtype, npy_intp num, char* sep)

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

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

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

PyObject* PyArray_FromBuffer(PyObject* buf, PyArray_Descr* dtype, npy_intp count, npy_intp offset)

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

int PyArray_CopyInto(PyArrayObject* dest, PyArrayObject* src)

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

int PyArray_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, int requirements)

Аналогично PyArray_FROM_O, но может принимать аргумент требований, указывающий свойства, которые должен иметь результирующий массив. Доступные требования, которые могут быть применены, это 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, int typenum)

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

PyObject* PyArray_FROM_OTF(PyObject* obj, int typenum, int requirements)

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

PyObject* PyArray_FROMANY(PyObject* obj, int typenum, int min, int max, int requirements)

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

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

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

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

Общая проверка типа Python

int PyArray_Check(PyObject *op)

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

int PyArray_CheckExact(PyObject *op)

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

int PyArray_HasArrayInterface(PyObject *op, PyObject *out)

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

int PyArray_HasArrayInterfaceType(PyObject *op, PyArray_Descr *dtype, PyObject *context, PyObject *out)

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

int PyArray_IsZeroDim(PyObject *op)

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

PyArray_IsScalar(op, cls)

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

int PyArray_CheckScalar(PyObject *op)

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

int PyArray_IsPythonNumber(PyObject *op)

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

int PyArray_IsPythonScalar(PyObject *op)

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

int PyArray_IsAnyScalar(PyObject *op)

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

int PyArray_CheckAnyScalar(PyObject *op)

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

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

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

int PyTypeNum_ISUNSIGNED(int num)

int PyDataType_ISUNSIGNED(PyArray_Descr *descr)

int PyArray_ISUNSIGNED(PyArrayObject *obj)

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

int PyTypeNum_ISSIGNED(int num)

int PyDataType_ISSIGNED(PyArray_Descr *descr)

int PyArray_ISSIGNED(PyArrayObject *obj)

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

int PyTypeNum_ISINTEGER(int num)

int PyDataType_ISINTEGER(PyArray_Descr* descr)

int PyArray_ISINTEGER(PyArrayObject *obj)

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

int PyTypeNum_ISFLOAT(int num)

int PyDataType_ISFLOAT(PyArray_Descr* descr)

int PyArray_ISFLOAT(PyArrayObject *obj)

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

int PyTypeNum_ISCOMPLEX(int num)

int PyDataType_ISCOMPLEX(PyArray_Descr* descr)

int PyArray_ISCOMPLEX(PyArrayObject *obj)

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

int PyTypeNum_ISNUMBER(int num)

int PyDataType_ISNUMBER(PyArray_Descr* descr)

int PyArray_ISNUMBER(PyArrayObject *obj)

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

int PyTypeNum_ISSTRING(int num)

int PyDataType_ISSTRING(PyArray_Descr* descr)

int PyArray_ISSTRING(PyArrayObject *obj)

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

int PyTypeNum_ISPYTHON(int num)

int PyDataType_ISPYTHON(PyArray_Descr* descr)

int PyArray_ISPYTHON(PyArrayObject *obj)

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

int PyTypeNum_ISFLEXIBLE(int num)

int PyDataType_ISFLEXIBLE(PyArray_Descr* descr)

int PyArray_ISFLEXIBLE(PyArrayObject *obj)

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

int PyDataType_ISUNSIZED(PyArray_Descr* descr)

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

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

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

int PyTypeNum_ISUSERDEF(int num)

int PyDataType_ISUSERDEF(PyArray_Descr* descr)

int PyArray_ISUSERDEF(PyArrayObject *obj)

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

int PyTypeNum_ISEXTENDED(int num)

int PyDataType_ISEXTENDED(PyArray_Descr* descr)

int PyArray_ISEXTENDED(PyArrayObject *obj)

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

int PyTypeNum_ISOBJECT(int num)

int PyDataType_ISOBJECT(PyArray_Descr* descr)

int PyArray_ISOBJECT(PyArrayObject *obj)

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

int PyTypeNum_ISBOOL(int num)

int PyDataType_ISBOOL(PyArray_Descr* descr)

int PyArray_ISBOOL(PyArrayObject *obj)

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

int PyDataType_HASFIELDS(PyArray_Descr* descr)

int PyArray_HASFIELDS(PyArrayObject *obj)

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

int PyArray_ISNOTSWAPPED(PyArrayObject *m)

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

int PyArray_ISBYTESWAPPED(PyArrayObject *m)

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

npy_bool PyArray_EquivTypes(PyArray_Descr* type1, PyArray_Descr* type2)

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

npy_bool PyArray_EquivArrTypes(PyArrayObject* a1, PyArrayObject * a2)

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

npy_bool PyArray_EquivTypenums(int typenum1, int typenum2)

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

int PyArray_EquivByteorders(int b1, int b2)

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

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

PyObject* PyArray_Cast(PyArrayObject* arr, int typenum)

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

PyObject* PyArray_CastToType(PyArrayObject* arr, PyArray_Descr* type, int fortran)

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

int PyArray_CastTo(PyArrayObject* out, PyArrayObject* in)

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

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

PyArray_VectorUnaryFunc* PyArray_GetCastFunc(PyArray_Descr* from, int totype)

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

int PyArray_CanCastSafely(int fromtype, int totype)

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

int PyArray_CanCastTo(PyArray_Descr* fromtype, PyArray_Descr* totype)

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

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

int PyArray_CanCastTypeTo(PyArray_Descr* fromtype, PyArray_Descr* totype, NPY_CASTING casting)

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

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

int PyArray_CanCastArrayTo(PyArrayObject* arr, PyArray_Descr* totype, NPY_CASTING casting)

Добавлена в версии 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_intp narrs, PyArrayObject **arrs, npy_intp ndtypes, PyArray_Descr **dtypes)

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

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

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

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

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

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

int PyArray_ObjectType(PyObject* op, int mintype)

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

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

void PyArray_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 ‘d, иначе произойдёт утечка памяти. Пример шаблона кода ниже демонстрирует типичное использование:

Изменено в версии 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), когда он больше не нужен.

int PyArray_ValidType(int typenum)

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

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

void PyArray_InitArrFuncs(PyArray_ArrFuncs* f)

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

int PyArray_RegisterDataType(PyArray_Descr* dtype)

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

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

int PyArray_RegisterCastFunc(PyArray_Descr* descr, int totype, PyArray_VectorUnaryFunc* castfunc)

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

int PyArray_RegisterCanCast(PyArray_Descr* descr, int totype, NPY_SCALARKIND scalar)

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

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

int PyArray_INCREF(PyArrayObject* op)

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

void PyArray_Item_INCREF(char* ptr, PyArray_Descr* dtype)

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

int PyArray_XDECREF(PyArrayObject* op)

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

void PyArray_Item_XDECREF(char* ptr, PyArray_Descr* dtype)

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

void PyArray_FillObjectArray(PyArrayObject* arr, PyObject* obj)

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

int PyArray_SetUpdateIfCopyBase(PyArrayObject* arr, PyArrayObject* base)

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

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

int PyArray_SetWritebackIfCopyBase(PyArrayObject* arr, PyArrayObject* base)

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

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

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

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

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

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

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

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

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

NPY_ARRAY_C_CONTIGUOUS

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

NPY_ARRAY_F_CONTIGUOUS

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

NPY_ARRAY_OWNDATA

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

NPY_ARRAY_ALIGNED

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

NPY_ARRAY_WRITEABLE

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

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

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.

int PyArray_CHKFLAGS(PyObject *arr, int flags)

Первый параметр, 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.

int PyArray_IS_C_CONTIGUOUS(PyObject *arr)

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

int PyArray_IS_F_CONTIGUOUS(PyObject *arr)

Определяет, является ли arr непрерывным в стиле Fortran.

int PyArray_ISFORTRAN(PyObject *arr)

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

int PyArray_ISWRITEABLE(PyObject *arr)

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

int PyArray_ISALIGNED(PyObject *arr)

Определяет, правильно ли выровнена область данных arr на компьютере.

int PyArray_ISBEHAVED(PyObject *arr)

Определяет, выровнена ли область данных arr, разрешена ли запись в неё и соответствует ли порядок байтов машинного порядка согласно её описателю.

int PyArray_ISBEHAVED_RO(PyObject *arr)

Определяет, выровнена ли область данных arr и соответствует ли порядок байтов машинного порядка.

int PyArray_ISCARRAY(PyObject *arr)

Определяет, является ли область данных arr непрерывной в стиле C и PyArray_ISBEHAVED (arr) равно true.

int PyArray_ISFARRAY(PyObject *arr)

Определяет, является ли область данных arr непрерывной в стиле Fortran и PyArray_ISBEHAVED (arr) равно true.

int PyArray_ISCARRAY_RO(PyObject *arr)

Определяет, является ли область данных arr непрерывной в стиле C, выровненной и соответствует ли порядок байтов машинного порядка.

int PyArray_ISFARRAY_RO(PyObject *arr)

Определяет, является ли область данных arr непрерывной в стиле Fortran, выровненной и соответствует ли порядок байтов машинного порядка.

int PyArray_ISONESEGMENT(PyObject *arr)

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

void PyArray_UpdateFlags(PyArrayObject* arr, int flagmask)

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

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

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

PyObject* PyArray_GetField(PyArrayObject* self, PyArray_Descr* dtype, int offset)

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

int PyArray_SetField(PyArrayObject* self, PyArray_Descr* dtype, int offset, PyObject* val)

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

PyObject* PyArray_Byteswap(PyArrayObject* self, npy_bool inplace)

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

PyObject* PyArray_NewCopy(PyArrayObject* old, NPY_ORDER order)

Эквивалентно 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_ORDER order)

Эквивалентно 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, показывающая, как должны быть записаны элементы.

int PyArray_Dump(PyObject* self, PyObject* file, int protocol)

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

PyObject* PyArray_Dumps(PyObject* self, int protocol)

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

int PyArray_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_ORDER order)

Результат — новый массив (ссылающийся на ту же область памяти, что и 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, int a1, int a2)

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

PyObject* PyArray_Resize(PyArrayObject* self, PyArray_Dims* newshape, int refcheck, NPY_ORDER fortran)

Эквивалентно 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 форма , а permute .ptr — (0,2,1), то форма результата Если permute NULL, то форма результата

PyObject* PyArray_Flatten(PyArrayObject* self, NPY_ORDER order)

Эквивалентно 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_ORDER order)

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

Выбор и обработка элементов

PyObject* PyArray_TakeFrom(PyArrayObject* self, PyObject* indices, int axis, PyArrayObject* ret, NPY_CLIPMODE clipmode)

Эквивалентно 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_CLIPMODE clipmode)

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

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

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

PyObject* PyArray_Repeat(PyArrayObject* self, PyObject* op, int axis)

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

PyObject* PyArray_Choose(PyArrayObject* self, PyObject* op, PyArrayObject* ret, NPY_CLIPMODE clipmode)

Эквивалентно 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, int axis, NPY_SORTKIND kind)

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

PyObject* PyArray_ArgSort(PyArrayObject* self, int axis)

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

PyObject* PyArray_LexSort(PyObject* sort_keys, int axis)

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

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

PyObject* PyArray_SearchSorted(PyArrayObject* self, PyObject* values, NPY_SEARCHSIDE side, PyObject* perm)

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

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

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

int PyArray_Partition(PyArrayObject *self, PyArrayObject * ktharray, int axis, NPY_SELECTKIND which)

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

PyObject* PyArray_ArgPartition(PyArrayObject *op, PyArrayObject * ktharray, int axis, NPY_SELECTKIND which)

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

PyObject* PyArray_Diagonal(PyArrayObject* self, int offset, int axis1, int axis2)

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

npy_intp PyArray_CountNonzero(PyArrayObject* self)

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

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

PyObject* PyArray_Nonzero(PyArrayObject* self)

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

PyObject* PyArray_Compress(PyArrayObject* self, PyObject* condition, int axis, PyArrayObject* out)

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

Вычисление

PyObject* PyArray_ArgMax(PyArrayObject* self, int axis, PyArrayObject* out)

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

PyObject* PyArray_ArgMin(PyArrayObject* self, int axis, PyArrayObject* out)

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

PyObject* PyArray_Max(PyArrayObject* self, int axis, PyArrayObject* out)

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

PyObject* PyArray_Min(PyArrayObject* self, int axis, PyArrayObject* out)

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

PyObject* PyArray_Ptp(PyArrayObject* self, int axis, PyArrayObject* out)

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

PyObject* PyArray_Mean(PyArrayObject* self, int axis, int rtype, PyArrayObject* out)

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

PyObject* PyArray_Trace(PyArrayObject* self, int offset, int axis1, int axis2, int rtype, PyArrayObject* out)

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

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, int decimals, PyArrayObject* out)

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

PyObject* PyArray_Std(PyArrayObject* self, int axis, int rtype, PyArrayObject* out)

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

PyObject* PyArray_Sum(PyArrayObject* self, int axis, int rtype, PyArrayObject* out)

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

PyObject* PyArray_CumSum(PyArrayObject* self, int axis, int rtype, PyArrayObject* out)

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

PyObject* PyArray_Prod(PyArrayObject* self, int axis, int rtype, PyArrayObject* out)

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

PyObject* PyArray_CumProd(PyArrayObject* self, int axis, int rtype, PyArrayObject* out)

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

PyObject* PyArray_All(PyArrayObject* self, int axis, PyArrayObject* out)

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

PyObject* PyArray_Any(PyArrayObject* self, int axis, PyArrayObject* out)

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

Функции

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

int PyArray_AsCArray(PyObject** op, void* ptr, npy_intp* dims, int nd, int typenum, int itemsize)

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

Параметры

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

int PyArray_Free(PyObject* op, void* ptr)

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

PyObject* PyArray_Concatenate(PyObject* obj, int axis)

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

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

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

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

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

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

New in version 1.6.

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

PyObject* PyArray_EinsteinSum(char* subscripts, npy_intp nop, PyArrayObject** op_in, PyArray_Descr* dtype, NPY_ORDER order, NPY_CASTING casting, PyArrayObject* out)

New in version 1.6.

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

См. функцию einsum для получения дополнительной информации.

PyObject* PyArray_CopyAndTranspose(PyObject * op)

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

PyObject* PyArray_Correlate(PyObject* op1, PyObject* op2, int mode)

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

Примечания

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

PyObject* PyArray_Correlate2(PyObject* op1, PyObject* op2, int mode)

Обновлённая версия PyArray_Correlate, которая использует обычное определение корреляции для 1-мерных массивов. Корреляция вычисляется в каждой точке вывода путём умножения 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_bool PyArray_CheckStrides(int elsize, int nd, npy_intp numbytes, npy_intp const* dims, npy_intp const* newstrides)

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

npy_intp PyArray_MultiplyList(npy_intp const* seq, int n)

int PyArray_MultiplyIntList(int const* seq, int n)

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

int PyArray_CompareLists(npy_intp const* l1, npy_intp const* l2, int n)

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

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

NpyAuxData

При работе с более сложными типами данных (dtypes), которые состоят из других типов данных, таких как тип 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;
}

NpyAuxData_FreeFunc

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

NpyAuxData_CloneFunc

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

void NPY_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. Этот итератор можно использовать для написания чего-то подобного тому, что делают ufuncs, где цикл по наибольшей оси выполняется отдельной подпрограммой. Если *axis отрицателен, то *axis будет установлен на ось с наименьшим шагом, и эта ось будет использована.

PyObject *PyArray_BroadcastToShape(PyObject* arr, npy_intp const *dimensions, int nd)

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

int PyArrayIter_Check(PyObject* op)

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

void PyArray_ITER_RESET(PyObject* iterator)

Сбрасывает iterator к началу массива.

void PyArray_ITER_NEXT(PyObject* iterator)

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

void *PyArray_ITER_DATA(PyObject* iterator)

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

void PyArray_ITER_GOTO(PyObject* iterator, npy_intp* destination)

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

void PyArray_ITER_GOTO1D(PyObject* iterator, npy_intp index)

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

int PyArray_ITER_NOTDONE(PyObject* iterator)

Возвращает TRUE, пока итератор не пройдёт по всем элементам; в противном случае возвращает FALSE.

Трансляция (многоитераторы)

PyObject* PyArray_MultiIterNew(int num, ...)

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

void PyArray_MultiIter_RESET(PyObject* multi)

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

void PyArray_MultiIter_NEXT(PyObject* multi)

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

void *PyArray_MultiIter_DATA(PyObject* multi, int i)

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

void PyArray_MultiIter_NEXTi(PyObject* multi, int i)

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

void PyArray_MultiIter_GOTO(PyObject* multi, npy_intp* destination)

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

void PyArray_MultiIter_GOTO1D(PyObject* multi, npy_intp index)

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

int PyArray_MultiIter_NOTDONE(PyObject* multi)

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

int PyArray_Broadcast(PyArrayMultiIterObject* mit)

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

int PyArray_RemoveSmallest(PyArrayMultiIterObject* mit)

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

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

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

PyObject* PyArray_NeighborhoodIterNew(PyArrayIterObject* iter, npy_intp bounds, int mode, PyArrayObject* fill_value)

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

Аргумент 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);
}

int PyArrayNeighborhoodIter_Reset(PyArrayNeighborhoodIterObject* iter)

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

int PyArrayNeighborhoodIter_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.

void PyArray_ScalarAsCtype(PyObject* scalar, void* ctypeptr)

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

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

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

PyObject* PyArray_TypeObjectFromType(int type)

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

NPY_SCALARKIND PyArray_ScalarKind(int typenum, PyArrayObject** arr)

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

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

int PyArray_CanCoerceScalar(char thistype, char neededtype, NPY_SCALARKIND scalar)

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

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

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

int PyArray_DescrCheck(PyObject* obj)

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

PyArray_Descr* PyArray_DescrNew(PyArray_Descr* obj)

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

PyArray_Descr* PyArray_DescrNewFromType(int typenum)

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

PyArray_Descr* PyArray_DescrNewByteorder(PyArray_Descr* obj, char newendian)

Создаёт новый объект типа данных с порядком байтов, заданным 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(int typenum)

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

int PyArray_DescrConverter(PyObject* obj, PyArray_Descr** dtype)

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

int PyArray_DescrConverter2(PyObject* obj, PyArray_Descr** dtype)

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

int Pyarray_DescrAlignConverter(PyObject* obj, PyArray_Descr** dtype)

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

int Pyarray_DescrAlignConverter2(PyObject* obj, PyArray_Descr** dtype)

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

PyObject *PyArray_FieldNames(PyObject* dict)

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

Справочные материалы по преобразованию

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

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

int PyArray_Converter(PyObject* obj, PyObject** address)

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

int PyArray_OutputConverter(PyObject* obj, PyArrayObject** address)

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

int PyArray_IntpConverter(PyObject* obj, PyArray_Dims* seq)

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

int PyArray_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 имеет интерфейс записываемого буфера.

int PyArray_AxisConverter(PyObject* obj, int* axis)

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

int PyArray_BoolConverter(PyObject* obj, npy_bool* value)

Преобразовать любой объект Python, obj, в NPY_TRUE или NPY_FALSE и поместить результат в value.

int PyArray_ByteorderConverter(PyObject* obj, char* endian)

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

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

int PyArray_SearchsideConverter(PyObject* obj, NPY_SEARCHSIDE* side)

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

int PyArray_OrderConverter(PyObject* obj, NPY_ORDER* order)

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

int PyArray_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.

int PyArray_ClipmodeConverter(PyObject* object, NPY_CLIPMODE* val)

Преобразуйте Python-строки ‘clip’, ‘wrap’, и ‘raise’ в перечисление NPY_CLIPMODE NPY_CLIP, NPY_WRAP и NPY_RAISE.

int PyArray_ConvertClipmodeSequence(PyObject* object, NPY_CLIPMODE* modes, int n)

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

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

int PyArray_PyIntAsInt(PyObject* op)

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

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

npy_intp PyArray_PyIntAsIntp(PyObject* op)

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

int PyArray_IntpFromSequence(PyObject* seq, npy_intp* vals, int maxvals)

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

int PyArray_TypestrConvert(int itemsize, int gentype)

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

Разное

Импорт API

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

void import_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 int PyArray_GetNDArrayCVersion(void)

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

unsigned int PyArray_GetNDArrayCFeatureVersion(void)

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

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

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

int PyArray_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.

void PyArray_SetStringFunction(PyObject* op, int repr)

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

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

char* PyDataMem_NEW(size_t nbytes)

void PyDataMem_FREE(char* ptr)

char* PyDataMem_RENEW(void * ptr, size_t newbytes)

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

npy_intp* PyDimMem_NEW(int nd)

void PyDimMem_FREE(char* ptr)

npy_intp* PyDimMem_RENEW(void* ptr, size_t newnd)

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

void* PyArray_malloc(size_t nbytes)

void PyArray_free(void* ptr)

void* PyArray_realloc(npy_intp* ptr, size_t nbytes)

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

NPY_USE_PYMEM

int PyArray_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 из сохранённой переменной.

void NPY_BEGIN_THREADS_DESCR(PyArray_Descr *dtype)

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

void NPY_END_THREADS_DESCR(PyArray_Descr *dtype)

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

void NPY_BEGIN_THREADS_THRESHOLDED(int loop_size)

Полезно для освобождения GIL только в том случае, если loop_size превышает минимальный порог, в настоящее время установленный в 500. Должен быть сопоставлен с NPY_END_THREADS для повторного получения GIL.

Группа 2

Эта группа используется для повторного получения GIL после его освобождения. Например, предположим, что GIL был освобождён (с помощью предыдущих вызовов), а затем какой-либо путь в коде (возможно, в другой подпрограмме) требует использования Python C-API, то эти макросы полезны для получения GIL. Эти макросы фактически выполняют обратный процесс предыдущих трёх (получают LOCK, сохраняя его состояние) и затем снова его освобождают сохранённым состоянием.

NPY_ALLOW_C_API_DEF

Поместить в область объявления переменных, чтобы настроить необходимую переменную.

NPY_ALLOW_C_API

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

NPY_DISABLE_C_API

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

Приоритет

NPY_PRIORITY

По умолчанию приоритет для массивов.

NPY_SUBTYPE_PRIORITY

По умолчанию приоритет подтипа.

NPY_SCALAR_PRIORITY

По умолчанию приоритет скаляра (очень маленький)

double PyArray_GetPriority(PyObject* obj, double def)

Возвращает атрибут __array_priority__ (преобразованный в double) объекта obj или def, если атрибут с таким именем не существует. Предоставляются быстрые возвраты, которые избегают поиска атрибута для объектов типа PyArray_Type.

Буферы по умолчанию

NPY_BUFSIZE

Размер буферов по умолчанию для пользовательских настроек внутренних буферов.

NPY_MIN_BUFSIZE

Минимальный размер пользовательских внутренних буферов.

NPY_MAX_BUFSIZE

Максимальный разрешенный размер пользовательских буферов.

Другие константы

NPY_NUM_FLOATTYPE

Количество типов с плавающей точкой

NPY_MAXDIMS

Максимальное количество измерений, разрешенных в массивах.

NPY_MAXARGS

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

NPY_FALSE

Определено как 0 для использования с Bool.

NPY_TRUE

Определено как 1 для использования с Bool.

NPY_FAIL

Значение возврата неудачных функций преобразования, которые вызываются с синтаксисом «O&» в функциях типа PyArg_ParseTuple.

NPY_SUCCEED

Значение возврата успешных функций преобразования, которые вызываются с синтаксисом «O&» в функциях типа PyArg_ParseTuple.

Разные макросы

int PyArray_SAMESHAPE(PyArrayObject *a1, PyArrayObject *a2)

Оценивается как True, если массивы a1 и a2 имеют одинаковую форму.

a

b

PyArray_MAX(a, b)

Возвращает максимальное значение из a и b. Если (a) или (b) являются выражениями, они вычисляются дважды.

PyArray_MIN(a, b)

Возвращает минимальное значение из a и b. Если (a) или (b) являются выражениями, они вычисляются дважды.

PyArray_CLT(a, b)

PyArray_CGT(a, b)

PyArray_CLE(a, b)

PyArray_CGE(a, b)

PyArray_CEQ(a, b)

PyArray_CNE(a, b)

Реализует комплексные сравнения между двумя комплексными числами (структуры с членами real и imag) с использованием определения NumPy порядка, которое является лексикографическим: сначала сравниваются вещественные части, а затем мнимые части, если вещественные части равны.

npy_intp PyArray_REFCOUNT(PyObject* op)

Возвращает счётчик ссылок любого объекта Python.

void PyArray_DiscardWritebackIfCopy(PyObject* obj)

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

void PyArray_XDECREF_ERR(PyObject* obj)

Устарело в 1.14, используйте PyArray_DiscardWritebackIfCopy за которым следует Py_XDECREF

DECREF объекта массива, у которого может быть установлен (устаревший) флаг NPY_ARRAY_UPDATEIFCOPY или NPY_ARRAY_WRITEBACKIFCOPY, без копирования содержимого обратно в исходный массив. Сбрасывает флаг NPY_ARRAY_WRITEABLE в базовом объекте. Это полезно для восстановления из ситуации ошибки, когда используются семантика записи назад, но приведёт к неверным результатам.

Перечисленные типы

NPY_SORTKIND

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

NPY_QUICKSORT

NPY_HEAPSORT

NPY_MERGESORT

NPY_STABLESORT

Используется как псевдоним NPY_MERGESORT и наоборот.

NPY_NSORTS

Определено как количество сортировок. Фиксируется на три из-за необходимости обратной совместимости, и поэтому NPY_MERGESORT и NPY_STABLESORT являются псевдонимами друг друга и могут ссылаться на один из нескольких устойчивых алгоритмов сортировки в зависимости от типа данных.

NPY_SCALARKIND

Особый тип переменной, указывающий количество «видов» скаляров, используемых для определения правил приведения скаляров. Эта переменная может принимать значения:

NPY_NOSCALAR

NPY_BOOL_SCALAR

NPY_INTPOS_SCALAR

NPY_INTNEG_SCALAR

NPY_FLOAT_SCALAR

NPY_COMPLEX_SCALAR

NPY_OBJECT_SCALAR

NPY_NSCALARKINDS

Определено как количество видов скаляров (без учета NPY_NOSCALAR).

NPY_ORDER

Тип перечисления, указывающий порядок элементов, в котором следует интерпретировать массив. При создании нового массива, обычно используются только NPY_CORDER и NPY_FORTRANORDER, в то время как при предоставлении одного или нескольких входных данных, порядок может быть основан на них.

NPY_ANYORDER

Порядок Fortran, если все входные данные в формате Fortran, в противном случае C.

NPY_CORDER

Порядок C.

NPY_FORTRANORDER

Порядок Fortran.

NPY_KEEPORDER

Порядок, максимально приближенный к порядку входных данных, даже если входной порядок не является ни C, ни Fortran.

NPY_CLIPMODE

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

NPY_RAISE

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

NPY_CLIP

Обрезает индекс до допустимого диапазона, если он находится вне границ.

NPY_WRAP

Оборачивает индекс до допустимого диапазона, если он находится вне границ.

NPY_SEARCHSIDE

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

NPY_SEARCHLEFT

NPY_SEARCHRIGHT

NPY_SELECTKIND

Тип переменной, указывающий используемый алгоритм выбора.

NPY_INTROSELECT

NPY_CASTING

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

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

NPY_NO_CASTING

Разрешены только идентичные типы.

NPY_EQUIV_CASTING

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

NPY_SAFE_CASTING

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

NPY_SAME_KIND_CASTING

Разрешены любые безопасные преобразования и преобразования между типами одного и того же рода. Например, float64 -> float32 разрешено по этому правилу.

NPY_UNSAFE_CASTING

Разрешено любое преобразование, независимо от типа потери данных.