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

3.1. Финализация и освобождение памяти

destructor tp_dealloc;

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

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

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

static void
newdatatype_dealloc(PyObject *op)
{
    newdatatypeobject *self = (newdatatypeobject *) op;
    PyObject_GC_UnTrack(op);
    Py_CLEAR(self->other_obj);
    ...
    Py_TYPE(self)->tp_free(self);
}

Одно из важных требований к функции освобождения памяти — она должна оставлять все ожидающие исключения без изменений. Это важно, поскольку функции освобождения памяти часто вызываются при разматывании стека 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(self)->tp_free(self);
}

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

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

reprfunc tp_repr;
reprfunc tp_str;

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

static PyObject *
newdatatype_repr(PyObject *op)
{
    newdatatypeobject *self = (newdatatypeobject *) op;
    return PyUnicode_FromFormat("Repr-ified_newdatatype{{size:%d}}",
                                self->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(PyObject *op)
{
    newdatatypeobject *self = (newdatatypeobject *) op;
    return PyUnicode_FromFormat("Stringified_newdatatype{{size:%d}}",
                                self->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(PyObject *op, char *name)
{
    newdatatypeobject *self = (newdatatypeobject *) op;
    if (strcmp(name, "data") == 0) {
        return PyLong_FromLong(self->data);
    }

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

static int
newdatatype_setattr(PyObject *op, 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(PyObject *lhs, PyObject *rhs, int op)
{
    newdatatypeobject *obj1 = (newdatatypeobject *) lhs;
    newdatatypeobject *obj2 = (newdatatypeobject *) rhs;
    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;
    return Py_NewRef(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(PyObject *op)
{
    newdatatypeobject *self = (newdatatypeobject *) op;
    Py_hash_t result;
    result = self->some_size + 32767 * self->some_number;
    if (result == -1) {
        result = -2;
    }
    return result;
}

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

ternaryfunc tp_call;

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

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

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

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

static PyObject *
newdatatype_call(PyObject *op, PyObject *args, PyObject *kwds)
{
    newdatatypeobject *self = (newdatatypeobject *) op;
    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",
        self->obj_UnderlyingDatatypePtr->size,
        arg1, arg2, arg3);
    return result;
}

/* 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 следует оставить равным нулю.

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

static PyTypeObject TrivialType = {
    PyVarObject_HEAD_INIT(NULL, 0)
    /* ... other members omitted for brevity ... */
    .tp_flags = Py_TPFLAGS_MANAGED_WEAKREF | ...,
};

Остаётся только добавить, что tp_dealloc должен очищать все слабые ссылки (вызывая PyObject_ClearWeakRefs()):

static void
Trivial_dealloc(PyObject *op)
{
    /* Clear weakrefs first before calling any destructors */
    PyObject_ClearWeakRefs(op);
    /* ... remainder of destruction code omitted for brevity ... */
    Py_TYPE(op)->tp_free(op);
}

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;
}