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

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

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.

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

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

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

static PyObject *
newdatatype_call(newdatatypeobject *obj, 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;
}

/* 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(TrivialObject *self)
{
    /* Clear weakrefs first before calling any destructors */
    PyObject_ClearWeakRefs((PyObject *) self);
    /* ... remainder of destruction code omitted for brevity ... */
    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;
}