3. Определение типов расширений: ассортированные темы¶

Этот раздел призван дать быстрый обзор различных методов, которые вы можете реализовать и что они делают.

Вот определение PyTypeObject, некоторые поля, используемыt только в отладочных компоновках, пропущены:

typedef struct _typeobject {
    PyObject_VAR_HEAD
    const char *tp_name; /* For printing, in format "<module>.<name>" */
    Py_ssize_t tp_basicsize, tp_itemsize; /* For allocation */

    /* Methods to implement standard operations */

    destructor tp_dealloc;
    Py_ssize_t tp_vectorcall_offset;
    getattrfunc tp_getattr;
    setattrfunc tp_setattr;
    PyAsyncMethods *tp_as_async; /* formerly known as tp_compare (Python 2)
                                    or tp_reserved (Python 3) */
    reprfunc tp_repr;

    /* Method suites for standard classes */

    PyNumberMethods *tp_as_number;
    PySequenceMethods *tp_as_sequence;
    PyMappingMethods *tp_as_mapping;

    /* More standard operations (here for binary compatibility) */

    hashfunc tp_hash;
    ternaryfunc tp_call;
    reprfunc tp_str;
    getattrofunc tp_getattro;
    setattrofunc tp_setattro;

    /* Functions to access object as input/output buffer */
    PyBufferProcs *tp_as_buffer;

    /* Flags to define presence of optional/expanded features */
    unsigned long tp_flags;

    const char *tp_doc; /* Documentation string */

    /* call function for all accessible objects */
    traverseproc tp_traverse;

    /* delete references to contained objects */
    inquiry tp_clear;

    /* rich comparisons */
    richcmpfunc tp_richcompare;

    /* weak reference enabler */
    Py_ssize_t tp_weaklistoffset;

    /* Iterators */
    getiterfunc tp_iter;
    iternextfunc tp_iternext;

    /* Attribute descriptor and subclassing stuff */
    struct PyMethodDef *tp_methods;
    struct PyMemberDef *tp_members;
    struct PyGetSetDef *tp_getset;
    struct _typeobject *tp_base;
    PyObject *tp_dict;
    descrgetfunc tp_descr_get;
    descrsetfunc tp_descr_set;
    Py_ssize_t tp_dictoffset;
    initproc tp_init;
    allocfunc tp_alloc;
    newfunc tp_new;
    freefunc tp_free; /* Low-level free-memory routine */
    inquiry tp_is_gc; /* For PyObject_IS_GC */
    PyObject *tp_bases;
    PyObject *tp_mro; /* method resolution order */
    PyObject *tp_cache;
    PyObject *tp_subclasses;
    PyObject *tp_weaklist;
    destructor tp_del;

    /* Type attribute cache version tag. Added in version 2.6 */
    unsigned int tp_version_tag;

    destructor tp_finalize;

} PyTypeObject;

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

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

const char *tp_name; /* Для печати */

Название типа – как упоминалось в предыдущей главе, оно появится в различных местах, почти полностью для целей диагностики. Постарайтесь выбрать то, что поможет в такой ситуации!:

Py_ssize_t tp_basicsize, tp_itemsize; /* Для распределенияn */

Эти поля указывают среде выполнения объем памяти, выделяемой при создании новых объектов этого типа. Python имеет некоторую встроенную поддержку структур переменной длины (подумайте: строки, кортежи), где входит tp_itemsize поле. С этим будет разбираться позже:

const char *tp_doc;

Здесь можно поместить строку (или его адрес), который требуется вернуть, когда сценарий Python ссылается на obj.__doc__ для получения строки документа.

Теперь мы переходим к основным типам методов, которые будут реализованы в большинстве типов расширений.

3.1. Завершение и отмена распределения¶

destructor tp_dealloc;

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

static void
newdatatype_dealloc(newdatatypeobject *obj)
{
    free(obj->obj_UnderlyingDatatypePtr);
    Py_TYPE(obj)->tp_free(obj);
}

Одним из важных требований функции деаллокатора является то, что она оставляет все незавершенные исключения. Это важно, поскольку деаллокаторы часто называются, так как интерпретатор разматывает стек Python; когда стек разматывается из-за исключения (вместо обычного возвращает), ничего не делается для защиты деаллокаторов от того, что исключение уже установлено. Любые действия, выполняемые деаллокатором, которые могут вызвать выполнение дополнительных Python код, могут обнаружить, что было установлено исключение. Это может привести к ошибкам в интерпретатора. Правильный способ защиты от этого - сохранить ожидающее исключение перед выполнением небезопасного действия и восстановить его по завершении. Это можно сделать с помощью функций PyErr_Fetch() и PyErr_Restore():

static void
my_dealloc(PyObject *obj)
{
    MyObject *self = (MyObject *) obj;
    PyObject *cbresult;

    if (self->my_callback != NULL) {
        PyObject *err_type, *err_value, *err_traceback;

        /* При этом сохраняется текущий состояние исключения */
        PyErr_Fetch(&err_type, &err_value, &err_traceback);

        cbresult = PyObject_CallObject(self->my_callback, NULL);
        if (cbresult == NULL)
            PyErr_WriteUnraisable(self->my_callback);
        else
            Py_DECREF(cbresult);

        /* Это восстанавливает сохраненный состояние исключения */
        PyErr_Restore(err_type, err_value, err_traceback);

        Py_DECREF(self->my_callback);
    }
    Py_TYPE(obj)->tp_free((PyObject*)self);
}

Примечание

Есть ограничения на то, что вы можете безопасно сделать в функции деаллокатора. Во-первых, если тип поддерживает сбор мусора (используя tp_traverse и/или tp_clear), некоторые элементы объекта могут быть очищены или окончательно определены во время tp_dealloc. Во-вторых, в tp_dealloc, ваш объект находится в нестабильном состояние: его отсчет равен нулю. Любой вызов нетривиального объекта или API (как в приведенном выше примере) может снова оказаться вызова tp_dealloc, что приведет к двойному освобождению и сбою.

Начиная с Python 3.4, рекомендуется не ставить какой-либо сложный код финализации в tp_dealloc, а вместо этого использовать новый метод типа tp_finalize.

См.также

PEP 442 объясняет новую схему окончательной доработки.

3.2. Представление объекта¶

В Python существует два способа создания текстового представления объекта: функция repr() и функция str(). (Функция print() вызывает только str()). Эти обработчики являются необязательными.

reprfunc tp_repr;
reprfunc tp_str;

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

static PyObject *
newdatatype_repr(newdatatypeobject * obj)
{
    return PyUnicode_FromFormat("Repr-ified_newdatatype{{size:%d}}",
                                obj->obj_UnderlyingDatatypePtr->size);
}

Если не указан tp_repr обработчик, интерпретатор предоставит представление, использующее тип tp_name и однозначно идентифицирующий значение для объекта.

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

Вот простой пример:

static PyObject *
newdatatype_str(newdatatypeobject * obj)
{
    return PyUnicode_FromFormat("Stringified_newdatatype{{size:%d}}",
                                obj->obj_UnderlyingDatatypePtr->size);
}

3.3. Управление атрибутами¶

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

Python поддерживает две пары атрибут обработчики; тип, поддерживающий атрибуты, должен реализовывать функции только для одной пары. Разница в том, что одна пара принимает имя атрибут как char*, а другая принимает PyObject*. Каждый тип может использовать любую пару имеет больше смысла для удобства реализации:

getattrfunc  tp_getattr;        /* char * версия */
setattrfunc  tp_setattr;
/* ... */
getattrofunc tp_getattro;       /* PyObject * версия */
setattrofunc tp_setattro;

Если доступ к атрибутам объекта всегда является простой операцией (это будет объяснено кратко), существуют общие реализации, которые могут быть используемый для обеспечения PyObject* версии функций управления атрибут. Фактическая потребность в специфичных для типа атрибута обработчика почти полностью исчезла, начиная с Python 2.2, хотя есть много примеров, которые не были обновлены, чтобы использовать некоторые из новых общих механизмов, которые доступны.

3.3.1. Общее управление атрибутами¶

Большинство типов расширений используют только простые атрибуты. Так что же делает атрибуты простым? Есть только два условия, которые должны быть выполнены:

Имена атрибутов должны быть известны при вызове PyType_Ready().
Не требуется никакой специальной обработки для регистрации поиска или установки атрибута, а также действий на основе значения.

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

При вызове PyType_Ready() он использует три таблицы, на которые ссылается объект- тип, для создания дескриптора, которые помещаются в словарь объекта-типа. Каждый дескриптор управляет доступом к одному атрибут объекта сущность. Каждая из таблиц является необязательной; если все три будут NULL, то у сущности типа только будет атрибуты, которые унаследованы от их основного типа и должны оставить поля tp_getattro и tp_setattro NULL также, позволив основному типу обращаться к атрибутам.

Таблицы объявляются как три поля объекта типа:

struct PyMethodDef *tp_methods;
struct PyMemberDef *tp_members;
struct PyGetSetDef *tp_getset;

Если tp_methods не является NULL, он должен относиться к массиву PyMethodDef структур. Каждая запись в таблице является сущность этой структуры:

typedef struct PyMethodDef {
    const char  *ml_name;       /* имя метода */
    PyCFunction  ml_meth;       /* функция реализации */
    int          ml_flags;      /* флаги */
    const char  *ml_doc;        /* docstring */
} PyMethodDef;

Для каждого метода, предоставляемого типом, должна быть определена одна запись; для методов, унаследованных от базового типа, записи не требуются. В конце требуется одна дополнительная запись; это дозорный, который отмечает конец массива. Поле ml_name дозорного должно быть NULL.

Вторая таблица используемая для определения атрибутов, которые отображаются непосредственно на данные, хранящиеся в сущности. Поддерживается множество примитивных типов C, и доступ может быть только для чтения или для чтения- записи. Структуры в таблице определяются как:

typedef struct PyMemberDef {
    const char *name;
    int         type;
    int         offset;
    int         flags;
    const char *doc;
} PyMemberDef;

Для каждой записи в таблице будет создан и добавлен к типу дескриптор, который сможет извлечь значение из структуры сущности. Поле type должно содержать одно из кодов типов, определенных в заголовке structmember.h; значение будет использоваться для определения способа преобразования Python значения в и из C значения. Поле flags используется для хранения флагов, управляющих доступом к атрибуту.

В structmember.h определены следующие константы флагов: они могут быть объединены с использованием побитового ИЛИ.

Константа	Смысл
`READONLY`	Никогда не может быть записано.
`READ_RESTRICTED`	Недоступно для чтения в ограниченном режиме.
`WRITE_RESTRICTED`	Невозможно выполнить запись в ограниченном режиме.
`RESTRICTED`	Недоступно для чтения или записи в ограниченном режиме.

Интересным преимуществом использования tp_members таблицы для построения дескрипторов, используемых во время выполнения, является то, что любой атрибут, определенный таким образом, может иметь связанную строку документа, просто предоставив текст в таблице. Приложение может использовать API самоанализа, чтобы восстановить дескриптор от объекта класса и получить докстроку, используя его __doc__ атрибут.

Как и tp_methods таблице, требуется дозорная запись с name значение NULL.

3.3.2. Управление атрибутами для конкретного типа¶

Для простоты здесь будет продемонстрирована только char* версия; тип параметра name является единственным различием между char* и PyObject* ароматами интерфейса. В этом примере эффективно выполняется то же самое, что и в приведенном выше примере, но не используется общая поддержка, добавленная в Python 2.2. Здесь объясняется, как вызываются обработчики функций, так что если вам нужно расширить их функциональность, вы поймете, что нужно сделать.

tp_getattr обработчик вызывается, когда объект требует атрибут поиска. Он вызывается в тех же ситуациях, когда вызывается метод __getattr__() класса.

Вот пример:

static PyObject *
newdatatype_getattr(newdatatypeobject *obj, char *name)
{
    if (strcmp(name, "data") == 0)
    {
        return PyLong_FromLong(obj->data);
    }

    PyErr_Format(PyExc_AttributeError,
                 "'%.50s' object has no attribute '%.400s'",
                 tp->tp_name, name);
    return NULL;
}

tp_setattr обработчик вызывается при вызове метода __setattr__() или __delattr__() класса сущности. При удалении атрибут будет NULL третий параметр. Вот пример, который просто вызывает исключение; если это действительно все, что вы хотели, tp_setattr обработчик должны быть настроен на NULL:

static int
newdatatype_setattr(newdatatypeobject *obj, char *name, PyObject *v)
{
    PyErr_Format(PyExc_RuntimeError, "Read-only attribute: %s", name);
    return -1;
}

3.4. Сравнение объектов¶

richcmpfunc tp_richcompare;

tp_richcompare обработчик вызывается при необходимости сравнения. Он аналогичен богатыv методfv сравнения, как и __lt__(), а также вызвается PyObject_RichCompare() и PyObject_RichCompareBool().

Эта функция вызывается с двумя объектами Python и оператором в качестве аргументов, где оператор является одним из Py_EQ, Py_NE, Py_LE, Py_GT, Py_LT или Py_GT. Это должно сравнить два объекта относительно указанного оператора и возвращает Py_True или Py_False, если сравнение успешно, Py_NotImplemented, чтобы указать, что сравнение не осуществлено, и метод сравнения другого объекта нужно попробовать, или NULL, если бы исключение было установлено.

Вот пример реализации для типа данных, который считается равным, если размер внутреннего указателя равен:

static PyObject *
newdatatype_richcmp(PyObject *obj1, PyObject *obj2, int op)
{
    PyObject *result;
    int c, size1, size2;

    /* код убедиться, что оба аргумента типа
       newdatatype прпропущены */

    size1 = obj1->obj_UnderlyingDatatypePtr->size;
    size2 = obj2->obj_UnderlyingDatatypePtr->size;

    switch (op) {
    case Py_LT: c = size1 <  size2; break;
    case Py_LE: c = size1 <= size2; break;
    case Py_EQ: c = size1 == size2; break;
    case Py_NE: c = size1 != size2; break;
    case Py_GT: c = size1 >  size2; break;
    case Py_GE: c = size1 >= size2; break;
    }
    result = c ? Py_True : Py_False;
    Py_INCREF(result);
    return result;
 }

3.5. Абстрактная поддержка протокола¶

Python поддерживает множество абстрактных «протоколов»; конкретные интерфейсы, предоставляемые для использования этих интерфейсов, задокументированы в Слой абстрактных объектов.

Ряд этих абстрактных интерфейсов был определен на раннем этапе разработки Python реализации. В частности, протоколы количества, отображения и последовательности являются частью Python с самого начала. Со временем были добавлены и другие протоколы. Для протоколов, которые зависят от нескольких обработчиков подпрограмм из реализации типа, старые протоколы были определены как необязательные блоки обработчики, на которые ссылается объект типа. Для более новых протоколов в объекте основного типа имеются дополнительные слоты, причем бит флага устанавливается для указания того, что слоты присутствуют и должны проверяться интерпретатором. (Бит флага не указывает, что значения слота являются не-NULL. Флаг может быть установлен для указания наличия слота, но слот все еще может быть незаполненным.):

PyNumberMethods   *tp_as_number;
PySequenceMethods *tp_as_sequence;
PyMappingMethods  *tp_as_mapping;

Если требуется, чтобы объект мог действовать как число, последовательность или объект отображения, следует разместить адрес структуры, реализующей типы C PyNumberMethods, PySequenceMethods или PyMappingMethods соответственно. Вы должны заполнить эту структуру соответствующими значения. Примеры использования каждого из них можно найти в каталоге Objects исходного дистрибутива Python:

hashfunc tp_hash;

Эта функция должна возвращать хэш-номер для сущности вашего типа данных. Вот простой пример:

static Py_hash_t
newdatatype_hash(newdatatypeobject *obj)
{
    Py_hash_t result;
    result = obj->some_size + 32767 * obj->some_number;
    if (result == -1)
       result = -2;
    return result;
}

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

ternaryfunc tp_call;

Эта функция вызвана, когда сущность вашего типа данных «вызывается», например, если obj1 - сущность вашего типа данных, и сценарий Python содержит obj1('hello'), вызывается tp_call обработчик.

Эта функция принимает три аргумента:

self - это сущность типа данных, который является предметом вызова. Если вызов obj1('hello'), то self obj1.
args - кортеж, содержащий аргументы для вызова. Для извлечения аргументов можно использовать PyArg_ParseTuple().
kwds - словарь ключевых переданных аргументов. Если не-NULL и вы поддерживаете ключевой аргументы, используйте PyArg_ParseTupleAndKeywords() для извлечения аргументов. Если вы не хотите поддерживать ключевой аргументы и это не-NULL, вызовите TypeError с сообщением о том, что ключевые аргументы не поддерживаются.

Вот реализация игрушечного tp_call:

static PyObject *
newdatatype_call(newdatatypeobject *self, PyObject *args, PyObject *kwds)
{
    PyObject *result;
    const char *arg1;
    const char *arg2;
    const char *arg3;

    if (!PyArg_ParseTuple(args, "sss:call", &arg1, &arg2, &arg3)) {
        return NULL;
    }
    result = PyUnicode_FromFormat(
        "Returning -- value: [%d] arg1: [%s] arg2: [%s] arg3: [%s]\n",
        obj->obj_UnderlyingDatatypePtr->size,
        arg1, arg2, arg3);
    return result;
}

/* Итераторы */
getiterfunc tp_iter;
iternextfunc tp_iternext;

Эти функции обеспечивают поддержку протокола итератора. Оба обработчика принимают ровно один параметр, сущность, для которого они вызываются, и возвращает новую ссылку. В случае ошибки они должны установить исключение и возвращает NULL.:c:member:~PyTypeObject.tp_iter соответствует методу Python __iter__(), пока tp_iternext соответствует методу Python __next__().

Любой итерируемый объект должен реализовывать tp_iter обработчик, который должен возвращает объектом итератора. Здесь применяются те же рекомендации, что и для Python классов:

Для коллекций (таких как списки и кортежи), которые могут поддерживать несколько независимых итераторов, каждый tp_iter вызова должен создавать и возвращенный новый итератор.
Объекты, которые могут быть итерируются только один раз (обычно из-за побочных эффектов итерации, например, файловые объекты), могут реализовывать tp_iter, возвращая себе новую ссылку, и поэтому должны реализовывать tp_iternext обработчик.

Любой объект итератора должен реализовывать оба tp_iter и tp_iternext. Итератор tp_iter обработчик должен возвращает новую ссылку на итератор. Это tp_iternext обработчик должна возвращает новая ссылка на следующий объект в итерации, если она имеется. Если повторение достигло конца tp_iternext может вернуть NULL, не устанавливая исключение, или это может установить StopIteration в дополнение в возвращение NULL; исключение может yield несколько лучшую производительность. Если фактическая ошибка происходит, tp_iternext всегда должна устанавливать исключение и возвращает NULL.

3.6. Слабая справочная поддержка¶

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

См.также

Документация для модуля weakref.

Чтобы объект был слабо ссылочным, тип расширения должен выполнять две операции:

Включите поле PyObject* в структуру объекта C, предназначенную для слабого ссылочного механизма. Конструктор объекта должен оставить его NULL (что автоматически при использовании значения по умолчанию: c:member:~PyTypeObject.tp_alloc).
Установите tp_weaklistoffset элемент типа смещение вышеупомянутого поля в структуре объекта C, чтобы интерпретатор знал, как получить доступ к этому полю и изменить его.

Конкретно, вот как тривиальная структура объекта была бы дополнена требуемым полем:

typedef struct {
    PyObject_HEAD
    PyObject *weakreflist;  /* Список слабых ссылок */
} TrivialObject;

И соответствующий элемент в статически объявленном типовом объекте:

static PyTypeObject TrivialType = {
    PyVarObject_HEAD_INIT(NULL, 0)
    /* ... другие члены пропущены для краткости ... */
    .tp_weaklistoffset = offsetof(TrivialObject, weakreflist),
};

Единственным дополнительным дополнением является то, что tp_dealloc необходимо очистить слабые ссылки (путем вызова PyObject_ClearWeakRefs()), если поле является не-NULL:

static void
Trivial_dealloc(TrivialObject *self)
{
    /* Прежде чем вызывать деструкторы, очистите слабые ссылки */
    if (self->weakreflist != NULL)
        PyObject_ClearWeakRefs((PyObject *) self);
    /* ... остальная часть кода уничтожения пропущена для краткости ... */
    Py_TYPE(self)->tp_free((PyObject *) self);
}

3.7. Дополнительные предложения¶

Чтобы узнать, как реализовать любой конкретный метод для нового типа данных, получите CPython источника код. Перейдите в каталог Objects, затем найдите в исходных файлах C tp_ плюс нужную функцию (например, tp_richcompare). Вы найдете примеры функций, которые вы хотите реализовать.

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

if (!PyObject_TypeCheck(some_object, &MyType)) {
    PyErr_SetString(PyExc_TypeError, "arg #1 not a mything");
    return NULL;
}

См.также

Загрузите CPython исходники релизов.: https://www.python.org/downloads/source/
Проект CPython на GitHub, где разрабатывается CPython исходный код.: https://github.com/python/cpython

3. Определение типов расширений: ассортированные темы¶

3.1. Завершение и отмена распределения¶

3.2. Представление объекта¶

3.3. Управление атрибутами¶

3.3.1. Общее управление атрибутами¶

3.3.2. Управление атрибутами для конкретного типа¶

3.4. Сравнение объектов¶

3.5. Абстрактная поддержка протокола¶

3.6. Слабая справочная поддержка¶

3.7. Дополнительные предложения¶

Содержание

Предыдущий раздел

Следующий раздел

Эта страница