Протокол буфера¶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 указывает, что разыменование не должно выполняться (шаг в непрерывном блоке памяти).

Такой тип представления массива используется библиотекой 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 должен быть установлен на экспортирующий объект. В противном случае exporter должен быть NULL.