Протокол буфера¶Buffer Protocol

Структура буфера¶Buffer structure

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

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

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

Py_buffer¶

void *buf¶

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

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

void *obj¶

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

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

Py_ssize_t len¶

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

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

int readonly¶

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

Py_ssize_t itemsize¶

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

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

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

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

const char *format¶

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

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

int ndim¶

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

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

Py_ssize_t *shape¶

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

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

Массив формы доступен потребителю только для чтения.

Py_ssize_t *strides¶

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

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

Массив шагов доступен потребителю только для чтения.

Py_ssize_t *suboffsets¶

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

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

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

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

void *internal¶

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

Типы запросов буфера¶Buffer request types

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

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

Комплексные массивы¶Complex arrays

def verify_structure(memlen, itemsize, ndim, shape, strides, offset):
    """Проверить, что параметры представляют допустимый массив в пределах
       границ выделенной памяти:
           char *mem: начало физического блока памяти
           memlen: длина физического блока памяти
           смещение: (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;
}

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

int PyObject_CheckBuffer(PyObject *obj)¶

Возвращает 1, если obj поддерживает интерфейс буфера, иначе 0. Если возвращается 1, это не гарантирует, что PyObject_GetBuffer() выполнится успешно.

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

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

При успехе заполняет view, устанавливает view->obj в новую ссылку на exporter и возвращает 0. В случае цепочечных поставщиков буферов, которые перенаправляют запросы одному объекту, view->obj МОЖЕТ ссылаться на этот объект вместо exporter (см. Структуры буферных объектов).

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

void PyBuffer_Release(Py_buffer *view)¶

Освобождает буфер view и уменьшает счётчик ссылок для view->obj. Эта функция ДОЛЖНА быть вызвана, когда буфер больше не используется, иначе могут возникнуть утечки ссылок.

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

Py_ssize_t PyBuffer_SizeFromFormat(const char *)¶

Возвращает подразумеваемый itemsize из format. Эта функция ещё не реализована.

int PyBuffer_IsContiguous(Py_buffer *view, char order)¶

Возвращает 1, если память, определённая view, является непрерывной в стиле C (order равен 'C') или в стиле Fortran (order равен 'F') или любым из них (order равен 'A'). Иначе возвращает 0.

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

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

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

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

Аргумент flags указывает тип запроса. Эта функция всегда заполняет view в соответствии с flags, если только buf не был назначен только для чтения и в flags не установлен PyBUF_WRITABLE.

При успехе устанавливает view->obj в новую ссылку на exporter и возвращает 0. В противном случае вызывает исключение PyExc_BufferError, устанавливает view->obj в NULL и возвращает -1;

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