Интерфейс API массивов

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

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

int PyArray_NDIM(PyArrayObject *arr)

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

npy_intp *PyArray_DIMS(PyArrayObject *arr)

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

npy_intp *PyArray_SHAPE(PyArrayObject *arr)

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

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

void *PyArray_DATA(PyArrayObject *arr)

char *PyArray_BYTES(PyArrayObject *arr)

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

npy_intp *PyArray_STRIDES(PyArrayObject* arr)

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

npy_intp PyArray_DIM(PyArrayObject* arr, int n)

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

npy_intp PyArray_STRIDE(PyArrayObject* arr, int n)

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

PyObject *PyArray_BASE(PyArrayObject* arr)

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

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

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

PyArray_Descr *PyArray_DESCR(PyArrayObject* arr)

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

PyArray_Descr *PyArray_DTYPE(PyArrayObject* arr)

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

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

void PyArray_ENABLEFLAGS(PyArrayObject* arr, int flags)

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

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

void PyArray_CLEARFLAGS(PyArrayObject* arr, int flags)

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

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

int PyArray_FLAGS(PyArrayObject* arr)

npy_intp PyArray_ITEMSIZE(PyArrayObject* arr)

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

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

int PyArray_TYPE(PyArrayObject* arr)

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

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

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

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

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

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

npy_intp PyArray_SIZE(PyArrayObject* arr)

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

npy_intp PyArray_Size(PyArrayObject* obj)

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

npy_intp PyArray_NBYTES(PyArrayObject* arr)

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

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

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

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

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

void* PyArray_GETPTR1(PyArrayObject* obj, npy_intp i)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

PyArray_FILLWBYTE(PyObject* obj, int val)

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

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

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

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

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

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

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

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

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

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

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

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

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

int PyArray_SetBaseObject(PyArrayObject* arr, PyObject* obj)

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

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

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

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

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

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

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

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

NPY_ARRAY_C_CONTIGUOUS

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

NPY_ARRAY_F_CONTIGUOUS

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

NPY_ARRAY_ALIGNED

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

NPY_ARRAY_WRITEABLE

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

NPY_ARRAY_ENSURECOPY

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

NPY_ARRAY_ENSUREARRAY

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

NPY_ARRAY_FORCECAST

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

NPY_ARRAY_WRITEBACKIFCOPY

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

NPY_ARRAY_UPDATEIFCOPY

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

NPY_ARRAY_BEHAVED

NPY_ARRAY_ALIGNED | NPY_ARRAY_WRITEABLE

NPY_ARRAY_CARRAY

NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_BEHAVED

NPY_ARRAY_CARRAY_RO

NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_ALIGNED

NPY_ARRAY_FARRAY

NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_BEHAVED

NPY_ARRAY_FARRAY_RO

NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_ALIGNED

NPY_ARRAY_DEFAULT

NPY_ARRAY_CARRAY

NPY_ARRAY_IN_ARRAY

NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_ALIGNED

NPY_ARRAY_IN_FARRAY

NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_ALIGNED

NPY_OUT_ARRAY

NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_WRITEABLE | NPY_ARRAY_ALIGNED

NPY_ARRAY_OUT_ARRAY

NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_ALIGNED | NPY_ARRAY_WRITEABLE

NPY_ARRAY_OUT_FARRAY

NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_WRITEABLE | NPY_ARRAY_ALIGNED

NPY_ARRAY_INOUT_ARRAY

NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_WRITEABLE | NPY_ARRAY_ALIGNED | NPY_ARRAY_WRITEBACKIFCOPY | NPY_ARRAY_UPDATEIFCOPY

NPY_ARRAY_INOUT_FARRAY

NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_WRITEABLE | NPY_ARRAY_ALIGNED | NPY_ARRAY_WRITEBACKIFCOPY | NPY_ARRAY_UPDATEIFCOPY

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

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

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

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

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

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

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

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

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

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

PyObject* PyArray_EnsureArray(PyObject* op)

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

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

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

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

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

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

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

int PyArray_CopyInto(PyArrayObject* dest, PyArrayObject* src)

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

int PyArray_MoveInto(PyArrayObject* dest, PyArrayObject* src)

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

PyArrayObject* PyArray_GETCONTIGUOUS(PyObject* op)

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

PyObject* PyArray_FROM_O(PyObject* obj)

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

PyObject* PyArray_FROM_OF(PyObject* obj, int requirements)

Аналогично PyArray_FROM_O, за исключением того, что он может принимать аргумент требований, указывающий свойства, которые должен иметь результирующий массив. Доступные требования, которые могут быть применены: 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= и работают должным образом с аргументом axis=None. Входной массив — obj, а *axis — преобразованное целое число (так что >=MAXDIMS — это значение None), и requirements задаёт необходимые свойства obj. Результат — преобразованная версия входного массива, которая соответствует требованиям, и, если необходимо, произошла уплощение. При выводе отрицательные значения *axis преобразуются, а новое значение проверяется на соответствие форме obj.

Работа с типами

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

PyArray_Check(PyObject *op)

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

PyArray_CheckExact(PyObject *op)

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

PyArray_HasArrayInterface(PyObject *op, PyObject *out)

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

PyArray_HasArrayInterfaceType(op, type, context, out)

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

PyArray_IsZeroDim(op)

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

PyArray_IsScalar(op, cls)

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

PyArray_CheckScalar(op)

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

PyArray_IsPythonNumber(op)

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

PyArray_IsPythonScalar(op)

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

PyArray_IsAnyScalar(op)

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

PyArray_CheckAnyScalar(op)

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

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

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

PyTypeNum_ISUNSIGNED(num)

PyDataType_ISUNSIGNED(descr)

PyArray_ISUNSIGNED(obj)

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

PyTypeNum_ISSIGNED(num)

PyDataType_ISSIGNED(descr)

PyArray_ISSIGNED(obj)

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

PyTypeNum_ISINTEGER(num)

PyDataType_ISINTEGER(descr)

PyArray_ISINTEGER(obj)

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

PyTypeNum_ISFLOAT(num)

PyDataType_ISFLOAT(descr)

PyArray_ISFLOAT(obj)

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

PyTypeNum_ISCOMPLEX(num)

PyDataType_ISCOMPLEX(descr)

PyArray_ISCOMPLEX(obj)

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

PyTypeNum_ISNUMBER(num)

PyDataType_ISNUMBER(descr)

PyArray_ISNUMBER(obj)

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

PyTypeNum_ISSTRING(num)

PyDataType_ISSTRING(descr)

PyArray_ISSTRING(obj)

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

PyTypeNum_ISPYTHON(num)

PyDataType_ISPYTHON(descr)

PyArray_ISPYTHON(obj)

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

PyTypeNum_ISFLEXIBLE(num)

PyDataType_ISFLEXIBLE(descr)

PyArray_ISFLEXIBLE(obj)

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

PyDataType_ISUNSIZED(descr):

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

PyTypeNum_ISUSERDEF(num)

PyDataType_ISUSERDEF(descr)

PyArray_ISUSERDEF(obj)

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

PyTypeNum_ISEXTENDED(num)

PyDataType_ISEXTENDED(descr)

PyArray_ISEXTENDED(obj)

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

PyTypeNum_ISOBJECT(num)

PyDataType_ISOBJECT(descr)

PyArray_ISOBJECT(obj)

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

PyTypeNum_ISBOOL(num)

PyDataType_ISBOOL(descr)

PyArray_ISBOOL(obj)

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

PyDataType_HASFIELDS(descr)

PyArray_HASFIELDS(obj)

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

PyArray_ISNOTSWAPPED(m)

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

PyArray_ISBYTESWAPPED(m)

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

Bool PyArray_EquivTypes(PyArray_Descr* type1, PyArray_Descr* type2)

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

Bool PyArray_EquivArrTypes(PyArrayObject* a1, PyArrayObject * a2)

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

Bool PyArray_EquivTypenums(int typenum1, int typenum2)

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

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

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

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

PyObject* PyArray_Cast(PyArrayObject* arr, int typenum)

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

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

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

int PyArray_CastTo(PyArrayObject* out, PyArrayObject* in)

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

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

PyArray_VectorUnaryFunc* PyArray_GetCastFunc(PyArray_Descr* from, int totype)

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

int PyArray_CanCastSafely(int fromtype, int totype)

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

int PyArray_CanCastTo(PyArray_Descr* fromtype, PyArray_Descr* totype)

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

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

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

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

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

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

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

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

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

PyArray_Descr* PyArray_MinScalarType(PyArrayObject* arr)

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

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

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

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

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

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

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

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

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

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

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

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

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

int PyArray_ObjectType(PyObject* op, int mintype)

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

Эта функция полезна для определения общего типа, к которому могут быть преобразованы два или более массивов. Она работает только для негибких типов массивов, так как никакая информация об itemsize не передаётся. Аргумент 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, в массив ndarray, каждый из которых имеет одинаковый тип данных. Тип выбирается на основе номера типа (выбирается больший номер типа вместо меньшего), игнорируя объекты, которые являются только скалярами. Длина последовательности возвращается в 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)

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

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

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

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

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

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

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

int PyArray_INCREF(PyArrayObject* op)

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

void PyArray_Item_INCREF(char* ptr, PyArray_Descr* dtype)

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

int PyArray_XDECREF(PyArrayObject* op)

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

void PyArray_Item_XDECREF(char* ptr, PyArray_Descr* dtype)

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

void PyArray_FillObjectArray(PyArrayObject* arr, PyObject* obj)

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

int PyArray_SetUpdateIfCopyBase(PyArrayObject* arr, PyArrayObject* base)

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

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

int PyArray_SetWritebackIfCopyBase(PyArrayObject* arr, PyArrayObject* base)

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

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

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

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

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

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

Флаги базового массива

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

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

NPY_ARRAY_C_CONTIGUOUS

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

NPY_ARRAY_F_CONTIGUOUS

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

NPY_ARRAY_OWNDATA

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

NPY_ARRAY_ALIGNED

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

NPY_ARRAY_WRITEABLE

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

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

NPY_ARRAY_WRITEBACKIFCOPY

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

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

NPY_ARRAY_UPDATEIFCOPY

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

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

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

NPY_ARRAY_BEHAVED

NPY_ARRAY_ALIGNED | NPY_ARRAY_WRITEABLE

NPY_ARRAY_CARRAY

NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_BEHAVED

NPY_ARRAY_CARRAY_RO

NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_ALIGNED

NPY_ARRAY_FARRAY

NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_BEHAVED

NPY_ARRAY_FARRAY_RO

NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_ALIGNED

NPY_ARRAY_DEFAULT

NPY_ARRAY_CARRAY

NPY_ARRAY_UPDATE_ALL

NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_ALIGNED

Флаги-константы

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

NPY_ARRAY_FORCECAST

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

NPY_ARRAY_ENSURECOPY

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

NPY_ARRAY_ENSUREARRAY

Убедиться, что результирующий объект является фактическим ndarray, а не подклассом.

NPY_ARRAY_NOTSWAPPED

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

NPY_ARRAY_BEHAVED_NS

NPY_ARRAY_ALIGNED | NPY_ARRAY_WRITEABLE | NPY_ARRAY_NOTSWAPPED

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

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

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

Возвращает истину, если arr контигуален по стилю C.

PyArray_IS_F_CONTIGUOUS(arr)

Возвращает истину, если arr контигуален по стилю Fortran.

PyArray_ISFORTRAN(arr)

Возвращает true, если arr является массивом с фортран-стилевым упорядочением (и не является массивом с c-стилевым упорядочением). PyArray_IS_F_CONTIGUOUS — правильный способ проверить фортран-стилевое упорядочение.

PyArray_ISWRITEABLE(arr)

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

PyArray_ISALIGNED(arr)

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

PyArray_ISBEHAVED(arr)

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

PyArray_ISBEHAVED_RO(arr)

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

PyArray_ISCARRAY(arr)

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

PyArray_ISFARRAY(arr)

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

PyArray_ISCARRAY_RO(arr)

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

PyArray_ISFARRAY_RO(arr)

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

PyArray_ISONESEGMENT(arr)

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

void PyArray_UpdateFlags(PyArrayObject* arr, int flagmask)

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

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

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

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

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

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

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

PyObject* PyArray_Byteswap(PyArrayObject* self, Bool inplace)

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

PyObject* PyArray_NewCopy(PyArrayObject* old, NPY_ORDER order)

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

PyObject* PyArray_ToList(PyArrayObject* self)

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

PyObject* PyArray_ToString(PyArrayObject* self, NPY_ORDER order)

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

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

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

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

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

PyObject* PyArray_Dumps(PyObject* self, int protocol)

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

int PyArray_FillWithScalar(PyArrayObject* arr, PyObject* obj)

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

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

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

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

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

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

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

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

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

PyObject* PyArray_Squeeze(PyArrayObject* self)

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

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

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

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

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

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

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

PyObject* PyArray_Flatten(PyArrayObject* self, NPY_ORDER order)

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

PyObject* PyArray_Ravel(PyArrayObject* self, NPY_ORDER order)

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

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

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

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

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

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

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

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

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

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

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

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

NPY_RAISE

вызвать ValueError;

NPY_WRAP

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

NPY_CLIP

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

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

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

PyObject* PyArray_ArgSort(PyArrayObject* self, int axis)

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

PyObject* PyArray_LexSort(PyObject* sort_keys, int axis)

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

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

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

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

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

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

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

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

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

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

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

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

npy_intp PyArray_CountNonzero(PyArrayObject* self)

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

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

PyObject* PyArray_Nonzero(PyArrayObject* self)

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

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

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

Расчёт

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

PyObject* PyArray_Conjugate(PyArrayObject* self)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Функции

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

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

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

Параметры:

op – Адрес любого объекта Python. Этот объект Python будет заменён эквивалентным корректным, непрерывным массивом ndarray в стиле C заданного типа данных, указанного в двух последних аргументах. Убедитесь, что взятие ссылки на входной объект таким образом оправдано. ptr – Адрес переменной (ctype* для 1-мерного, ctype** для 2-мерного или ctype*** для 3-мерного), где ctype — эквивалентный тип C для типа данных. При возврате ptr будет адресован как 1-мерный, 2-мерный или 3-мерный массив. dims – Выходной массив, содержащий форму массива объекта. Этот массив задаёт границы любого цикла, который будет выполняться. nd – Размерность массива (1, 2 или 3). typenum – Ожидаемый тип данных массива. itemsize – Этот аргумент нужен только тогда, когда typenum представляет гибкий массив. В противном случае он должен быть 0.

int PyArray_Free(PyObject* op, void* ptr)

Необходимо вызывать с теми же объектами и местами памяти, возвращёнными из PyArray_AsCArray (…). Эта функция очищает память, которая в противном случае могла бы быть потеряна.

PyObject* PyArray_Concatenate(PyObject* obj, int axis)

Объединить последовательность объектов в obj вместе вдоль axis в один массив. Если размерности или типы не совместимы, генерируется ошибка.

PyObject* PyArray_InnerProduct(PyObject* obj1, PyObject* obj2)

Вычислить произведение-сумму по последним измерениям obj1 и obj2. Ни один массив не сопряжён.

PyObject* PyArray_MatrixProduct(PyObject* obj1, PyObject* obj)

Вычислить произведение-сумму по последнему измерению obj1 и предпоследнему измерению obj2. Для 2-мерных массивов это матричное произведение. Ни один массив не сопряжён.

PyObject* PyArray_MatrixProduct2(PyObject* obj1, PyObject* obj, PyArrayObject* out)

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

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

PyObject* PyArray_EinsteinSum(char* subscripts, npy_intp nop, PyArrayObject** op_in, PyArray_Descr* dtype, NPY_ORDER order, NPY_CASTING casting, PyArrayObject* out)

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

Применяет соглашение об индексации Эйнштейна к предоставленным операндам массива, возвращая новый массив или помещая результат в out. Строка в subscripts — это список индексов букв, разделённых запятыми. Количество операндов в nop, и op_in — массив, содержащий эти операнды. Тип данных выходных данных можно принудительно задать с помощью dtype, порядок выходных данных можно принудительно задать с помощью order (NPY_KEEPORDER рекомендуется), и когда задан dtype, casting указывает, насколько разрешительным должно быть преобразование данных.

См. функцию einsum для получения дополнительной информации.

PyObject* PyArray_CopyAndTranspose(PyObject * op)

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

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

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

Примечания

Это не вычисляет обычную корреляцию: если op2 больше, чем op1, аргументы меняются местами, и сопряжение никогда не берется для комплексных массивов. См. PyArray_Correlate2 для обычной корреляции обработки сигналов.

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

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

Примечания

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

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

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

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

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

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

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

npy_intp PyArray_MultiplyList(npy_intp const* seq, int n)

int PyArray_MultiplyIntList(int const* seq, int n)

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

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

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

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

NpyAuxData

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

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

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

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

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

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

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

    return (NpyAuxData *)ret;
}

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

    return (NpyAuxData *)ret;
}

NpyAuxData_FreeFunc

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

NpyAuxData_CloneFunc

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

NPY_AUXDATA_FREE(auxdata)

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

NPY_AUXDATA_CLONE(auxdata)

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

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

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

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

void *PyArray_ITER_DATA(PyObject* iterator)

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

void PyArray_ITER_GOTO(PyObject* iterator, npy_intp* destination)

Устанавливает индекс iterator, dataptr и члены координат в местоположение в массиве, указанное многомерным массивом 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.

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

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

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

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

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

Режим должен быть одним из следующих:

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

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

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

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

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

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

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

int PyArrayNeighborhoodIter_Reset(PyArrayNeighborhoodIterObject* iter)

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

int PyArrayNeighborhoodIter_Next(PyArrayNeighborhoodIterObject* iter)

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

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

PyObject* PyArray_Return(PyArrayObject* arr)

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

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

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

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

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

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

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

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

void PyArray_ScalarAsCtype(PyObject* scalar, void* ctypeptr)

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

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

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

PyObject* PyArray_TypeObjectFromType(int type)

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

NPY_SCALARKIND PyArray_ScalarKind(int typenum, PyArrayObject** arr)

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

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

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

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

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

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

int PyArray_DescrCheck(PyObject* obj)

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

PyArray_Descr* PyArray_DescrNew(PyArray_Descr* obj)

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

PyArray_Descr* PyArray_DescrNewFromType(int typenum)

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

PyArray_Descr* PyArray_DescrNewByteorder(PyArray_Descr* obj, char newendian)

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

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

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

PyArray_Descr* PyArray_DescrFromScalar(PyObject* scalar)

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

PyArray_Descr* PyArray_DescrFromType(int typenum)

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

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

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

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

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

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

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

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

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

PyObject *PyArray_FieldNames(PyObject* dict)

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

Утилиты преобразования

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

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

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

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

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

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

int PyArray_IntpConverter(PyObject* obj, PyArray_Dims* seq)

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

int PyArray_BufferConverter(PyObject* obj, PyArray_Chunk* buf)

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

int PyArray_AxisConverter(PyObject * obj, int* axis)

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

int PyArray_BoolConverter(PyObject* obj, Bool* value)

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

int PyArray_ByteorderConverter(PyObject* obj, char* endian)

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

int PyArray_SortkindConverter(PyObject* obj, NPY_SORTKIND* sort)

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

int PyArray_SearchsideConverter(PyObject* obj, NPY_SEARCHSIDE* side)

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

int PyArray_OrderConverter(PyObject* obj, NPY_ORDER* order)

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

int PyArray_CastingConverter(PyObject* obj, NPY_CASTING* casting)

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

int PyArray_ClipmodeConverter(PyObject* object, NPY_CLIPMODE* val)

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

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

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

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

int PyArray_PyIntAsInt(PyObject* op)

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

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

npy_intp PyArray_PyIntAsIntp(PyObject* op)

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

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

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

int PyArray_TypestrConvert(int itemsize, int gentype)

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

Разное

Импорт API

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

void import_array(void)

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

PY_ARRAY_UNIQUE_SYMBOL

NO_IMPORT_ARRAY

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

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

#define PY_ARRAY_UNIQUE_SYMBOL cool_ARRAY_API
#include numpy/arrayobject.h

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

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

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

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

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

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

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

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

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

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

unsigned int PyArray_GetNDArrayCVersion(void)

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

unsigned int PyArray_GetNDArrayCFeatureVersion(void)

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

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

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

int PyArray_SetNumericOps(PyObject* dict)

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

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

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

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

PyObject* PyArray_GetNumericOps(void)

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

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

void PyArray_SetStringFunction(PyObject* op, int repr)

Эта функция позволяет изменить методы tp_str и tp_repr объекта массива на любую функцию Python. Таким образом, вы можете изменить поведение всех массивов при вызове str(arr) или repr(arr) из Python. Вызываемая функция передаётся в качестве op. Если repr отлично от нуля, то эта функция будет вызываться в ответ на repr(arr), в противном случае функция будет вызываться в ответ на str(arr). Проверка на то, является ли op вызываемой функцией, не выполняется. Передаваемая в op вызываемая функция должна принимать массив в качестве аргумента и возвращать строку для вывода.

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

char* PyDataMem_NEW(size_t nbytes)

PyDataMem_FREE(char* ptr)

char* PyDataMem_RENEW(void * ptr, size_t newbytes)

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

npy_intp* PyDimMem_NEW(int nd)

PyDimMem_FREE(char* ptr)

npy_intp* PyDimMem_RENEW(void* ptr, size_t newnd)

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

void* PyArray_malloc(size_t nbytes)

PyArray_free(void* ptr)

void* PyArray_realloc(npy_intp* ptr, size_t nbytes)

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

int PyArray_ResolveWritebackIfCopy(PyArrayObject* obj)

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

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

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

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

Группа 1

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

NPY_BEGIN_ALLOW_THREADS

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

NPY_END_ALLOW_THREADS

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

NPY_BEGIN_THREADS_DEF

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

NPY_BEGIN_THREADS

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

NPY_END_THREADS

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

NPY_BEGIN_THREADS_DESCR(PyArray_Descr *dtype)

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

NPY_END_THREADS_DESCR(PyArray_Descr *dtype)

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

NPY_BEGIN_THREADS_THRESHOLDED(int loop_size)

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

Группа 2

Эта группа используется для повторного приобретения GIL после его освобождения. Например, предположим, что 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__ (преобразованный в двойное значение) объекта 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(PyArrayObject *a1, PyArrayObject *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 значения 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 в базовом объекте. Это полезно для восстановления от ошибки при использовании семантики записи, но может привести к неправильным результатам.

Перечисление типов

NPY_SORTKIND

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

QUICKSORT, HEAPSORT, MERGESORT, STABLESORT

NPY_NSORTS

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

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

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