Массив API

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

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

int PyArray_NDIM(PyArrayObject *arr)

Число измерений в массиве.

npy_intp *PyArray_DIMS(PyArrayObject *arr)

Возвращает указатель на размеры/форму массива. Количество элементов соответствует количеству измерений массива.

npy_intp *PyArray_SHAPE(PyArrayObject *arr)

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

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

void *PyArray_DATA(PyArrayObject *arr)

char *PyArray_BYTES(PyArrayObject *arr)

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

npy_intp *PyArray_STRIDES(PyArrayObject* arr)

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

npy_intp PyArray_DIM(PyArrayObject* arr, int n)

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

npy_intp PyArray_STRIDE(PyArrayObject* arr, int n)

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

PyObject *PyArray_BASE(PyArrayObject* arr)

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

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

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

PyArray_Descr *PyArray_DESCR(PyArrayObject* arr)

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

PyArray_Descr *PyArray_DTYPE(PyArrayObject* arr)

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

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

void PyArray_ENABLEFLAGS(PyArrayObject* arr, int flags)

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

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

void PyArray_CLEARFLAGS(PyArrayObject* arr, int flags)

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

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

int PyArray_FLAGS(PyArrayObject* arr)

npy_intp PyArray_ITEMSIZE(PyArrayObject* arr)

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

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

int PyArray_TYPE(PyArrayObject* arr)

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

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

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

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

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

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

npy_intp PyArray_SIZE(PyArrayObject* arr)

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

npy_intp PyArray_Size(PyArrayObject* obj)

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

npy_intp PyArray_NBYTES(PyArrayObject* arr)

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

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

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

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

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

void* PyArray_GETPTR1(PyArrayObject* obj, npy_intp i)

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

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

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

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

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

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

PyObject* PyArray_NewFromDescr(PyTypeObject* subtype, PyArray_Descr* descr, int nd, npy_intp* dims, npy_intp* strides, void* data, int flags, PyObject* obj)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

PyObject* PyArray_New(PyTypeObject* subtype, int nd, npy_intp* dims, int type_num, npy_intp* 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* dims, int typenum)

Создайте новый неинициализированный массив типа typenum, размер которого в каждой из nd размерностей задаётся целочисленным массивом dims. Эта функция не может быть использована для создания массива с гибким типом (без указания itemsize).

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

Создайте обёртку массива вокруг data, на который указывает указанный указатель. Флаги массива будут иметь значение по умолчанию, что область данных ведёт себя хорошо и является непрерывной в стиле C. Форма массива задаётся массивом dims длиной nd. Тип данных массива задаётся typenum.

PyObject* PyArray_SimpleNewFromDescr(int nd, npy_intp* dims, PyArray_Descr* descr)

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

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

PyArray_FILLWBYTE(PyObject* obj, int val)

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

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

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

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

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

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

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

PyObject* PyArray_EMPTY(int nd, npy_intp* 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, что означает, что любой тип данных (и порядок байтов) приемлем. Если в flags отсутствует NPY_ARRAY_FORCECAST, это вызов будет генерировать ошибку, если тип данных не может быть безопасно получен из объекта. Если вы хотите использовать NULL для dtype и убедиться, что массив не переставлен, используйте PyArray_CheckFromAny. Значение 0 для любого из параметров глубины приводит к игнорированию параметра. Любые из следующих флагов массива могут быть добавлены (например, с использованием |), чтобы получить аргумент требования. Если ваш код может обрабатывать общие (например, с шагами, переставленными по байтам или невыровненными массивами) требования, могут быть 0. Кроме того, если op не является массивом (или не экспонирует интерфейс массива), то будет создан новый массив (и заполнен из op с использованием протокола последовательности). Новый массив будет иметь NPY_ARRAY_DEFAULT в качестве своего члена флагов. Аргумент context передается методу __array__ объекта op и используется только в том случае, если массив создается таким образом. Почти всегда этот параметр NULL.

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_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)

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

Получает параметры массива для просмотра/преобразования произвольного PyObject* в массив NumPy. Это позволяет обнаружить «внутренний тип и форму» списка Python списков списков, не преобразуя его в массив. PyArray_FromAny вызывает эту функцию для анализа входных данных.

В некоторых случаях, таких как структурированные массивы и интерфейс __array__, для осмысления объекта необходимо использовать тип данных. Когда это требуется, укажите Descr для ‘requested_dtype’, в противном случае укажите NULL. Эта ссылка не воруется. Кроме того, если запрашиваемый тип данных не изменяет интерпретацию входных данных, out_dtype всё равно получит «внутренний» тип данных объекта, а не тип данных, переданный в ‘requested_dtype’.

Если необходимо записать в значение в ‘op’, установите булеву переменную ‘writeable’ в 1. Это вызывает ошибку, когда ‘op’ является скаляром, списком списков или другим не изменяемым ‘op’. Это отличается от передачи NPY_ARRAY_WRITEABLE в PyArray_FromAny, где изменяемый массив может быть копией входных данных.

При успешном выполнении (возвращаемое значение 0) либо out_arr заполняется ненулевым PyArrayObject, а остальные параметры остаются без изменений, либо out_arr заполняется NULL, а остальные параметры заполняются.

Типичное использование:

PyArrayObject *arr = NULL;
PyArray_Descr *dtype = NULL;
int ndim = 0;
npy_intp dims[NPY_MAXDIMS];

if (PyArray_GetArrayParamsFromObject(op, NULL, 1, &dtype,
                                    &ndim, &dims, &arr, NULL) < 0) {
    return NULL;
}
if (arr == NULL) {
    ... validate/change dtype, validate flags, ndim, etc ...
    // Could make custom strides here too
    arr = PyArray_NewFromDescr(&PyArray_Type, dtype, ndim,
                                dims, NULL,
                                fortran ? NPY_ARRAY_F_CONTIGUOUS : 0,
                                NULL);
    if (arr == NULL) {
        return NULL;
    }
    if (PyArray_CopyObject(arr, op) < 0) {
        Py_DECREF(arr);
        return NULL;
    }
}
else {
    ... in this case the other parameters weren't filled, just
        validate and possibly copy arr itself ...
}
... use arr ...

PyObject* PyArray_CheckFromAny(PyObject* op, PyArray_Descr* dtype, int min_depth, int max_depth, int requirements, PyObject* context)

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

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

NPY_ARRAY_NOTSWAPPED

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

NPY_ARRAY_BEHAVED_NS

NPY_ARRAY_ALIGNED | NPY_ARRAY_WRITEABLE | NPY_ARRAY_NOTSWAPPED

NPY_ARRAY_ELEMENTSTRIDES

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

PyObject* PyArray_FromArray(PyArrayObject* op, PyArray_Descr* newtype, int requirements)

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

PyObject* PyArray_FromStructInterface(PyObject* op)

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

PyObject* PyArray_FromInterface(PyObject* op)

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

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

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

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, заданного перечисленным типом. Минимальное количество измерений массива задаётся 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(op)

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

PyArray_CheckExact(op)

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

PyArray_HasArrayInterface(op, out)

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

PyArray_HasArrayInterfaceType(op, type, context, out)

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

PyArray_IsZeroDim(op)

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

PyArray_IsScalar(op, cls)

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

PyArray_CheckScalar(op)

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

PyArray_IsPythonNumber(op)

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

PyArray_IsPythonScalar(op)

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

PyArray_IsAnyScalar(op)

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

PyArray_CheckAnyScalar(op)

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

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

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

PyTypeNum_ISUNSIGNED(num)

PyDataType_ISUNSIGNED(descr)

PyArray_ISUNSIGNED(obj)

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

PyTypeNum_ISSIGNED(num)

PyDataType_ISSIGNED(descr)

PyArray_ISSIGNED(obj)

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

PyTypeNum_ISINTEGER(num)

PyDataType_ISINTEGER(descr)

PyArray_ISINTEGER(obj)

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

PyTypeNum_ISFLOAT(num)

PyDataType_ISFLOAT(descr)

PyArray_ISFLOAT(obj)

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

PyTypeNum_ISCOMPLEX(num)

PyDataType_ISCOMPLEX(descr)

PyArray_ISCOMPLEX(obj)

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

PyTypeNum_ISNUMBER(num)

PyDataType_ISNUMBER(descr)

PyArray_ISNUMBER(obj)

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

PyTypeNum_ISSTRING(num)

PyDataType_ISSTRING(descr)

PyArray_ISSTRING(obj)

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

PyTypeNum_ISPYTHON(num)

PyDataType_ISPYTHON(descr)

PyArray_ISPYTHON(obj)

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

PyTypeNum_ISFLEXIBLE(num)

PyDataType_ISFLEXIBLE(descr)

PyArray_ISFLEXIBLE(obj)

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

PyDataType_ISUNSIZED(descr):

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

PyTypeNum_ISUSERDEF(num)

PyDataType_ISUSERDEF(descr)

PyArray_ISUSERDEF(obj)

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

PyTypeNum_ISEXTENDED(num)

PyDataType_ISEXTENDED(descr)

PyArray_ISEXTENDED(obj)

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

PyTypeNum_ISOBJECT(num)

PyDataType_ISOBJECT(descr)

PyArray_ISOBJECT(obj)

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

PyTypeNum_ISBOOL(num)

PyDataType_ISBOOL(descr)

PyArray_ISBOOL(obj)

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

PyDataType_HASFIELDS(descr)

PyArray_HASFIELDS(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)

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

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

PyObject* PyArray_Cast(PyArrayObject* arr, int typenum)

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

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

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

int PyArray_CastTo(PyArrayObject* out, PyArrayObject* in)

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

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

PyArray_VectorUnaryFunc* PyArray_GetCastFunc(PyArray_Descr* from, int totype)

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

int PyArray_CanCastSafely(int fromtype, int totype)

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

int PyArray_CanCastTo(PyArray_Descr* fromtype, PyArray_Descr* totype)

PyArray_CanCastTypeTo заменяет эту функцию в NumPy 1.6 и выше.

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

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

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

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

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

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

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

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

PyArray_Descr* PyArray_MinScalarType(PyArrayObject* arr)

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

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

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

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

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

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

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

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

Это применяет повышение типа ко всем входным данным, используя правила NumPy для объединения скаляров и массивов, чтобы определить тип результата набора операндов. Это тот же тип результата, что и у функций 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 — объект, который будет преобразован в массив. Возвращаемое значение — перечисление типа, которое представляет тип данных, которым 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, каждый из которых имеет один и тот же тип данных. Тип выбирается на основе номера типа (выбирается тип с большим номером по сравнению с меньшим), игнорируя объекты, которые являются только скалярами. Длина последовательности возвращается в n, а возвращаемое значение — массив длины n указателей PyArrayObject (или NULL в случае ошибки). Возвращённый массив должен быть освобождён вызывающим эту функцию (с помощью PyDataMem_FREE ), и все объекты массивов в нём должны быть освобождены DECREF, иначе произойдёт утечка памяти. Приведённый ниже пример кода шаблона демонстрирует типичное использование:

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)

Регистрирует тип данных как новый тип данных, определённый пользователем, для массивов. Тип должен иметь большинство заполненных элементов. Это не всегда проверяется, и ошибки могут привести к сбою программы. В частности, член 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)

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

int PyArray_XDECREF(PyArrayObject* op)

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

void PyArray_Item_XDECREF(char* ptr, PyArray_Descr* dtype)

Функция для XDECREF всех объектов в позиции ptr, как указано в типе данных dtype. Она работает рекурсивно, поэтому если dtype сам имеет поля с типами данных, содержащими объекты, все подобные поля будут XDECREF '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 содержит важную информацию о памяти, используемой массивом (на который указывает член data). Эта информация о флагах должна храниться точно, иначе могут возникнуть странные результаты и даже сбой программы.

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

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

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

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

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

NPY_ARRAY_C_CONTIGUOUS

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

NPY_ARRAY_F_CONTIGUOUS

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

NPY_ARRAY_OWNDATA

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

NPY_ARRAY_ALIGNED

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

NPY_ARRAY_WRITEABLE

В область данных можно записывать.

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

NPY_ARRAY_WRITEBACKIFCOPY

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

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

NPY_ARRAY_UPDATEIFCOPY

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

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

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

NPY_ARRAY_BEHAVED

NPY_ARRAY_ALIGNED | NPY_ARRAY_WRITEABLE

NPY_ARRAY_CARRAY

NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_BEHAVED

NPY_ARRAY_CARRAY_RO

NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_ALIGNED

NPY_ARRAY_FARRAY

NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_BEHAVED

NPY_ARRAY_FARRAY_RO

NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_ALIGNED

NPY_ARRAY_DEFAULT

NPY_ARRAY_CARRAY

NPY_ARRAY_UPDATE_ALL

NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_ALIGNED

Флаги-подобные константы

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

NPY_ARRAY_FORCECAST

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

NPY_ARRAY_ENSURECOPY

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

NPY_ARRAY_ENSUREARRAY

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

NPY_ARRAY_NOTSWAPPED

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

NPY_ARRAY_BEHAVED_NS

NPY_ARRAY_ALIGNED | NPY_ARRAY_WRITEABLE | NPY_ARRAY_NOTSWAPPED

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

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

PyArray_CHKFLAGS(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(arr)

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

PyArray_IS_F_CONTIGUOUS(arr)

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

PyArray_ISFORTRAN(arr)

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

PyArray_ISWRITEABLE(arr)

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

PyArray_ISALIGNED(arr)

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

PyArray_ISBEHAVED(arr)

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

PyArray_ISBEHAVED_RO(arr)

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

PyArray_ISCARRAY(arr)

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

PyArray_ISFARRAY(arr)

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

PyArray_ISCARRAY_RO(arr)

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

PyArray_ISFARRAY_RO(arr)

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

PyArray_ISONESEGMENT(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). Возвращает новый массив заданного типа 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 Pickle (или наивысший доступный, если 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)

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

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-й, перед, а все элементы, равные или большие, после k-го элемента. Порядок всех элементов внутри разделов не определён. Если self->descr — это тип данных с определёнными полями, то self->descr->names используется для определения порядка сортировки. Если сравнение по первому полю равно, используется второе поле и так далее. Для изменения порядка сортировки структурированного массива создайте новый тип данных с другим порядком имён и создайте представление массива с этим новым типом данных. Возвращает ноль при успехе и -1 при ошибке.

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

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

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

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

npy_intp PyArray_CountNonzero(PyArrayObject* self)

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

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

PyObject* PyArray_Nonzero(PyArrayObject* self)

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

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

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

Расчёт

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 вызывают округление до ближайших 10, 100 и т. д. Если 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, чтобы алгоритмы можно было реализовать с помощью синтаксиса C’s a[i][j][k]. Эта функция возвращает указатель 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)

Добавлено в версии 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)

Добавлено в версии 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* dims, npy_intp* newstrides)

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

npy_intp PyArray_MultiplyList(npy_intp* seq, int n)

int PyArray_MultiplyIntList(int* seq, int n)

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

int PyArray_CompareLists(npy_intp* l1, npy_intp* 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 *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)

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

PyArray_ITER_GOTO1D(PyObject* iterator, npy_intp index)

Устанавливает индекс и 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]).

Аргумент mode должен быть одним из:

• NPY_NEIGHBORHOOD_ITER_ZERO_PADDING: заполнение нулями. Значения вне границ будут 0.
• NPY_NEIGHBORHOOD_ITER_ONE_PADDING: заполнение единицами. Значения вне границ будут 1.
• NPY_NEIGHBORHOOD_ITER_CONSTANT_PADDING: заполнение константой. Значения вне границ будут такими же, как первый элемент в fill_value.
• NPY_NEIGHBORHOOD_ITER_MIRROR_PADDING: зеркальное заполнение. Значения вне границ будут такими, как если бы элементы массива были зеркально отражены. Например, для массива [1, 2, 3, 4], x[-2] будет 2, x[-2] будет 1, x[4] будет 4, x[5] будет 1 и т.д…
• NPY_NEIGHBORHOOD_ITER_CIRCULAR_PADDING: циклическое заполнение. Значения вне границ будут такими, как если бы массив повторялся. Например, для массива [1, 2, 3, 4], x[-2] будет 3, x[-2] будет 4, x[4] будет 1, x[5] будет 2 и т.д…

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

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

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

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

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

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

int PyArrayNeighborhoodIter_Reset(PyArrayNeighborhoodIterObject* iter)

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

int PyArrayNeighborhoodIter_Next(PyArrayNeighborhoodIterObject* iter)

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

Массивы-скаляры

PyObject* PyArray_Return(PyArrayObject* arr)

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

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

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

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

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

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

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

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

void PyArray_ScalarAsCtype(PyObject* scalar, void* ctypeptr)

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

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

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

PyObject* PyArray_TypeObjectFromType(int type)

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

NPY_SCALARKIND PyArray_ScalarKind(int typenum, PyArrayObject** arr)

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

Возвращает тип скаляра, представленного typenum и массива в *arr (если arr не NULL). Массив предполагается рангом 0 и используется только в том случае, если typenum представляет собой целое число со знаком. Если arr не NULL и первый элемент отрицательный, возвращается NPY_INTNEG_SCALAR, в противном случае возвращается NPY_INTPOS_SCALAR. Возможные значения возврата — NPY_{kind}_SCALAR, где {kind} может быть INTPOS, INTNEG, FLOAT, COMPLEX, BOOL или OBJECT. NPY_NOSCALAR также является перечисленным значением NPY_SCALARKIND, которые могут принимать на себя переменные.

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

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

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

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

int PyArray_DescrCheck(PyObject* obj)

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

int PyArray_SearchsideConverter(PyObject* obj, NPY_SEARCHSIDE* side)

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

int PyArray_OrderConverter(PyObject* obj, NPY_ORDER* order)

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

int PyArray_CastingConverter(PyObject* obj, NPY_CASTING* casting)

Преобразует Python-строки ‘no’, ‘equiv’, ‘safe’, ‘same_kind’, и ‘unsafe’ в перечисление NPY_CASTING NPY_NO_CASTING, NPY_EQUIV_CASTING, NPY_SAFE_CASTING, NPY_SAME_KIND_CASTING, и NPY_UNSAFE_CASTING.

int PyArray_ClipmodeConverter(PyObject* object, NPY_CLIPMODE* val)

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

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

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

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

int PyArray_PyIntAsInt(PyObject* op)

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

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

npy_intp PyArray_PyIntAsIntp(PyObject* op)

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

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

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

int PyArray_TypestrConvert(int itemsize, int gentype)

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

Разное

Импортирование API

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

void import_array(void)

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

PY_ARRAY_UNIQUE_SYMBOL

NO_IMPORT_ARRAY

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

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

#define PY_ARRAY_UNIQUE_SYMBOL cool_ARRAY_API
#include numpy/arrayobject.h

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

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

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

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

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

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

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

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

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

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

unsigned int PyArray_GetNDArrayCVersion(void)

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

unsigned int PyArray_GetNDArrayCFeatureVersion(void)

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

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

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

int PyArray_SetNumericOps(PyObject* dict)

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

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

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

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

PyObject* PyArray_GetNumericOps(void)

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

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

void PyArray_SetStringFunction(PyObject* op, int repr)

Эта функция позволяет изменить методы tp_str и tp_repr объекта массива на любую функцию Python. Таким образом, вы можете изменить то, что происходит со всеми массивами, когда из Python вызываются str(arr) или repr(arr). Вызываемая функция передаётся в качестве 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(nd)

PyDimMem_FREE(npy_intp* ptr)

npy_intp* PyDimMem_RENEW(npy_intp* ptr, npy_intp newnd)

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

PyArray_malloc(nbytes)

PyArray_free(ptr)

PyArray_realloc(ptr, nbytes)

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

int PyArray_ResolveWritebackIfCopy(PyArrayObject* obj)

Если obj.flags имеет NPY_ARRAY_WRITEBACKIFCOPY или (устаревшее) NPY_ARRAY_UPDATEIFCOPY, эта функция очищает флаги, DECREF s 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 определён как константа WITH_THREADS, определённая в Python, за исключением случаев, когда переменная окружения 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 после его освобождения. Например, предположим, что 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_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(a1, a2)

Принимает значение True, если массивы a1 и a2 имеют одинаковую форму.

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)

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

PyArray_REFCOUNT(PyObject* op)

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

PyArray_DiscardWritebackIfCopy(PyObject* obj)

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

PyArray_XDECREF_ERR(PyObject* obj)

Устарело в версии 1.14, используйте PyArray_DiscardWritebackIfCopy в сочетании с Py_XDECREF

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

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

NPY_SORTKIND

Специальный тип переменной, который может принимать значения NPY_{KIND}, где {KIND} является

QUICKSORT, HEAPSORT, MERGESORT

NPY_NSORTS

Определено как количество видов сортировки.

NPY_SCALARKIND

Специальный тип переменной, указывающий количество «видов» скаляров, различаемых при определении правил коэрации скаляров. Эта переменная может принимать значения NPY_{KIND}, где {KIND} может быть

NOSCALAR, BOOL_SCALAR, INTPOS_SCALAR, INTNEG_SCALAR, FLOAT_SCALAR, COMPLEX_SCALAR, 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

New in version 1.6.

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

NPY_NO_CASTING

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

NPY_EQUIV_CASTING

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

NPY_SAFE_CASTING

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

NPY_SAME_KIND_CASTING

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

NPY_UNSAFE_CASTING

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