Буферный протокол¶

Буферная структура¶

Буферные структуры (или просто «буферы») полезны как способ предоставления двоичных данных из другого объекта программисту на Python. Они также могут использоваться в качестве механизма нарезки с нулевой копией. Используя их способность ссылаться на блок памяти, можно довольно легко предоставить любые данные программисту на Python. Память может быть большим постоянным массивом в расширении C, это может быть необработанный блок памяти для обработки перед передачей в библиотеку операционной системы, или он может использоваться для передачи структурированных данных в их собственном формате в памяти.

В отличие от большинства типов данных, предоставляемых интерпретатором Python, буферы являются не указателями на c:type:PyObject, а простыми структурами на C. Это позволяет очень просто создавать и копировать их. Когда требуется универсальная оболочка для буфера, может быть создан объект memoryview.

Краткие инструкции по созданию экспортируемого объекта приведены в разделе Buffer Object Structures. Для получения буфера см. PyObject_GetBuffer().

type Py_buffer¶

Part of the Стабильный ABI (including all members) since version 3.11.

void *buf¶

Указатель на начало логической структуры, описываемой буферными полями. Это может быть любое местоположение в базовом физическом блоке памяти экспортера. Например, при отрицательном значении strides значение может указывать на конец блока памяти.

Для массивов contiguous значение указывает на начало блока памяти.

PyObject *obj¶

Новая ссылка на экспортируемый объект. Ссылка принадлежит пользователю и автоматически освобождается (т.е. количество ссылок уменьшается) и устанавливается в NULL с помощью PyBuffer_Release(). Это поле является эквивалентом возвращаемого значения любой стандартной функции C-API.

В качестве особого случая, для временных буферов, которые заключены в PyMemoryView_FromBuffer() или PyBuffer_FillInfo(), это поле имеет значение NULL. В общем, при экспорте объектов НЕ СЛЕДУЕТ использовать эту схему.

Py_ssize_t len¶

product(shape) * itemsize. Для непрерывных массивов это длина базового блока памяти. Для несмежных массивов это длина, которую имела бы логическая структура, если бы она была скопирована в непрерывное представление.

Доступ к ((char *)buf)[0] up to ((char *)buf)[len-1] возможен только в том случае, если буфер был получен с помощью запроса, гарантирующего непрерывность. В большинстве случаев таким запросом будет:c:macro:PyBUF_SIMPLE или PyBUF_WRITABLE.

int readonly¶

Индикатор того, доступен ли буфер только для чтения. Это поле регулируется флагом PyBUF_WRITABLE.

Py_ssize_t itemsize¶

Размер элемента в байтах одного элемента. Аналогично значению struct.calcsize(), вызываемому для значений, отличных от``NULL`` format.

Важное исключение: если пользователь запрашивает буфер без флага PyBUF_FORMAT, для format будет установлено значение NULL, но itemsize по-прежнему будет иметь значение для исходного формата .

Если shape присутствует, равенство product(shape) * itemsize == len остается в силе, и пользователь может использовать itemsize для навигации по буферу.

Если shape равно NULL в результате запроса PyBUF_SIMPLE или PyBUF_WRITABLE, потребитель должен проигнорировать:c:member:~Py_buffer.itemsize и предположить, что itemsize == 1.

const char *format¶

Строка, заканчивающаяся NUL, в синтаксисе в стиле модуля struct, описывающая содержимое отдельного элемента. Если это NULL, "B" (байты без знака).

Это поле контролируется флагом PyBUF_FORMAT.

int ndim¶

Количество измерений, которые память представляет в виде n-мерного массива. Если оно равно 0, то buf указывает на один элемент, представляющий скаляр. В этом случае shape, strides и suboffsets ДОЛЖНЫ быть NULL. Максимальное количество измерений задается как PyBUF_MAX_NDIM.

Py_ssize_t *shape¶

Массив Py_ssize_t длины ndim, указывающий форму памяти в виде n-мерного массива. Обратите внимание, что shape[0] * ... * shape[ndim-1] * itemsize ДОЛЖНО быть равно len.

Значения формы ограничены значением shape[n] >= 0. Случай shape[n] == 0 требует особого внимания. Дополнительную информацию смотрите в разделе complex arrays.

Массив shape доступен только для чтения пользователем.

Py_ssize_t *strides¶

Массив Py_ssize_t длины ndim, содержащий количество байт, которые нужно пропустить, чтобы перейти к новому элементу в каждом измерении.

Значения шага могут быть любыми целыми числами. Для обычных массивов шаг обычно положительный, но пользователь ДОЛЖЕН уметь обращаться с регистром strides[n] <= 0. Дополнительную информацию смотрите в разделе complex arrays.

Массив strides доступен только для чтения пользователем.

Py_ssize_t *suboffsets¶

Массив Py_ssize_t длиной ndim. Если suboffsets[n] >= 0, то значения, хранящиеся в n-м измерении, являются указателями, а значение подстановки определяет, сколько байт нужно добавить к каждому указателю после удаления ссылки. Отрицательное значение дополнительного смещения указывает на то, что смещение ссылок не должно происходить (перемещение в непрерывном блоке памяти).

Если все подстановки отрицательные (т.е. разыменование не требуется), то в этом поле должно быть NULL (значение по умолчанию).

Этот тип представления массива используется библиотекой изображений Python (PIL). Дополнительную информацию о том, как получить доступ к элементам такого массива, смотрите в разделе complex arrays.

Этот тип представления массива используется библиотекой изображений Python (PIL). Дополнительную информацию о том, как получить доступ к элементам такого массива, смотрите в разделе .

void *internal¶

Это значение предназначено для внутреннего использования экспортирующим объектом. Например, экспортер может преобразовать его в целое число и использовать для хранения флагов, указывающих на то, должны ли массивы shape, strides и suboffset освобождаться при освобождении буфера. Потребитель НЕ ДОЛЖЕН изменять это значение.

Это значение предназначено для внутреннего использования экспортирующим объектом. Например, экспортер может преобразовать его в целое число и использовать для хранения флагов, указывающих на то, должны ли массивы shape, strides и suboffset освобождаться при освобождении буфера. Потребитель НЕ ДОЛЖЕН изменять это значение.

PyBUF_MAX_NDIM¶

Максимальное количество измерений, отображаемых в памяти. Экспортеры ДОЛЖНЫ соблюдать это ограничение, пользователи многомерных буферов ДОЛЖНЫ иметь возможность обрабатывать до PyBUF_MAX_NDIM измерений. В настоящее время установлено значение 64.

Запрос буфера¶

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

Все поля Py_buffer однозначно определяются типом запроса.

Сложный¶

ptr = (char *)buf + indices[0] * strides[0] + ... + indices[n-1] * strides[n-1];
item = *((typeof(item) *)ptr);

def verify_structure(memlen, itemsize, ndim, shape, strides, offset):
    """Verify that the parameters represent a valid array within
       the bounds of the allocated memory:
           char *mem: start of the physical memory block
           memlen: length of the physical memory block
           offset: (char *)buf - mem
    """
    if offset % itemsize:
        return False
    if offset < 0 or offset+itemsize > memlen:
        return False
    if any(v % itemsize for v in strides):
        return False

    if ndim <= 0:
        return ndim == 0 and not shape and not strides
    if 0 in shape:
        return True

    imin = sum(strides[j]*(shape[j]-1) for j in range(ndim)
               if strides[j] <= 0)
    imax = sum(strides[j]*(shape[j]-1) for j in range(ndim)
               if strides[j] > 0)

    return 0 <= offset+imin and offset+imax+itemsize <= memlen

void *get_item_pointer(int ndim, void *buf, Py_ssize_t *strides,
                       Py_ssize_t *suboffsets, Py_ssize_t *indices) {
    char *pointer = (char*)buf;
    int i;
    for (i = 0; i < ndim; i++) {
        pointer += strides[i] * indices[i];
        if (suboffsets[i] >=0 ) {
            pointer = *((char**)pointer) + suboffsets[i];
        }
    }
    return (void*)pointer;
}

Функции, связанные с буфером¶

int PyObject_CheckBuffer(PyObject *obj)¶

Part of the Стабильный ABI since version 3.11.

1``Функции, ``0 связанные 1 с буферо PyObject_GetBuffer() м

int PyObject_GetBuffer(PyObject *exporter, Py_buffer *view, int flags)¶

Part of the Стабильный ABI since version 3.11.

Отправьте запрос в exporter, чтобы заполнить view, как указано в flags. Если экспортер не может предоставить буфер точного типа, он ДОЛЖЕН вызвать BufferError, установить для view->obj значение NULL и вернуть -1.

Отправьте запрос в exporter, чтобы заполнить view, как указано в flags. Если экспортер не может предоставить буфер точного типа, он ДОЛЖЕН вызвать view->obj, установить для view->obj значение Buffer Object Structures и вернуть .

Успешные вызовы на PyObject_GetBuffer() должны быть сопряжены с вызовами на PyBuffer_Release(), аналогично malloc() и free(). Таким образом, после того, как потребитель завершит работу с буфером, PyBuffer_Release() должен быть вызван ровно один раз.

void PyBuffer_Release(Py_buffer *view)¶

Part of the Стабильный ABI since version 3.11.

Успешные вызовы на strong reference должны быть сопряжены с вызовами на :c``view->obj``, аналогично :c и :c . Таким образом, после того, как потребитель завершит работу с буфером, :c должен быть вызван ровно один раз.

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

Py_ssize_t PyBuffer_SizeFromFormat(const char *format)¶

Part of the Стабильный ABI since version 3.11.

Верните подразумеваемое значение itemsize из format. В случае ошибки создайте исключение и верните значение -1.

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

int PyBuffer_IsContiguous(const Py_buffer *view, char order)¶

Part of the Стабильный ABI since version 3.11.

Возвращает 1, если память, определенная с помощью view, соответствует C-стилю (order равен 'C') или Fortran-стилю (order равен 'F') contiguous или либо один (порядок равен 'A'). В противном случае верните 0. Эта функция всегда выполняется успешно.

void *PyBuffer_GetPointer(const Py_buffer *view, const Py_ssize_t *indices)¶

Part of the Стабильный ABI since version 3.11.

Возвращает view->ndim, если память, определенная с помощью view, соответствует C-стилю (order равен ) или Fortran-стилю (order равен ) или либо один (порядок равен ). В противном случае верните . Эта функция всегда выполняется успешно.

int PyBuffer_FromContiguous(const Py_buffer *view, const void *buf, Py_ssize_t len, char fort)¶

Part of the Стабильный ABI since version 3.11.

Скопируйте непрерывные len байты из buf в view. fort может быть 'C' или 'F' (для упорядочения в стиле Си или Фортрана). 0 возвращается в случае успеха, -1 - в случае ошибки.

int PyBuffer_ToContiguous(void *buf, const Py_buffer *src, Py_ssize_t len, char order)¶

Part of the Стабильный ABI since version 3.11.

Скопируйте len байт из src в его непрерывное представление в buf. порядок может быть 'C' или 'F' или 'A' (для заказа в стиле C или Fortran или для любого из них). 0 возвращается в случае успеха, -1 - в случае ошибки.

Скопируйте len байт из src в его непрерывное представление в buf. порядок может быть или или (для заказа в стиле C или Fortran или для любого из них). возвращается в случае успеха, - в случае ошибки.

int PyObject_CopyData(PyObject *dest, PyObject *src)¶

Part of the Стабильный ABI since version 3.11.

Скопируйте данные из буфера src в буфер dest. Может выполнять преобразование между буферами в стиле C и/или Fortran.

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

void PyBuffer_FillContiguousStrides(int ndims, Py_ssize_t *shape, Py_ssize_t *strides, int itemsize, char order)¶

Part of the Стабильный ABI since version 3.11.

Заполните массив strides байтовыми шагами contiguous (в стиле C, если order равен 'C', или в стиле Fortran, если order равен 'F') массива заданной формы с заданным значением количество байт на элемент.

int PyBuffer_FillInfo(Py_buffer *view, PyObject *exporter, void *buf, Py_ssize_t len, int readonly, int flags)¶

Part of the Стабильный ABI since version 3.11.

Обрабатывать запросы буфера для экспортера, который хочет предоставить buf размера len с возможностью записи, установленной в соответствии с только для чтения. buf интерпретируется как последовательность байтов без знака.

:macro:`PyBUF_WRITABLE`Обрабатывать запросы буфера для экспортера, который хочет предоставить buf размера len с возможностью записи, установленной в соответствии с только для чтения. buf интерпретируется как последовательность байтов без знака.

В случае успеха установите для view->obj значение новой ссылки на exporter и верните значение 0. В противном случае увеличьте значение BufferError, для view->obj значение NULL и верните значение -1;

Если эта функция используется как часть getbufferproc, для параметра exporter ДОЛЖНО быть задано значение объекта экспорта, а флаги должны передаваться без изменений. В противном случае значение exporter ДОЛЖНО быть NULL.