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 и помещает его в массив NumPy 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-объект встроенного типа из массива NumPy arr по адресу, указанному в itemptr. Возвращает NULL при ошибке.

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

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

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

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

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

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)

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

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

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

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

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

Кроме того, если data не нулевой указатель, то можно также предоставить strides. Если strides — NULL, то шаги массива вычисляются как непрерывные в стиле C (по умолчанию) или непрерывные в стиле Fortran (flags не равно нулю для data = NULL или flags & NPY_ARRAY_F_CONTIGUOUS не равно нулю для non-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.

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 для любого из параметров глубины приводит к игнорированию параметра. Любые из следующих флагов массива могут быть добавлены (например, с помощью |), чтобы получить аргумент requirements. Если ваш код может обрабатывать общие (например, ступенчатые, с изменённым порядком байтов или невыровненные массивы), то requirements может быть 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 аргумента type, установленным на typenum.

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

PyObject* PyArray_FROM_OT(PyObject* obj, 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

PyArray_Check(PyObject *op)

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

PyArray_CheckExact(PyObject *op)

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

PyArray_HasArrayInterface(PyObject *op, PyObject *out)

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

PyArray_HasArrayInterfaceType(op, dtype, context, out)

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

PyArray_IsZeroDim(op)

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

PyArray_IsScalar(op, cls)

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

PyArray_CheckScalar(op)

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

PyArray_IsPythonNumber(op)

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

PyArray_IsPythonScalar(op)

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

PyArray_IsAnyScalar(op)

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

PyArray_CheckAnyScalar(op)

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

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

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

PyTypeNum_ISUNSIGNED(int num)

PyDataType_ISUNSIGNED(PyArray_Descr *descr)

PyArray_ISUNSIGNED(PyArrayObject *obj)

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

PyTypeNum_ISSIGNED(int num)

PyDataType_ISSIGNED(PyArray_Descr *descr)

PyArray_ISSIGNED(PyArrayObject *obj)

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

PyTypeNum_ISINTEGER(int num)

PyDataType_ISINTEGER(PyArray_Descr* descr)

PyArray_ISINTEGER(PyArrayObject *obj)

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

PyTypeNum_ISFLOAT(int num)

PyDataType_ISFLOAT(PyArray_Descr* descr)

PyArray_ISFLOAT(PyArrayObject *obj)

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

PyTypeNum_ISCOMPLEX(int num)

PyDataType_ISCOMPLEX(PyArray_Descr* descr)

PyArray_ISCOMPLEX(PyArrayObject *obj)

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

PyTypeNum_ISNUMBER(int num)

PyDataType_ISNUMBER(PyArray_Descr* descr)

PyArray_ISNUMBER(PyArrayObject *obj)

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

PyTypeNum_ISSTRING(int num)

PyDataType_ISSTRING(PyArray_Descr* descr)

PyArray_ISSTRING(PyArrayObject *obj)

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

PyTypeNum_ISPYTHON(int num)

PyDataType_ISPYTHON(PyArray_Descr* descr)

PyArray_ISPYTHON(PyArrayObject *obj)

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

PyTypeNum_ISFLEXIBLE(int num)

PyDataType_ISFLEXIBLE(PyArray_Descr* descr)

PyArray_ISFLEXIBLE(PyArrayObject *obj)

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

PyDataType_ISUNSIZED(PyArray_Descr* descr):

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

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

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

PyTypeNum_ISUSERDEF(int num)

PyDataType_ISUSERDEF(PyArray_Descr* descr)

PyArray_ISUSERDEF(PyArrayObject *obj)

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

PyTypeNum_ISEXTENDED(int num)

PyDataType_ISEXTENDED(PyArray_Descr* descr)

PyArray_ISEXTENDED(PyArrayObject *obj)

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

PyTypeNum_ISOBJECT(int num)

PyDataType_ISOBJECT(PyArray_Descr* descr)

PyArray_ISOBJECT(PyArrayObject *obj)

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

PyTypeNum_ISBOOL(int num)

PyDataType_ISBOOL(PyArray_Descr* descr)

PyArray_ISBOOL(PyArrayObject *obj)

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

PyDataType_HASFIELDS(PyArray_Descr* descr)

PyArray_HASFIELDS(PyArrayObject *obj)

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

PyArray_ISNOTSWAPPED(m)

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

PyArray_ISBYTESWAPPED(m)

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

Bool PyArray_EquivTypes(PyArray_Descr* type1, PyArray_Descr* type2)

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

Bool PyArray_EquivArrTypes(PyArrayObject* a1, PyArrayObject * a2)

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

Bool PyArray_EquivTypenums(int typenum1, int typenum2)

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

int PyArray_EquivByteorders({byteorder} b1, {byteorder} b2)

Истинно, если символы порядка байтов ( 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-битные числа с плавающей точкой, даже если это может привести к потере точности для больших целых чисел, чтобы не распространять использование длинной двойной точности без явных запросов. Гибкие типы массивов не проверяются по их длинам с помощью этой функции.

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

PyArray_Descr* PyArray_ResultType(npy_intp narrs, PyArrayObject**arrs, npy_intp ndtypes, PyArray_Descr**dtypes)

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

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

Категории определяются путём проверки, являются ли максимальным типом всех массивов и скаляров булевы, целые (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.

Эта функция полезна для определения общего типа, в который можно преобразовать два или более массивов. Она работает только для негибких типов массивов, так как не передаётся информация о размере элемента. Аргумент mintype представляет собой минимально допустимый тип, а op представляет собой объект, который будет преобразован в массив. Значение возврата — это перечисление typenumber, которое представляет тип данных, которым 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 , иначе произойдёт утечка памяти. Приведённый ниже пример демонстрирует типовое использование:

Изменено в версии 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. Используйте 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_DECREF (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, что требует этих флагов. Если вы получаете произвольный PyArrayObject в коде C, вам необходимо учитывать установленные флаги. Если вам нужно гарантировать определённый тип массива (например, NPY_ARRAY_C_CONTIGUOUS и NPY_ARRAY_BEHAVED), передайте эти требования в функцию PyArray_FromAny.

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

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

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

NPY_ARRAY_C_CONTIGUOUS

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

NPY_ARRAY_F_CONTIGUOUS

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

NPY_ARRAY_OWNDATA

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

NPY_ARRAY_ALIGNED

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

NPY_ARRAY_WRITEABLE

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

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

NPY_ARRAY_WRITEBACKIFCOPY

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

Это специальный флаг, который устанавливается, если этот массив представляет копию, созданную потому, что пользователь потребовал определённых флагов в PyArray_FromAny, и пришлось создать копию другого массива (и пользователь попросил установить этот флаг в такой ситуации). Атрибут base затем указывает на «неправильно организованный» массив (который устанавливается в режим только для чтения). :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, а не подклассом.

NPY_ARRAY_NOTSWAPPED

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

NPY_ARRAY_BEHAVED_NS

NPY_ARRAY_ALIGNED | NPY_ARRAY_WRITEABLE | NPY_ARRAY_NOTSWAPPED

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

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

PyArray_CHKFLAGS(PyObject *arr, 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.

PyArray_IS_C_CONTIGUOUS(PyObject *arr)

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

PyArray_IS_F_CONTIGUOUS(PyObject *arr)

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

PyArray_ISFORTRAN(PyObject *arr)

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

PyArray_ISWRITEABLE(PyObject *arr)

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

PyArray_ISALIGNED(PyObject *arr)

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

PyArray_ISBEHAVED(PyObject *arr)

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

PyArray_ISBEHAVED_RO(PyObject *arr)

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

PyArray_ISCARRAY(PyObject *arr)

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

PyArray_ISFARRAY(PyObject *arr)

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

PyArray_ISCARRAY_RO(PyObject *arr)

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

PyArray_ISFARRAY_RO(PyObject *arr)

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

PyArray_ISONESEGMENT(PyObject *arr)

Возвращает True, если область данных 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 ->elsize должен быть меньше self ->descr->elsize, иначе возникает ошибка. В противном случае аргумент val преобразуется в массив и копируется в указанное поле. При необходимости элементы val повторяются для заполнения целевого массива. Но количество элементов в целевом массиве должно быть целым кратным количеству элементов в val.

PyObject* PyArray_Byteswap(PyArrayObject* self, 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 отрицательный, используется максимальное доступное значение). Это простой обертка вокруг cPickle.dump(self, file, protocol).

PyObject* PyArray_Dumps(PyObject* self, int protocol)

Записывает объект из self в Python-строку и возвращает её. Используется указанный протокол protocol (или максимальное доступное значение, если 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 истинны. Массивы 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 и так далее. Это эквивалентно команде Python lexsort(sort_keys, axis). Из-за того, как работает сортировка слиянием, убедитесь, что вы понимаете порядок, в котором должны располагаться 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 ). Возвращает диагонали смещения 2-мерных массивов, определённых axis1 и axis2.

npy_intp PyArray_CountNonzero(PyArrayObject* self)

New in version 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.

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

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 dtype, для создания внутренних циклов, манипулирующих этими типами данных, требуется передача дополнительных данных. 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 при ошибке, потому что они могут вызываться из многопоточного контекста.

NPY_AUXDATA_FREE(auxdata)

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

NPY_AUXDATA_CLONE(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.

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[-3] будет 1, x[4] будет 4, x[5] будет 1 и т.д…

NPY_NEIGHBORHOOD_ITER_CIRCULAR_PADDING

Циклическое заполнение. Значения за пределами границ будут такими, как если бы массив повторялся. Например, для массива [1, 2, 3, 4], x[-2] будет 3, x[-3] будет 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, и если да, возвращает соответствующий массивный скаляр. Она должна использоваться всякий раз, когда могут быть возвращены массивы размерности 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 объекта типа данных) также изменяются (рекурсивно). Если встречается порядок байтов 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, например, прикреплённого к объекту типа данных, создаётся упорядоченный список имён полей, как хранится в поле names объекта 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_BEHAVED_RO со флагом 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, 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

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

void import_array(void)

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

PY_ARRAY_UNIQUE_SYMBOL

NO_IMPORT_ARRAY

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

Предположим, у меня есть два файла 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 #определен до #включения этого файла.

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

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

unsigned int PyArray_GetNDArrayCVersion(void)

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

PyDataMem_FREE(char* ptr)

char* PyDataMem_RENEW(void * ptr, size_t newbytes)

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

npy_intp* PyDimMem_NEW(int nd)

PyDimMem_FREE(char* ptr)

npy_intp* PyDimMem_RENEW(void* ptr, size_t newnd)

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

void* PyArray_malloc(size_t nbytes)

PyArray_free(void* ptr)

void* PyArray_realloc(npy_intp* ptr, size_t nbytes)

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

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.

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

NPY_BEGIN_THREADS_DESCR(PyArray_Descr *dtype)

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

NPY_END_THREADS_DESCR(PyArray_Descr *dtype)

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

NPY_BEGIN_THREADS_THRESHOLDED(int loop_size)

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

Группа 2

Эта группа используется для повторного получения GIL Python после его освобождения. Например, предположим, что 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_VERSION

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

NPY_FALSE

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

NPY_TRUE

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

NPY_FAIL

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

NPY_SUCCEED

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

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

PyArray_SAMESHAPE(PyArrayObject *a1, PyArrayObject *a2)

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

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, которое является лексикографическим: сначала сравниваются вещественные части, а затем комплексные части, если вещественные части равны.

PyArray_REFCOUNT(PyObject* op)

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

PyArray_DiscardWritebackIfCopy(PyObject* obj)

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

PyArray_XDECREF_ERR(PyObject* obj)

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

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

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

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_CASTING

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

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

NPY_NO_CASTING

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

NPY_EQUIV_CASTING

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

NPY_SAFE_CASTING

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

NPY_SAME_KIND_CASTING

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

NPY_UNSAFE_CASTING

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