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

Интерфейс массива (иногда называемый протоколом массива) был создан в 2005 году, как средство для похожих на массив Python-объектов для разумного повторного использования буферов данных друг друга, когда это возможно. Гомогенный N-мерный интерфейс массива — это механизм по умолчанию для объектов для совместного использования памяти и информации N-мерного массива. Интерфейс состоит из стороны Python и стороны C, используя два атрибута. Объекты, которые хотят считаться N-мерным массивом в прикладном коде, должны поддерживать как минимум один из этих атрибутов. Объекты, которые хотят поддерживать N-мерный массив в прикладном коде, должны искать как минимум один из этих атрибутов и использовать предоставленную информацию соответствующим образом.

Этот интерфейс описывает однородные массивы в том смысле, что каждый элемент массива имеет тот же «тип». Этот тип может быть очень простым или довольно произвольным и сложным, похожим на структуру C.

Существует два способа использования интерфейса: со стороны Python и со стороны C. Оба являются отдельными атрибутами.

Сторона Python

Этот подход к интерфейсу состоит из объекта, имеющего атрибут __array_interface__.

__array_interface__

Словарь элементов (3 обязательных и 5 необязательных). Необязательные ключи в словаре имеют подразумеваемые значения по умолчанию, если они не предоставлены.

Ключи:

shape (обязательно)

Кортеж, элементы которого представляют размер массива в каждом измерении. Каждый элемент — целое число (Python int или long). Обратите внимание, что эти целые числа могут быть больше, чем может содержать платформа «int» или «long» (Python int — это C long). Код, использующий этот атрибут, должен уметь правильно обрабатывать это; либо вызывая ошибку, когда возможен переполнение, либо используя Py_LONG_LONG в качестве типа C для размеров.

typestr (обязательно)

Строка, предоставляющая базовый тип однородного массива. Базовый формат строки состоит из 3 частей: символ, описывающий порядок байтов данных (<: little-endian, >: big-endian, |: не относится), символ, указывающий базовый тип массива, и целое число, указывающее количество байтов, используемых типом.

Основные символы типа:

t	Поле бита (последующее целое число указывает количество битов в поле бита).
b	Булево (целочисленный тип, где все значения — только True или False)
i	Целое число
u	Беззнаковое целое число
f	Число с плавающей точкой
c	Комплексное число с плавающей точкой
m	Timedelta
M	Datetime
O	Объект (т. е. память содержит указатель на PyObject)
S	Строка (фиксированная последовательность символов)
U	Unicode (фиксированная последовательность Py_UNICODE)
V	Другое (void * — каждый элемент — фиксированный блок памяти)

descr (необязательно)

Список кортежей, предоставляющий более подробное описание макета памяти для каждого элемента однородного массива. Каждый кортеж в списке имеет два или три элемента. Обычно этот атрибут используется, когда typestr равен V[0-9]+, но это не является обязательным. Единственное требование — количество байтов, представленных в ключе typestr, должно совпадать с общим количеством байтов, представленных здесь. Идея состоит в том, чтобы поддержать описания структур C-подобных типов, которые составляют элементы массива. Элементы каждого кортежа в списке:

1. Строка, предоставляющая имя, связанное с этой частью типа данных. Это также может быть кортеж из ('full name', 'basic_name') где базовое имя является допустимым именем Python-переменной, представляющей полное имя поля.
2. Либо строка описания базового типа, как в typestr, либо другой список (для вложенных типов структур)
3. Необязательный кортеж shapes, указывающий, сколько раз эта часть структуры должна повторяться. Если этого не указано, повторений не предполагается. Очень сложные структуры могут быть описаны с использованием этого универсального интерфейса. Обратите внимание, однако, что каждый элемент массива по-прежнему имеет один и тот же тип данных.

По умолчанию: [('', typestr)]

data (необязательно)

Двухэлементный кортеж, первый элемент которого — целое число (целое число long, если необходимо), указывающее на область данных, хранящую содержимое массива. Этот указатель должен указывать на первый элемент данных (другими словами, любые смещения игнорируются в этом случае). Второй элемент кортежа — флаг только для чтения (true означает, что область данных только для чтения).

Этот атрибут также может быть объектом, предоставляющим buffer interface, который будет использоваться для совместного использования данных. Если этот ключ отсутствует (или возвращает None), то совместное использование памяти будет выполнено через интерфейс буфера самого объекта. В этом случае ключ offset может использоваться для указания начала буфера. Ссылка на объект, предоставляющий интерфейс массива, должна храниться новым объектом, если область памяти должна быть защищена.

По умолчанию: None

strides (необязательно)

Либо None для указания массива, расположенного в C-стиле, либо кортеж шагов, который предоставляет количество байтов, необходимых для перехода к следующему элементу массива в соответствующем измерении. Каждый элемент должен быть целым числом (Python int или long). Как и в случае с shape, значения могут быть больше, чем может представлять C «int» или «long»; вызывающий код должен правильно обработать это, либо вызвав ошибку, либо используя Py_LONG_LONG в C. По умолчанию None означает буфер памяти, расположенный в стиле C. В этой модели последнее измерение массива изменяется быстрее всего. Например, кортеж шагов по умолчанию для объекта, элементы которого имеют длину 8 байтов, а форма (10,20,30) — (4800, 240, 8)

По умолчанию: None (непрерывный в стиле C)

mask (необязательно)

None или объект, предоставляющий интерфейс массива. Все элементы массива маски должны интерпретироваться только как истинные или ложные, указывая, какие элементы этого массива действительны. Форма этого объекта должна быть “broadcastable” к форме исходного массива.

По умолчанию: None (Все значения массива действительны)

offset (необязательно)

Смещение в области данных массива. Это может быть использовано только когда данные None или возвращает объект buffer.

По умолчанию: 0.

version (обязательно)

Целое число, показывающее версию интерфейса (т. е. 3 для этой версии). Будьте внимательны, не используйте это для аннулирования объектов, предоставляющих будущие версии интерфейса.

Доступ к C-структуре

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

__array_struct__

Тип :c:type: PyCObject , член voidptr которого содержит указатель на заполненную структуру PyArrayInterface. Память для структуры создается динамически, а для PyCObject также создается соответствующий деструктор, поэтому получатель этого атрибута просто должен применить Py_DECREF к объекту, возвращаемому этим атрибутом, по завершении. Кроме того, либо данные необходимо скопировать, либо должна быть сохранена ссылка на объект, предоставляющий этот атрибут, чтобы убедиться, что данные не освобождаются. Объекты, предоставляющие интерфейс __array_struct__ , также не должны перераспределять свою память, если они ссылаются на них другие объекты.

Структура PyArrayInterface определена в numpy/ndarrayobject.h как:

typedef struct {
  int two;              /* contains the integer 2 -- simple sanity check */
  int nd;               /* number of dimensions */
  char typekind;        /* kind in array --- character code of typestr */
  int itemsize;         /* size of each element */
  int flags;            /* flags indicating how the data should be interpreted */
                        /*   must set ARR_HAS_DESCR bit to validate descr */
  Py_intptr_t *shape;   /* A length-nd array of shape information */
  Py_intptr_t *strides; /* A length-nd array of stride information */
  void *data;           /* A pointer to the first element of the array */
  PyObject *descr;      /* NULL or data-description (same as descr key
                                of __array_interface__) -- must set ARR_HAS_DESCR
                                flag or this will be ignored. */
} PyArrayInterface;

Член flags может состоять из 5 битов, показывающих, как должны быть интерпретированы данные, и одного бита, показывающего, как должен быть интерпретирован интерфейс. Бит данных — это CONTIGUOUS (0x1), FORTRAN (0x2), ALIGNED (0x100), NOTSWAPPED (0x200) и WRITEABLE (0x400). Конечный флаг ARR_HAS_DESCR (0x800) указывает, содержит ли эта структура поле arrdescr.

Примеры описания типа

Для ясности полезно привести несколько примеров описания типа и соответствующих записей ‘descr’ для __array_interface__. Спасибо Скотту Гильберту за эти примеры:

В каждом случае ключ ‘descr’ является необязательным, но, конечно, предоставляет больше информации, которая может быть важной для различных приложений:

* Float data
    typestr == '>f4'
    descr == [('','>f4')]

* Complex double
    typestr == '>c8'
    descr == [('real','>f4'), ('imag','>f4')]

* RGB Pixel data
    typestr == '|V3'
    descr == [('r','|u1'), ('g','|u1'), ('b','|u1')]

* Mixed endian (weird but could happen).
    typestr == '|V8' (or '>u8')
    descr == [('big','>i4'), ('little','<i4')]

* Nested structure
    struct {
        int ival;
        struct {
            unsigned short sval;
            unsigned char bval;
            unsigned char cval;
        } sub;
    }
    typestr == '|V8' (or '<u8' if you want)
    descr == [('ival','<i4'), ('sub', [('sval','<u2'), ('bval','|u1'), ('cval','|u1') ]) ]

* Nested array
    struct {
        int ival;
        double data[16*4];
    }
    typestr == '|V516'
    descr == [('ival','>i4'), ('data','>f8',(16,4))]

* Padded structure
    struct {
        int ival;
        double dval;
    }
    typestr == '|V16'
    descr == [('ival','>i4'),('','|V4'),('dval','>f8')]

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

Отличия от интерфейса массива (Версия 2)

Интерфейс версии 2 был очень похож. Различия были в основном косметическими. В частности:

1. Структура PyArrayInterface не имела члена descr в конце (и, следовательно, флага ARR_HAS_DESCR)
2. Член desc объекта PyCObject, возвращаемого из __array_struct__, не был указан. Обычно это был объект, экспонирующий массив (чтобы можно было сохранить ссылку на него и уничтожить её при уничтожении объекта C). Теперь это должен быть кортеж, первым элементом которого является строка “PyArrayInterface Версия #”, а вторым — объект, экспонирующий массив.
3. Кортеж, возвращаемый из __array_interface__[‘data’], раньше был шестнадцатеричной строкой (теперь это целое или длинное целое число).
4. Атрибута __array_interface__ не было; вместо этого все ключи (кроме версии) в словаре __array_interface__ были собственными атрибутами: таким образом, чтобы получить информацию со стороны Python, вам нужно было отдельно получить доступ к атрибутам:
   • __array_data__
   • __array_shape__
   • __array_strides__
   • __array_typestr__
   • __array_descr__
   • __array_offset__
   • __array_mask__