Массивный API

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

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

int PyArray_NDIM(PyArrayObject *arr)

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

npy_intp *PyArray_DIMS(PyArrayObject *arr)

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

npy_intp *PyArray_SHAPE(PyArrayObject *arr)

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

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

void *PyArray_DATA(PyArrayObject *arr)

char *PyArray_BYTES(PyArrayObject *arr)

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

npy_intp *PyArray_STRIDES(PyArrayObject* arr)

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

npy_intp PyArray_DIM(PyArrayObject* arr, int n)

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

npy_intp PyArray_STRIDE(PyArrayObject* arr, int n)

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

PyObject *PyArray_BASE(PyArrayObject* arr)

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

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

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

PyArray_Descr *PyArray_DESCR(PyArrayObject* arr)

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

PyArray_Descr *PyArray_DTYPE(PyArrayObject* arr)

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

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

void PyArray_ENABLEFLAGS(PyArrayObject* arr, int flags)

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

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

void PyArray_CLEARFLAGS(PyArrayObject* arr, int flags)

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

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

int PyArray_FLAGS(PyArrayObject* arr)

npy_intp PyArray_ITEMSIZE(PyArrayObject* arr)

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

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

int PyArray_TYPE(PyArrayObject* arr)

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

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

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

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

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

npy_intp PyArray_SIZE(PyArrayObject* arr)

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

npy_intp PyArray_Size(PyArrayObject* obj)

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

npy_intp PyArray_NBYTES(PyArrayObject* arr)

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

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

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

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

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

void* PyArray_GETPTR1(PyArrayObject* obj, npy_intp i)

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

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

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

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

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

Из ничего

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Форма массива задаётся массивом dims длиной nd. Тип данных массива указан в typenum.

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

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

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

PyArray_FILLWBYTE(PyObject* obj, int val)

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

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

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

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

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

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

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

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

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

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

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

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

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

int PyArray_SetBaseObject(PyArrayObject* arr, PyObject* obj)

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

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

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

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

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

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

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

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

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

NPY_ARRAY_C_CONTIGUOUS

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

NPY_ARRAY_F_CONTIGUOUS

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

NPY_ARRAY_ALIGNED

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

NPY_ARRAY_WRITEABLE

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

NPY_ARRAY_ENSURECOPY

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

NPY_ARRAY_ENSUREARRAY

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

NPY_ARRAY_FORCECAST

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

NPY_ARRAY_WRITEBACKIFCOPY

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

NPY_ARRAY_UPDATEIFCOPY

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

NPY_ARRAY_BEHAVED

NPY_ARRAY_ALIGNED | NPY_ARRAY_WRITEABLE

NPY_ARRAY_CARRAY

NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_BEHAVED

NPY_ARRAY_CARRAY_RO

NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_ALIGNED

NPY_ARRAY_FARRAY

NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_BEHAVED

NPY_ARRAY_FARRAY_RO

NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_ALIGNED

NPY_ARRAY_DEFAULT

NPY_ARRAY_CARRAY

NPY_ARRAY_IN_ARRAY

NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_ALIGNED

NPY_ARRAY_IN_FARRAY

NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_ALIGNED

NPY_OUT_ARRAY

NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_WRITEABLE | NPY_ARRAY_ALIGNED

NPY_ARRAY_OUT_FARRAY

NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_WRITEABLE | NPY_ARRAY_ALIGNED

NPY_ARRAY_INOUT_ARRAY

NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_WRITEABLE | NPY_ARRAY_ALIGNED | NPY_ARRAY_WRITEBACKIFCOPY | NPY_ARRAY_UPDATEIFCOPY

NPY_ARRAY_INOUT_FARRAY

NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_WRITEABLE | NPY_ARRAY_ALIGNED | NPY_ARRAY_WRITEBACKIFCOPY | NPY_ARRAY_UPDATEIFCOPY

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

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

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

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

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

При успешном завершении (возвращаемое значение 0), либо out_arr заполняется не-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 с требованиями, установленными в NPY_ARRAY_DEFAULT, и членом type_num аргумента типа, установленным в typenum.

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

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

PyObject* PyArray_EnsureArray(PyObject* op)

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

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

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

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

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

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

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

int PyArray_CopyInto(PyArrayObject* dest, PyArrayObject* src)

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

int PyArray_MoveInto(PyArrayObject* dest, PyArrayObject* src)

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

PyArrayObject* PyArray_GETCONTIGUOUS(PyObject* op)

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

PyObject* PyArray_FROM_O(PyObject* obj)

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

PyObject* PyArray_FROM_OF(PyObject* obj, int requirements)

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

PyObject* PyArray_FROM_OT(PyObject* obj, int typenum)

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

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

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

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

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

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

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

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

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

PyArray_Check(op)

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

PyArray_CheckExact(op)

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

PyArray_HasArrayInterface(op, out)

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

PyArray_HasArrayInterfaceType(op, type, context, out)

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

PyArray_IsZeroDim(op)

Возвращает 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(num)

PyDataType_ISUNSIGNED(descr)

PyArray_ISUNSIGNED(obj)

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

PyTypeNum_ISSIGNED(num)

PyDataType_ISSIGNED(descr)

PyArray_ISSIGNED(obj)

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

PyTypeNum_ISINTEGER(num)

PyDataType_ISINTEGER(descr)

PyArray_ISINTEGER(obj)

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

PyTypeNum_ISFLOAT(num)

PyDataType_ISFLOAT(descr)

PyArray_ISFLOAT(obj)

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

PyTypeNum_ISCOMPLEX(num)

PyDataType_ISCOMPLEX(descr)

PyArray_ISCOMPLEX(obj)

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

PyTypeNum_ISNUMBER(num)

PyDataType_ISNUMBER(descr)

PyArray_ISNUMBER(obj)

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

PyTypeNum_ISSTRING(num)

PyDataType_ISSTRING(descr)

PyArray_ISSTRING(obj)

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

PyTypeNum_ISPYTHON(num)

PyDataType_ISPYTHON(descr)

PyArray_ISPYTHON(obj)

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

PyTypeNum_ISFLEXIBLE(num)

PyDataType_ISFLEXIBLE(descr)

PyArray_ISFLEXIBLE(obj)

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

PyDataType_ISUNSIZED(descr):

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

PyTypeNum_ISUSERDEF(num)

PyDataType_ISUSERDEF(descr)

PyArray_ISUSERDEF(obj)

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

PyTypeNum_ISEXTENDED(num)

PyDataType_ISEXTENDED(descr)

PyArray_ISEXTENDED(obj)

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

PyTypeNum_ISOBJECT(num)

PyDataType_ISOBJECT(descr)

PyArray_ISOBJECT(obj)

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

PyTypeNum_ISBOOL(num)

PyDataType_ISBOOL(descr)

PyArray_ISBOOL(obj)

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

PyDataType_HASFIELDS(descr)

PyArray_HASFIELDS(obj)

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

PyArray_ISNOTSWAPPED(m)

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

PyArray_ISBYTESWAPPED(m)

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

Bool PyArray_EquivTypes(PyArray_Descr* type1, PyArray_Descr* type2)

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

Bool PyArray_EquivArrTypes(PyArrayObject* a1, PyArrayObject * a2)

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

Bool PyArray_EquivTypenums(int typenum1, int typenum2)

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

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

True, если символы byteorder ( NPY_LITTLE, NPY_BIG, NPY_NATIVE, NPY_IGNORE ) равны или эквивалентны с точки зрения их задания родного порядка байтов. Таким образом, на машине с малым порядком байтов NPY_LITTLE и NPY_NATIVE эквивалентны, где они не эквивалентны на машине с большим порядком байтов.

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

PyObject* PyArray_Cast(PyArrayObject* arr, int typenum)

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

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

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

int PyArray_CastTo(PyArrayObject* out, PyArrayObject* in)

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

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

PyArray_VectorUnaryFunc* PyArray_GetCastFunc(PyArray_Descr* from, int totype)

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

int PyArray_CanCastSafely(int fromtype, int totype)

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

int PyArray_CanCastTo(PyArray_Descr* fromtype, PyArray_Descr* totype)

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

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

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

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

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

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

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

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

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

PyArray_Descr* PyArray_MinScalarType(PyArrayObject* arr)

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

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

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

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

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

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

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

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

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

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

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

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

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

NPY_ARRAY_C_CONTIGUOUS

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

NPY_ARRAY_F_CONTIGUOUS

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

NPY_ARRAY_OWNDATA

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

NPY_ARRAY_ALIGNED

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

NPY_ARRAY_WRITEABLE

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

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

NPY_ARRAY_WRITEBACKIFCOPY

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

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

NPY_ARRAY_UPDATEIFCOPY

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

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

Комбинации флагов массива

NPY_ARRAY_BEHAVED

NPY_ARRAY_ALIGNED | NPY_ARRAY_WRITEABLE

NPY_ARRAY_CARRAY

NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_BEHAVED

NPY_ARRAY_CARRAY_RO

NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_ALIGNED

NPY_ARRAY_FARRAY

NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_BEHAVED

NPY_ARRAY_FARRAY_RO

NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_ALIGNED

NPY_ARRAY_DEFAULT

NPY_ARRAY_CARRAY

NPY_ARRAY_UPDATE_ALL

NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_ALIGNED

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

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

NPY_ARRAY_FORCECAST

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

NPY_ARRAY_ENSURECOPY

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

NPY_ARRAY_ENSUREARRAY

Обеспечить, что полученный объект является фактически ndarray, а не подклассом.

NPY_ARRAY_NOTSWAPPED

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

NPY_ARRAY_BEHAVED_NS

NPY_ARRAY_ALIGNED | NPY_ARRAY_WRITEABLE | NPY_ARRAY_NOTSWAPPED

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

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

PyArray_CHKFLAGS(arr, flags)

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

PyArray_IS_C_CONTIGUOUS(arr)

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

PyArray_IS_F_CONTIGUOUS(arr)

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

PyArray_ISFORTRAN(arr)

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

PyArray_ISWRITEABLE(arr)

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

PyArray_ISALIGNED(arr)

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

PyArray_ISBEHAVED(arr)

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

PyArray_ISBEHAVED_RO(arr)

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

PyArray_ISCARRAY(arr)

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

PyArray_ISFARRAY(arr)

Возвращает true, если область данных arr является фортрановски непрерывной и PyArray_ISBEHAVED (arr) равно true.

PyArray_ISCARRAY_RO(arr)

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

PyArray_ISFARRAY_RO(arr)

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

PyArray_ISONESEGMENT(arr)

Возвращает true, если область данных 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). Возвращает новый массив заданного типа dtype, используя данные из текущего массива по указанному смещению offset в байтах. offset плюс размер элемента нового типа массива должны быть меньше self ->descr->elsize, иначе произойдёт ошибка. Используются те же размеры и шаги, что и в исходном массиве. Таким образом, эта функция действует как выбор поля из структурированного массива. Но её также можно использовать для выбора определённых байтов или групп байтов из любого типа массива.

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

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

PyObject* PyArray_Byteswap(PyArrayObject* self, Bool inplace)

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

PyObject* PyArray_NewCopy(PyArrayObject* old, NPY_ORDER order)

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

PyObject* PyArray_ToList(PyArrayObject* self)

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

PyObject* PyArray_ToString(PyArrayObject* self, NPY_ORDER order)

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

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

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

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

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

PyObject* PyArray_Dumps(PyObject* self, int protocol)

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

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

PyObject* PyArray_ArgSort(PyArrayObject* self, int axis)

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

PyObject* PyArray_LexSort(PyObject* sort_keys, int axis)

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

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

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

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

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

npy_intp PyArray_CountNonzero(PyArrayObject* self)

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

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

PyObject* PyArray_Nonzero(PyArrayObject* self)

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

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

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

Вычисления

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

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

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

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

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

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

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

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

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

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

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

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

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

Эквивалентно ndarray.trace (self, offset, axis1, axis2, rtype). Возвращает сумму (используя rtype в качестве типа данных суммирования) по диагональным элементам с offset 2-мерных массивов, определённых переменными axis1 и axis2. Положительное значение 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). Возвращает вектор сумм элементов в self по оси axis в виде одномерного вектора. Выполняет суммирование после преобразования данных к типу данных rtype.

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

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

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

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

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

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

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

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

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

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

Функции

Функции для массивов

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

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

Параметры:

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)

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

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

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

Примечания

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

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

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

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

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

Bool PyArray_CheckStrides(int elsize, int nd, npy_intp numbytes, npy_intp* dims, npy_intp* newstrides)

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

npy_intp PyArray_MultiplyList(npy_intp* seq, int n)

int PyArray_MultiplyIntList(int* seq, int n)

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

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

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

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

NpyAuxData

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

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

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

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

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

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

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

    return (NpyAuxData *)ret;
}

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

    return (NpyAuxData *)ret;
}

NpyAuxData_FreeFunc

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

NpyAuxData_CloneFunc

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

NPY_AUXDATA_FREE(auxdata)

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

NPY_AUXDATA_CLONE(auxdata)

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

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

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

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

PyObject* PyArray_IterNew(PyObject* arr)

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

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

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

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

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

int PyArrayIter_Check(PyObject* op)

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

void PyArray_ITER_RESET(PyObject* iterator)

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

void PyArray_ITER_NEXT(PyObject* iterator)

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

void *PyArray_ITER_DATA(PyObject* iterator)

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

void PyArray_ITER_GOTO(PyObject* iterator, npy_intp* destination)

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

PyArray_ITER_GOTO1D(PyObject* iterator, npy_intp index)

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

int PyArray_ITER_NOTDONE(PyObject* iterator)

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

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

PyObject* PyArray_MultiIterNew(int num, ...)

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

void PyArray_MultiIter_RESET(PyObject* multi)

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

void PyArray_MultiIter_NEXT(PyObject* multi)

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

void *PyArray_MultiIter_DATA(PyObject* multi, int i)

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

void PyArray_MultiIter_NEXTi(PyObject* multi, int i)

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

void PyArray_MultiIter_GOTO(PyObject* multi, npy_intp* destination)

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

void PyArray_MultiIter_GOTO1D(PyObject* multi, npy_intp index)

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

int PyArray_MultiIter_NOTDONE(PyObject* multi)

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

int PyArray_Broadcast(PyArrayMultiIterObject* mit)

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

int PyArray_RemoveSmallest(PyArrayMultiIterObject* mit)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

int PyArrayNeighborhoodIter_Reset(PyArrayNeighborhoodIterObject* iter)

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

int PyArrayNeighborhoodIter_Next(PyArrayNeighborhoodIterObject* iter)

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

Масштабируемые массивы

PyObject* PyArray_Return(PyArrayObject* arr)

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

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

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

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

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

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

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

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

void PyArray_ScalarAsCtype(PyObject* scalar, void* ctypeptr)

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

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

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

PyObject* PyArray_TypeObjectFromType(int type)

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

NPY_SCALARKIND PyArray_ScalarKind(int typenum, PyArrayObject** arr)

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

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

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

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

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

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

int PyArray_DescrCheck(PyObject* obj)

Истинно, если obj — объект типа данных ( PyArray_Descr * ).

PyArray_Descr* PyArray_DescrNew(PyArray_Descr* obj)

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

PyArray_Descr* PyArray_DescrNewFromType(int typenum)

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

PyArray_Descr* PyArray_DescrNewByteorder(PyArray_Descr* obj, char newendian)

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

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

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

PyArray_Descr* PyArray_DescrFromScalar(PyObject* scalar)

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

PyArray_Descr* PyArray_DescrFromType(int typenum)

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

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

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

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

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

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

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

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

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

PyObject *PyArray_FieldNames(PyObject* dict)

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

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

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

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

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

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

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

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

int PyArray_IntpConverter(PyObject* obj, PyArray_Dims* seq)

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

int PyArray_BufferConverter(PyObject* obj, PyArray_Chunk* buf)

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

int PyArray_AxisConverter(PyObject * obj, int* axis)

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

int PyArray_BoolConverter(PyObject* obj, Bool* value)

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

int PyArray_ByteorderConverter(PyObject* obj, char* endian)

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

int PyArray_SortkindConverter(PyObject* obj, NPY_SORTKIND* sort)

Преобразует строки Python в один из NPY_QUICKSORT (начинается с ‘q’ или ‘Q’), NPY_HEAPSORT (начинается с ‘h’ или ‘H’), или NPY_MERGESORT (начинается с ‘m’ или ‘M’).

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)

New in version 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-ошибки), если один из назначаемых объектов не является вызываемым.

PyObject* PyArray_GetNumericOps(void)

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

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

PyDimMem_FREE(npy_intp* ptr)

npy_intp* PyDimMem_RENEW(npy_intp* ptr, npy_intp newnd)

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

PyArray_malloc(nbytes)

PyArray_free(ptr)

PyArray_realloc(ptr, nbytes)

Эти макросы используют разные выделения памяти, в зависимости от константы NPY_USE_PYMEM. Системный 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

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

NPY_ALLOW_C_API_DEF

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

NPY_ALLOW_C_API

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

NPY_DISABLE_C_API

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

Приоритет

NPY_PRIORITY

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

NPY_SUBTYPE_PRIORITY

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

NPY_SCALAR_PRIORITY

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

double PyArray_GetPriority(PyObject* obj, double def)

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

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

NPY_BUFSIZE

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

NPY_MIN_BUFSIZE

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

NPY_MAX_BUFSIZE

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

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

NPY_NUM_FLOATTYPE

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

NPY_MAXDIMS

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

NPY_VERSION

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

NPY_FALSE

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

NPY_TRUE

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

NPY_FAIL

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

NPY_SUCCEED

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

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

PyArray_SAMESHAPE(a1, a2)

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

PyArray_MAX(a, b)

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

PyArray_MIN(a, b)

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

PyArray_CLT(a, b)

PyArray_CGT(a, b)

PyArray_CLE(a, b)

PyArray_CGE(a, b)

PyArray_CEQ(a, b)

PyArray_CNE(a, b)

Реализует комплексные сравнения между двумя комплексными числами (структуры с членами 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

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

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

NPY_SORTKIND

Особый тип переменной, который может принимать значения NPY_{KIND} , где {KIND} это

QUICKSORT, HEAPSORT, MERGESORT

NPY_NSORTS

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

NPY_SCALARKIND

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

NOSCALAR, BOOL_SCALAR, INTPOS_SCALAR, INTNEG_SCALAR, FLOAT_SCALAR, COMPLEX_SCALAR, OBJECT_SCALAR

NPY_NSCALARKINDS

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

NPY_ORDER

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

NPY_ANYORDER

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

NPY_CORDER

Порядок C.

NPY_FORTRANORDER

Порядок Fortran.

NPY_KEEPORDER

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

NPY_CLIPMODE

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

NPY_RAISE

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

NPY_CLIP

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

NPY_WRAP

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

NPY_CASTING

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

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

NPY_NO_CASTING

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

NPY_EQUIV_CASTING

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

NPY_SAFE_CASTING

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

NPY_SAME_KIND_CASTING

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

NPY_UNSAFE_CASTING

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