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

В версиях 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’, установите boolean ‘writeable’ в 1. Это вызывает ошибку, когда ‘op’ является скаляром, списком списков или другим не-записываемым ‘op’. Это отличается от передачи NPY_ARRAY_WRITEABLE в PyArray_FromAny, где изменяемый массив может быть копией входных данных.

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

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

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

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

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

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

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

NPY_ARRAY_NOTSWAPPED

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

NPY_ARRAY_BEHAVED_NS

NPY_ARRAY_ALIGNED | NPY_ARRAY_WRITEABLE | NPY_ARRAY_NOTSWAPPED

NPY_ARRAY_ELEMENTSTRIDES

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

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

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

PyObject* PyArray_FromStructInterface(PyObject* op)

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

PyObject* PyArray_FromInterface(PyObject* op)

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

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

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

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

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

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

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

PyObject* PyArray_EnsureArray(PyObject* op)

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

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

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

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

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

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

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

int PyArray_CopyInto(PyArrayObject* dest, PyArrayObject* src)

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

int PyArray_MoveInto(PyArrayObject* dest, PyArrayObject* src)

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

PyArrayObject* PyArray_GETCONTIGUOUS(PyObject* op)

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

PyObject* PyArray_FROM_O(PyObject* obj)

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

PyObject* PyArray_FROM_OF(PyObject* obj, int requirements)

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

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

PyObject* PyArray_Cast(PyArrayObject* arr, int typenum)

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

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

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

int PyArray_CastTo(PyArrayObject* out, PyArrayObject* in)

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

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

PyArray_VectorUnaryFunc* PyArray_GetCastFunc(PyArray_Descr* from, int totype)

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

int PyArray_CanCastSafely(int fromtype, int totype)

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

int PyArray_CanCastTo(PyArray_Descr* fromtype, PyArray_Descr* totype)

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

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

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

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

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

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

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

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

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

PyArray_Descr* PyArray_MinScalarType(PyArrayObject* arr)

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

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

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

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

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

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

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

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

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

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

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

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

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

int PyArray_ObjectType(PyObject* op, int mintype)

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

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

void PyArray_ArrayType(PyObject* op, PyArray_Descr* mintype, PyArray_Descr* outtype)

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

Эта функция работает аналогично PyArray_ObjectType (…), за исключением того, что она обрабатывает гибкие массивы. Аргумент mintype может иметь член itemsize, а аргумент outtype будет иметь член itemsize, по крайней мере, такого же размера, но, возможно, большего, в зависимости от объекта op.

PyArrayObject** PyArray_ConvertToCommonType(PyObject* op, int* n)

Функциональность, которую она предоставляет, в значительной степени устарела и заменена итератором NpyIter, представленным в версии 1.6, с флагом NPY_ITER_COMMON_DTYPE или с одинаковым параметром dtype для всех операндов.

Преобразуйте последовательность Python-объектов, содержащихся в op, в массив ndarrays, каждый из которых имеет одинаковый тип данных. Тип выбирается на основе номера типа (выбирается больший номер типа по сравнению с меньшим), игнорируя объекты, которые являются только скалярами. Длина последовательности возвращается в n, а возвращаемым значением является массив длины n указателей на PyArrayObject (или NULL, если произошла ошибка). Возвращаемый массив должен быть освобождён вызывающей стороной этой функции (с помощью PyDataMem_FREE ), и все массивы в нём DECREF , иначе произойдёт утечка памяти. Приведённый ниже пример кода демонстрирует типичное использование:

mps = PyArray_ConvertToCommonType(obj, &n);
if (mps==NULL) return NULL;
{code}
<before return>
for (i=0; i<n; i++) Py_DECREF(mps[i]);
PyDataMem_FREE(mps);
{return}

char* PyArray_Zero(PyArrayObject* arr)

Указатель на вновь созданную память размером arr ->itemsize, которая содержит представление 0 для этого типа. Возвращённый указатель ret должен быть освобождён с помощью PyDataMem_FREE (ret), когда он больше не нужен.

char* PyArray_One(PyArrayObject* arr)

Указатель на вновь созданную память размером arr ->itemsize, которая содержит представление 1 для этого типа. Возвращённый указатель ret должен быть освобождён с помощью PyDataMem_FREE (ret), когда он больше не нужен.

int PyArray_ValidType(int typenum)

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

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

void PyArray_InitArrFuncs(PyArray_ArrFuncs* f)

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

int PyArray_RegisterDataType(PyArray_Descr* dtype)

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

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

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

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

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

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

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

int PyArray_INCREF(PyArrayObject* op)

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

void PyArray_Item_INCREF(char* ptr, PyArray_Descr* dtype)

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

int PyArray_XDECREF(PyArrayObject* op)

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

void PyArray_Item_XDECREF(char* ptr, PyArray_Descr* dtype)

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

void PyArray_FillObjectArray(PyArrayObject* arr, PyObject* obj)

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

int PyArray_SetUpdateIfCopyBase(PyArrayObject* arr, PyArrayObject* base)

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

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

int PyArray_SetWritebackIfCopyBase(PyArrayObject* arr, PyArrayObject* base)

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

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

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

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

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

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

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

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

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

NPY_ARRAY_C_CONTIGUOUS

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

NPY_ARRAY_F_CONTIGUOUS

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

NPY_ARRAY_OWNDATA

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

NPY_ARRAY_ALIGNED

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

NPY_ARRAY_WRITEABLE

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

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

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)

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

PyArray_ISWRITEABLE(arr)

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

PyArray_ISALIGNED(arr)

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

PyArray_ISBEHAVED(arr)

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

PyArray_ISBEHAVED_RO(arr)

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

PyArray_ISCARRAY(arr)

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

PyArray_ISFARRAY(arr)

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

PyArray_ISCARRAY_RO(arr)

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

PyArray_ISFARRAY_RO(arr)

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

PyArray_ISONESEGMENT(arr)

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

void PyArray_UpdateFlags(PyArrayObject* arr, int flagmask)

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

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

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

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

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

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

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

PyObject* PyArray_Byteswap(PyArrayObject* self, Bool inplace)

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

PyObject* PyArray_NewCopy(PyArrayObject* old, NPY_ORDER order)

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

PyObject* PyArray_ToList(PyArrayObject* self)

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

PyObject* PyArray_ToString(PyArrayObject* self, NPY_ORDER order)

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

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

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

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

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

PyObject* PyArray_Dumps(PyObject* self, int protocol)

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

int PyArray_FillWithScalar(PyArrayObject* arr, PyObject* obj)

Заполняет массив arr заданным скалярным объектом obj. Объект сначала преобразуется в тип данных arr, а затем копируется в каждое местоположение. -1 возвращается, если произошла ошибка, в противном случае возвращается 0.

PyObject* PyArray_View(PyArrayObject* self, PyArray_Descr* dtype, PyTypeObject *ptype)

Эквивалентно ndarray.view (self, dtype). Возвращает новый вид массива self как, возможно, другого типа данных dtype и другого подкласса массива ptype.

Если dtype равно NULL, возвращаемый массив будет иметь тот же тип данных, что и self. Новый тип данных должен быть согласован с размером self. Либо размеры элементов должны быть идентичны, либо self должен быть односегментным, и общее количество байтов должно быть одинаковым. В последнем случае размерности возвращаемого массива будут изменены в последней (или первой для массивов с непрерывной структурой Fortran) размерности. Область данных возвращаемого массива и self абсолютно одинаковы.

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

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

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

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

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

PyObject* PyArray_Squeeze(PyArrayObject* self)

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

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

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

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

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

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

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

PyObject* PyArray_Flatten(PyArrayObject* self, NPY_ORDER order)

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

PyObject* PyArray_Ravel(PyArrayObject* self, NPY_ORDER order)

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

Выбор элементов и манипуляции

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

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

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

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

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

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

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

npy_intp PyArray_CountNonzero(PyArrayObject* self)

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

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

PyObject* PyArray_Nonzero(PyArrayObject* self)

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

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

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

Вычисление

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

PyObject* PyArray_Conjugate(PyArrayObject* self)

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

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

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

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

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

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

Эквивалентно ndarray.sum (self, axis, rtype). Возвращает суммы элементов в 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, чтобы алгоритмы могли использовать синтаксис C’s a[i][j][k]. Эта функция возвращает указатель ptr, который моделирует такой массив в стиле C для одномерных, двумерных и трехмерных массивов.

Параметры:

op – Адрес любого объекта Python. Этот объект Python будет заменён эквивалентным хорошо себя ведущим, непрерывным в стиле C массивом ndarray заданного типа, указанного двумя последними аргументами. Убедитесь, что взятие ссылки на входной объект таким образом оправдано. ptr – Адрес (ctype* для 1-мерного, ctype** для 2-мерного или ctype*** для 3-мерного) переменной, где ctype — эквивалентный тип C для типа данных. По возвращении ptr будет доступен как одномерный, двумерный или трехмерный массив. 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. Для двумерных массивов это матричное произведение. Ни один массив не конъюгируется.

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)

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

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

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

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

NpyAuxData

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

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

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

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

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

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

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

    return (NpyAuxData *)ret;
}

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

    return (NpyAuxData *)ret;
}

NpyAuxData_FreeFunc

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

NpyAuxData_CloneFunc

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

NPY_AUXDATA_FREE(auxdata)

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

NPY_AUXDATA_CLONE(auxdata)

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

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

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

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

PyObject* PyArray_IterNew(PyObject* arr)

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

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

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

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

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

int PyArrayIter_Check(PyObject* op)

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

void PyArray_ITER_RESET(PyObject* iterator)

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

void PyArray_ITER_NEXT(PyObject* iterator)

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

void *PyArray_ITER_DATA(PyObject* iterator)

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

void PyArray_ITER_GOTO(PyObject* iterator, npy_intp* destination)

Устанавливает индекс 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[-2] будет 1, x[4] будет 4, x[5] будет 1 и т. д…
• NPY_NEIGHBORHOOD_ITER_CIRCULAR_PADDING: циклическое заполнение. Значения за пределами границ будут такими, как если бы массив повторялся. Например, для массива [1, 2, 3, 4], x[-2] будет 3, x[-2] будет 4, x[4] будет 1, x[5] будет 2 и т. д…

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

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

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

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

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

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

int PyArrayNeighborhoodIter_Reset(PyArrayNeighborhoodIterObject* iter)

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

int PyArrayNeighborhoodIter_Next(PyArrayNeighborhoodIterObject* iter)

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

Масштабы массивов

PyObject* PyArray_Return(PyArrayObject* arr)

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

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

Реализует правила приведения скаляров. Скаляры приводятся к нужному типу только в том случае, если эта функция возвращает ненулевое значение. Если скаляр 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_QUICKSORT (начинается с ‘m’ или ‘M’).

int PyArray_SearchsideConverter(PyObject* obj, NPY_SEARCHSIDE* side)

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

int PyArray_OrderConverter(PyObject* obj, NPY_ORDER* order)

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

int PyArray_CastingConverter(PyObject* obj, NPY_CASTING* casting)

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

int PyArray_ClipmodeConverter(PyObject* object, NPY_CLIPMODE* val)

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

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

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

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

int PyArray_PyIntAsInt(PyObject* op)

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

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

npy_intp PyArray_PyIntAsIntp(PyObject* op)

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

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

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

int PyArray_TypestrConvert(int itemsize, int gentype)

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

Разное

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

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

void import_array(void)

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

PY_ARRAY_UNIQUE_SYMBOL

NO_IMPORT_ARRAY

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

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

#define PY_ARRAY_UNIQUE_SYMBOL cool_ARRAY_API
#include numpy/arrayobject.h

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

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

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

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

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

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

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

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

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

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

unsigned int PyArray_GetNDArrayCVersion(void)

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

unsigned int PyArray_GetNDArrayCFeatureVersion(void)

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

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

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

int PyArray_SetNumericOps(PyObject* dict)

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

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

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

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

int PyArray_ResolveWritebackIfCopy(PyArrayObject* obj)

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

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

Поддержка многопоточности

Эти макросы имеют смысл только если NPY_ALLOW_THREADS принимает значение True во время компиляции модуля расширения. В противном случае эти макросы эквивалентны пробелу. Python использует единый глобальный интерпретаторский замок (GIL) для каждого процесса Python, так что только один поток может выполняться одновременно (даже на многоядерных машинах). При вызове скомпилированной функции, которая может занимать много времени (и не имеет побочных эффектов для других потоков, таких как обновление глобальных переменных), следует освободить GIL, чтобы другие потоки Python могли выполняться во время выполнения трудоёмких вычислений. Это можно сделать с помощью двух групп макросов. Обычно, если в блоке кода используется один макрос из группы, все они должны использоваться в том же блоке кода. В настоящее время NPY_ALLOW_THREADS определён как константа WITH_THREADS, определённая Python, если переменная среды NPY_NOSMP не установлена, в противном случае NPY_ALLOW_THREADS определяется как 0.

Группа 1

Эта группа используется для вызова кода, который может занимать некоторое время, но не использует вызовы Python C-API. Таким образом, GIL следует освободить во время вычисления.

NPY_BEGIN_ALLOW_THREADS

Эквивалентно Py_BEGIN_ALLOW_THREADS, за исключением того, что оно использует NPY_ALLOW_THREADS для определения, заменяется ли макрос пробелом или нет.

NPY_END_ALLOW_THREADS

Эквивалентно Py_END_ALLOW_THREADS, за исключением того, что оно использует NPY_ALLOW_THREADS для определения, заменяется ли макрос пробелом или нет.

NPY_BEGIN_THREADS_DEF

Разместите в области объявления переменной. Этот макрос подготавливает переменную для хранения состояния Python.

NPY_BEGIN_THREADS

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

NPY_END_THREADS

Разместите непосредственно после кода, не требующего интерпретатора Python. Этот макрос приобретает GIL и восстанавливает состояние Python из сохранённой переменной.

NPY_BEGIN_THREADS_DESCR(PyArray_Descr *dtype)

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

NPY_END_THREADS_DESCR(PyArray_Descr *dtype)

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

NPY_BEGIN_THREADS_THRESHOLDED(int loop_size)

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

Группа 2

Эта группа используется для повторного получения GIL 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

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