Определение типов расширений: Разные темы

3.1. Заключительные действия и освобождение памяти

destructor tp_dealloc;

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

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

Если ваш тип поддерживает сборку мусора, деструктор должен вызвать PyObject_GC_UnTrack() перед очисткой любых членских полей:

static void
newdatatype_dealloc(newdatatypeobject *obj)
{
    PyObject_GC_UnTrack(obj);
    Py_CLEAR(obj->other_obj);
    ...
    Py_TYPE(obj)->tp_free((PyObject *)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;

        /* This saves the current exception state */
        PyErr_Fetch(&err_type, &err_value, &err_traceback);

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

        /* This restores the saved exception state */
        PyErr_Restore(err_type, err_value, err_traceback);

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

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 * version */
setattrfunc  tp_setattr;
/* ... */
getattrofunc tp_getattro;       /* PyObject * version */
setattrofunc tp_setattro;

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

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

typedef struct PyMethodDef {
    const char  *ml_name;       /* method name */
    PyCFunction  ml_meth;       /* implementation function */
    int          ml_flags;      /* flags */
    const char  *ml_doc;        /* docstring */
} PyMethodDef;

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

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

    PyErr_Format(PyExc_AttributeError,
                 "'%.100s' object has no attribute '%.400s'",
                 Py_TYPE(obj)->tp_name, name);
    return 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 вызывается при необходимости сравнений. Он аналогичен методам сравнения, таким как __lt__(), и также вызывается функциями PyObject_RichCompare() и PyObject_RichCompareBool().

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

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

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

    /* code to make sure that both arguments are of type
       newdatatype omitted */

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

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

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

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

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

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

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

Вот пример реализации tp_call

/* Iterators */
getiterfunc tp_iter;
iternextfunc tp_iternext;

Эти функции обеспечивают поддержку протокола итератора. Оба обработчика принимают ровно один параметр — экземпляр, для которого они вызываются, и возвращают новую ссылку. В случае ошибки они должны установить исключение и вернуть NULL. 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; избежание исключения может незначительно повысить производительность. Если возникает реальная ошибка, tp_iternext всегда должен установить исключение и вернуть NULL

3.6. Поддержка слабых ссылок

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

Для того, чтобы объект мог быть слабо ссылаемым, тип расширения должен установить бит Py_TPFLAGS_MANAGED_WEAKREF поля tp_flags. Поле tp_weaklistoffset (наследие) должно оставаться нулевым.

Конкретно, вот как бы выглядел статически объявленный объект типа:

Единственное дальнейшее дополнение состоит в том, что tp_dealloc необходимо очистить любые слабые ссылки (вызвав PyObject_ClearWeakRefs()):

3.7. Дополнительные рекомендации

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

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