Array API

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

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

int PyArray_NDIM(PyArrayObject *arr)

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

int PyArray_FLAGS(PyArrayObject* arr)

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

int PyArray_TYPE(PyArrayObject* arr)

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

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

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

void PyArray_ENABLEFLAGS(PyArrayObject* arr, int flags)

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

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

void PyArray_CLEARFLAGS(PyArrayObject* arr, int flags)

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

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

void *PyArray_DATA(PyArrayObject *arr)

char *PyArray_BYTES(PyArrayObject *arr)

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

npy_intp *PyArray_DIMS(PyArrayObject *arr)

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

npy_intp *PyArray_SHAPE(PyArrayObject *arr)

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

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

npy_intp *PyArray_STRIDES(PyArrayObject* arr)

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

npy_intp PyArray_DIM(PyArrayObject* arr, int n)

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

npy_intp PyArray_STRIDE(PyArrayObject* arr, int n)

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

npy_intp PyArray_ITEMSIZE(PyArrayObject* arr)

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

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

npy_intp PyArray_SIZE(PyArrayObject* arr)

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

npy_intp PyArray_Size(PyArrayObject* obj)

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

npy_intp PyArray_NBYTES(PyArrayObject* arr)

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

PyObject *PyArray_BASE(PyArrayObject* arr)

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

Если вы создаёте массив с помощью C API и указываете собственную память, вы должны использовать функцию 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.

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

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

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

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

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

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

Возвращает указатель на данные ndarray, aobj, в N-мерном индексе, заданном 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 const* dims, npy_intp const* strides, void* data, int flags, PyObject* obj)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

PyArray_FILLWBYTE(PyObject* obj, int val)

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

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

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

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

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

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

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

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

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

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

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

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

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

int PyArray_SetBaseObject(PyArrayObject* arr, PyObject* obj)

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

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

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

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

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

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

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

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

NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_ALIGNED | NPY_ARRAY_WRITEABLE

NPY_ARRAY_OUT_FARRAY

NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_WRITEABLE | NPY_ARRAY_ALIGNED

NPY_ARRAY_INOUT_ARRAY

NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_WRITEABLE | NPY_ARRAY_ALIGNED | NPY_ARRAY_WRITEBACKIFCOPY | NPY_ARRAY_UPDATEIFCOPY

NPY_ARRAY_INOUT_FARRAY

NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_WRITEABLE | NPY_ARRAY_ALIGNED | NPY_ARRAY_WRITEBACKIFCOPY | NPY_ARRAY_UPDATEIFCOPY

int PyArray_GetArrayParamsFromObject(PyObject* op, PyArray_Descr* requested_dtype, npy_bool writeable, PyArray_Descr** out_dtype, int* out_ndim, npy_intp* out_dims, PyArrayObject** out_arr, PyObject* context)

Новое в версии 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 заполняется не-NULL 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 с параметрами requirements, установленными на NPY_ARRAY_DEFAULT, и значением member type_num аргумента type, установленным на typenum.

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

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

PyObject* PyArray_EnsureArray(PyObject* op)

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

PyObject* PyArray_FromString(char* string, npy_intp slen, PyArray_Descr* dtype, npy_intp num, char* sep)

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

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

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

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

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

int PyArray_CopyInto(PyArrayObject* dest, PyArrayObject* src)

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

int PyArray_MoveInto(PyArrayObject* dest, PyArrayObject* src)

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

PyArrayObject* PyArray_GETCONTIGUOUS(PyObject* op)

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

PyObject* PyArray_FROM_O(PyObject* obj)

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

PyObject* PyArray_FROM_OF(PyObject* obj, int requirements)

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

PyObject* PyArray_FROM_OT(PyObject* obj, int typenum)

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

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

Сочетание PyArray_FROM_OF и PyArray_FROM_OT, позволяющее указать как аргумент typenum, так и flags.

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

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

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

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

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

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

PyArray_Check(PyObject *op)

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

PyArray_CheckExact(PyObject *op)

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

PyArray_HasArrayInterface(PyObject *op, PyObject *out)

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

PyArray_HasArrayInterfaceType(op, type, context, out)

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

PyArray_IsZeroDim(op)

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

PyArray_IsScalar(op, cls)

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

PyArray_CheckScalar(op)

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

PyArray_IsPythonNumber(op)

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

PyArray_IsPythonScalar(op)

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

PyArray_IsAnyScalar(op)

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

PyArray_CheckAnyScalar(op)

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

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

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

PyTypeNum_ISUNSIGNED(int num)

PyDataType_ISUNSIGNED(PyArray_Descr *descr)

PyArray_ISUNSIGNED(PyArrayObject *obj)

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

PyTypeNum_ISSIGNED(int num)

PyDataType_ISSIGNED(PyArray_Descr *descr)

PyArray_ISSIGNED(PyArrayObject *obj)

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

PyTypeNum_ISINTEGER(int num)

PyDataType_ISINTEGER(PyArray_Descr* descr)

PyArray_ISINTEGER(PyArrayObject *obj)

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

PyTypeNum_ISFLOAT(int num)

PyDataType_ISFLOAT(PyArray_Descr* descr)

PyArray_ISFLOAT(PyArrayObject *obj)

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

PyTypeNum_ISCOMPLEX(int num)

PyDataType_ISCOMPLEX(PyArray_Descr* descr)

PyArray_ISCOMPLEX(PyArrayObject *obj)

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

PyTypeNum_ISNUMBER(int num)

PyDataType_ISNUMBER(PyArray_Descr* descr)

PyArray_ISNUMBER(PyArrayObject *obj)

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

PyTypeNum_ISSTRING(int num)

PyDataType_ISSTRING(PyArray_Descr* descr)

PyArray_ISSTRING(PyArrayObject *obj)

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

PyTypeNum_ISPYTHON(int num)

PyDataType_ISPYTHON(PyArray_Descr* descr)

PyArray_ISPYTHON(PyArrayObject *obj)

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

PyTypeNum_ISFLEXIBLE(int num)

PyDataType_ISFLEXIBLE(PyArray_Descr* descr)

PyArray_ISFLEXIBLE(PyArrayObject *obj)

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

PyDataType_ISUNSIZED(PyArray_Descr* descr):

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

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

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

PyTypeNum_ISUSERDEF(int num)

PyDataType_ISUSERDEF(PyArray_Descr* descr)

PyArray_ISUSERDEF(PyArrayObject *obj)

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

PyTypeNum_ISEXTENDED(int num)

PyDataType_ISEXTENDED(PyArray_Descr* descr)

PyArray_ISEXTENDED(PyArrayObject *obj)

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

PyTypeNum_ISOBJECT(int num)

PyDataType_ISOBJECT(PyArray_Descr* descr)

PyArray_ISOBJECT(PyArrayObject *obj)

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

PyTypeNum_ISBOOL(int num)

PyDataType_ISBOOL(PyArray_Descr* descr)

PyArray_ISBOOL(PyArrayObject *obj)

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

PyDataType_HASFIELDS(PyArray_Descr* descr)

PyArray_HASFIELDS(PyArrayObject *obj)

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

PyArray_ISNOTSWAPPED(m)

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

PyArray_ISBYTESWAPPED(m)

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

Bool PyArray_EquivTypes(PyArray_Descr* type1, PyArray_Descr* type2)

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

Bool PyArray_EquivArrTypes(PyArrayObject* a1, PyArrayObject * a2)

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

Bool PyArray_EquivTypenums(int typenum1, int typenum2)

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

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

True, если символы порядка байтов ( NPY_LITTLE, NPY_BIG, NPY_IGNORE, NPY_NATIVE ) равны или эквивалентны по своему определению родного порядка байтов. Таким образом, на машине с порядком байтов 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)

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

int PyArray_CastTo(PyArrayObject* out, PyArrayObject* in)

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

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

PyArray_VectorUnaryFunc* PyArray_GetCastFunc(PyArray_Descr* from, int totype)

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

int PyArray_CanCastSafely(int fromtype, int totype)

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

int PyArray_CanCastTo(PyArray_Descr* fromtype, PyArray_Descr* totype)

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

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

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

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

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

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

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

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

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

PyArray_Descr* PyArray_MinScalarType(PyArrayObject* arr)

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

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

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

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)

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

int PyArray_XDECREF(PyArrayObject* op)

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

void PyArray_Item_XDECREF(char* ptr, PyArray_Descr* dtype)

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

void PyArray_FillObjectArray(PyArrayObject* arr, PyObject* obj)

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

int PyArray_SetUpdateIfCopyBase(PyArrayObject* arr, PyArrayObject* base)

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

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

int PyArray_SetWritebackIfCopyBase(PyArrayObject* arr, PyArrayObject* base)

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

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

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

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

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

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

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

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

Флаги массива используются для указания того, что можно сказать о данных, связанных с массивом.

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

NPY_ARRAY_C_CONTIGUOUS

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

NPY_ARRAY_F_CONTIGUOUS

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

NPY_ARRAY_OWNDATA

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

NPY_ARRAY_ALIGNED

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

NPY_ARRAY_WRITEABLE

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

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

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(PyObject *arr, flags)

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

PyArray_IS_C_CONTIGUOUS(PyObject *arr)

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

PyArray_IS_F_CONTIGUOUS(PyObject *arr)

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

PyArray_ISFORTRAN(PyObject *arr)

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

PyArray_ISWRITEABLE(PyObject *arr)

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

PyArray_ISALIGNED(PyObject *arr)

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

PyArray_ISBEHAVED(PyObject *arr)

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

PyArray_ISBEHAVED_RO(PyObject *arr)

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

PyArray_ISCARRAY(PyObject *arr)

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

PyArray_ISFARRAY(PyObject *arr)

Возвращает истину, если область данных arr имеет фортран-стилевую непрерывность и PyArray_ISBEHAVED (arr) — истина.

PyArray_ISCARRAY_RO(PyObject *arr)

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

PyArray_ISFARRAY_RO(PyObject *arr)

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

PyArray_ISONESEGMENT(PyObject *arr)

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

void PyArray_UpdateFlags(PyArrayObject* arr, int flagmask)

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

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

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

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

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

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

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

PyObject* PyArray_Byteswap(PyArrayObject* self, 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, то возвращается массив с фортран-стилевой непрерывностью. Если order равно NPY_ANYORDER, то возвращаемый массив будет фортран-стилевым непрерывным только если исходный массив является таковым; в противном случае он будет 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-print, показывающей, как будут выводиться элементы.

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

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

PyObject* PyArray_Dumps(PyObject* self, int protocol)

Записывает объект из self в строку Python и возвращает её. Используется предоставленный протокол protocol (или наивысший доступный, если 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 должен быть односегментным, и общее количество байтов должно быть одинаковым. В последнем случае размерности возвращаемого массива будут изменены в последней (или первой для фортран-стилевых непрерывных массивов) размерности. Область данных возвращаемого массива и self — точно одинаковые.

Изменение формы

PyObject* PyArray_Newshape(PyArrayObject* self, PyArray_Dims* newshape, NPY_ORDER order)

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

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

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

PyObject* PyArray_Squeeze(PyArrayObject* self)

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

PyObject* PyArray_SwapAxes(PyArrayObject* self, int a1, int a2)

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

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

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

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

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

PyObject* PyArray_Flatten(PyArrayObject* self, NPY_ORDER order)

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

PyObject* PyArray_Ravel(PyArrayObject* self, NPY_ORDER order)

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

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

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

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

PyObject* PyArray_PutTo(PyArrayObject* self, PyObject* values, PyObject* indices, NPY_CLIPMODE clipmode)

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

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

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

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

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

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

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

NPY_RAISE

вызывает ValueError;

NPY_WRAP

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

NPY_CLIP

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

PyObject* PyArray_Sort(PyArrayObject* self, int axis, NPY_SORTKIND kind)

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

PyObject* PyArray_ArgSort(PyArrayObject* self, int axis)

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

PyObject* PyArray_LexSort(PyObject* sort_keys, int axis)

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

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

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

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

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

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

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

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

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

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

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

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

npy_intp PyArray_CountNonzero(PyArrayObject* self)

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

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

PyObject* PyArray_Nonzero(PyArrayObject* self)

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

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

Эквивалентно ndarray.compress (self, condition, axis ). Возвращает элементы вдоль axis, соответствующие элементам condition, которые равны 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. Положительный offset выбирает диагонали над главной диагональю. Отрицательный offset выбирает диагонали под главной диагональю.

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

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

PyObject* PyArray_Conjugate(PyArrayObject* self)

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

PyObject* PyArray_Round(PyArrayObject* self, int decimals, PyArrayObject* out)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Функции

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

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

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

Параметры

• op – Адрес любого объекта Python. Этот объект Python будет заменён эквивалентным корректным, непрерывным в стиле C массивом ndarray заданного типа данных, указанного двумя последними аргументами. Убедитесь, что взятие ссылки на входной объект таким образом обосновано.
• 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 const* dims, npy_intp const* newstrides)

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

npy_intp PyArray_MultiplyList(npy_intp const* seq, int n)

int PyArray_MultiplyIntList(int const* seq, int n)

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

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

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

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

NpyAuxData

При работе с более сложными типами данных (dtypes), составленными из других dtypes, таких как тип struct dtype, создание внутренних циклов, манипулирующих dtypes, требует переноса дополнительных данных. 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. Этот итератор можно использовать для написания чего-то подобного тому, что делают ufunc, где цикл по самой большой оси выполняется отдельной подпрограммой. Если *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.

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

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

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

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

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

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

NPY_NEIGHBORHOOD_ITER_ZERO_PADDING

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

NPY_NEIGHBORHOOD_ITER_ONE_PADDING

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

NPY_NEIGHBORHOOD_ITER_CONSTANT_PADDING

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

NPY_NEIGHBORHOOD_ITER_MIRROR_PADDING

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

NPY_NEIGHBORHOOD_ITER_CIRCULAR_PADDING

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

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

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

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

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

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

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

int PyArrayNeighborhoodIter_Reset(PyArrayNeighborhoodIterObject* iter)

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

int PyArrayNeighborhoodIter_Next(PyArrayNeighborhoodIterObject* iter)

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

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

PyObject* PyArray_Return(PyArrayObject* arr)

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

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

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

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

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

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

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

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

void PyArray_ScalarAsCtype(PyObject* scalar, void* ctypeptr)

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

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

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

PyObject* PyArray_TypeObjectFromType(int type)

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

NPY_SCALARKIND PyArray_ScalarKind(int typenum, PyArrayObject** arr)

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

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

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

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

Реализует правила приведения скаляров. Скаляры приводятся только без ошибок из thistype в neededtype, если эта функция возвращает ненулевое значение. Если скаляр — 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. Все ссылающиеся объекты типа данных (в членах subdescr и fields объекта типа данных) также изменяются (рекурсивно). Если встречается порядок байтов NPY_IGNORE, он остается без изменений. Если newendian равен NPY_SWAP, то все порядки байтов меняются местами. Другие допустимые значения newendian — NPY_NATIVE, NPY_LITTLE, и NPY_BIG, что заставляет возвращаемый описатель типа данных (и все ссылающиеся описатели типов данных) иметь соответствующий порядок байтов.

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

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

PyArray_Descr* PyArray_DescrFromScalar(PyObject* scalar)

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

PyArray_Descr* PyArray_DescrFromType(int typenum)

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

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

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

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

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

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

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

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

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

PyObject *PyArray_FieldNames(PyObject* dict)

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

Служебные функции преобразования

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

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

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

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

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

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

int PyArray_IntpConverter(PyObject* obj, PyArray_Dims* seq)

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

int PyArray_BufferConverter(PyObject* obj, PyArray_Chunk* buf)

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

int PyArray_AxisConverter(PyObject * obj, int* axis)

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

int PyArray_BoolConverter(PyObject* obj, Bool* value)

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

int PyArray_ByteorderConverter(PyObject* obj, char* endian)

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

int PyArray_SortkindConverter(PyObject* obj, NPY_SORTKIND* sort)

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

int PyArray_SearchsideConverter(PyObject* obj, NPY_SEARCHSIDE* side)

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

int PyArray_OrderConverter(PyObject* obj, NPY_ORDER* order)

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

int PyArray_CastingConverter(PyObject* obj, NPY_CASTING* casting)

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

int PyArray_ClipmodeConverter(PyObject* object, NPY_CLIPMODE* val)

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

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

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

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

int PyArray_PyIntAsInt(PyObject* op)

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

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

npy_intp PyArray_PyIntAsIntp(PyObject* op)

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

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

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

int PyArray_TypestrConvert(int itemsize, int gentype)

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

Разное

Импорт API

Для использования 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. Таким образом, можно изменить поведение всех массивов при вызове str(arr) или repr(arr) из Python. Вызываемая функция передается в качестве op. Если repr не равно нулю, то эта функция будет вызвана в ответ на repr(arr), в противном случае — в ответ на str(arr). Проверка того, является ли op вызываемой функцией, не выполняется. Переданная в op вызываемая функция должна принимать массив в качестве аргумента и возвращать строку для вывода.

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

char* PyDataMem_NEW(size_t nbytes)

PyDataMem_FREE(char* ptr)

char* PyDataMem_RENEW(void * ptr, size_t newbytes)

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

npy_intp* PyDimMem_NEW(int nd)

PyDimMem_FREE(char* ptr)

npy_intp* PyDimMem_RENEW(void* ptr, size_t newnd)

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

void* PyArray_malloc(size_t nbytes)

PyArray_free(void* ptr)

void* PyArray_realloc(npy_intp* ptr, size_t nbytes)

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

int PyArray_ResolveWritebackIfCopy(PyArrayObject* obj)

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

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

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

Эти макросы имеют смысл только если NPY_ALLOW_THREADS принимает значение True во время компиляции модуля расширения. В противном случае эти макросы эквивалентны пробелу. Python использует единый глобальный интерпретаторский замок (GIL) для каждого процесса Python, так что только один поток может выполняться одновременно (даже на многопроцессорных машинах). При вызове скомпилированной функции, которая может занимать много времени для вычисления (и не имеет побочных эффектов для других потоков, таких как обновление глобальных переменных), необходимо освободить GIL, чтобы другие потоки Python могли выполняться, пока выполняются длительные вычисления. Это можно сделать с помощью двух групп макросов. Как правило, если один макрос из группы используется в блоке кода, все они должны использоваться в одном и том же блоке кода. В настоящее время NPY_ALLOW_THREADS определён как константа 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. Эти макросы выполняют в сущности обратное действие трех предыдущих (получение блокировки, сохранение ее состояния) и затем повторно освобождают его с сохраненным состоянием.

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__ (преобразованный в двойное число) объекта obj или def, если атрибут с таким именем не существует. Предложены быстрые возвраты, которые избегают поиска атрибута для объектов типа PyArray_Type.

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

NPY_BUFSIZE

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

NPY_MIN_BUFSIZE

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

NPY_MAX_BUFSIZE

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

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

NPY_NUM_FLOATTYPE

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

NPY_MAXDIMS

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

NPY_MAXARGS

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

NPY_VERSION

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

NPY_FALSE

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

NPY_TRUE

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

NPY_FAIL

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

NPY_SUCCEED

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

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

PyArray_SAMESHAPE(PyArrayObject *a1, PyArrayObject *a2)

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

a

b

PyArray_MAX(a, b)

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

PyArray_MIN(a, b)

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

PyArray_CLT(a, b)

PyArray_CGT(a, b)

PyArray_CLE(a, b)

PyArray_CGE(a, b)

PyArray_CEQ(a, b)

PyArray_CNE(a, b)

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

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_QUICKSORT

NPY_HEAPSORT

NPY_MERGESORT

NPY_STABLESORT

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

NPY_NSORTS

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

NPY_SCALARKIND

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

NPY_NOSCALAR

NPY_BOOL_SCALAR

NPY_INTPOS_SCALAR

NPY_INTNEG_SCALAR

NPY_FLOAT_SCALAR

NPY_COMPLEX_SCALAR

NPY_OBJECT_SCALAR

NPY_NSCALARKINDS

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

NPY_ORDER

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

NPY_ANYORDER

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

NPY_CORDER

Порядок C.

NPY_FORTRANORDER

Порядок Fortran.

NPY_KEEPORDER

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

NPY_CLIPMODE

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

NPY_RAISE

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

NPY_CLIP

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

NPY_WRAP

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

NPY_CASTING

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

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

NPY_NO_CASTING

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

NPY_EQUIV_CASTING

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

NPY_SAFE_CASTING

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

NPY_SAME_KIND_CASTING

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

NPY_UNSAFE_CASTING

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