Содержание страницы

Определение новых типов¶Defining New Types

Как упоминалось в предыдущей главе, Python позволяет разработчику модуля расширения определять новые типы, которыми можно манипулировать из кода Python, подобно строкам и спискам в ядре Python.

Это несложно; код всех типов расширений следует определённому шаблону, но есть несколько деталей, которые необходимо понять, прежде чем приступать к работе.

Основы¶The Basics

Среда выполнения Python рассматривает все объекты Python как переменные типа PyObject*. Объект PyObject не является очень значительным – он содержит только счетчик ссылок и указатель на «объект типа» этого объекта. Именно здесь происходит основное действие; объект типа определяет, какие (C) функции вызываются, когда, например, ищется атрибут объекта или объект умножается на другой. Эти C-функции называются «методами типа», чтобы отличать их от таких вещей, как [].append (которые мы называем «методами объекта»).

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

Такие вещи лучше всего объяснять на примере, поэтому вот минимальный, но полный модуль, определяющий новый тип:

#include <Python.h>

typedef struct {
    PyObject_HEAD
    /* Сюда помещаются поля, специфичные для типа. */
} noddy_NoddyObject;

static PyTypeObject noddy_NoddyType = {
    PyObject_HEAD_INIT(NULL)
    "noddy.Noddy",             /* tp_name */
    sizeof(noddy_NoddyObject), /* tp_basicsize */
    0,                         /* tp_itemsize */
    0,                         /* tp_dealloc */
    0,                         /* tp_print */
    0,                         /* tp_getattr */
    0,                         /* tp_setattr */
    0,                         /* tp_reserved */
    0,                         /* tp_repr */
    0,                         /* tp_as_number */
    0,                         /* tp_as_sequence */
    0,                         /* tp_as_mapping */
    0,                         /* tp_hash  */
    0,                         /* tp_call */
    0,                         /* tp_str */
    0,                         /* tp_getattro */
    0,                         /* tp_setattro */
    0,                         /* tp_as_buffer */
    Py_TPFLAGS_DEFAULT,        /* tp_flags */
    "Noddy objects",           /* tp_doc */
};

static PyModuleDef noddymodule = {
    PyModuleDef_HEAD_INIT,
    "noddy",
    "Example module that creates an extension type.",
    -1,
    NULL, NULL, NULL, NULL, NULL
};

PyMODINIT_FUNC
PyInit_noddy(void) 
{
    PyObject* m;

    noddy_NoddyType.tp_new = PyType_GenericNew;
    if (PyType_Ready(&noddy_NoddyType) < 0)
        return NULL;

    m = PyModule_Create(&noddymodule);
    if (m == NULL)
        return NULL;

    Py_INCREF(&noddy_NoddyType);
    PyModule_AddObject(m, "Noddy", (PyObject *)&noddy_NoddyType);
    return m;
}

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

Первое, что будет новым:

typedef struct {
    PyObject_HEAD
} noddy_NoddyObject;

Вот что будет содержать объект Noddy – в данном случае не больше, чем любой объект Python, а именно счетчик ссылок и указатель на объект типа. Это поля, которые предоставляет макрос PyObject_HEAD. Причина использования макроса – стандартизация расположения и возможность включения специальных отладочных полей в отладочных сборках. Обратите внимание, что после макроса PyObject_HEAD точка с запятой не ставится; она уже включена в определение макроса. Следует остерегаться случайного добавления точки с запятой; это легко сделать по привычке, и ваш компилятор может не пожаловаться, но у другого, скорее всего, возникнет ошибка! (В Windows известно, что MSVC считает это ошибкой и отказывается компилировать код.)

Для сравнения взгляните на соответствующее определение для стандартных чисел с плавающей запятой Python:

typedef struct {
    PyObject_HEAD
    double ob_fval;
} PyFloatObject;

Далее переходим к самому главному – объекту типа.

static PyTypeObject noddy_NoddyType = {
    PyObject_HEAD_INIT(NULL)
    "noddy.Noddy",             /* tp_name */
    sizeof(noddy_NoddyObject), /* tp_basicsize */
    0,                         /* tp_itemsize */
    0,                         /* tp_dealloc */
    0,                         /* tp_print */
    0,                         /* tp_getattr */
    0,                         /* tp_setattr */
    0,                         /* tp_reserved */
    0,                         /* tp_repr */
    0,                         /* tp_as_number */
    0,                         /* tp_as_sequence */
    0,                         /* tp_as_mapping */
    0,                         /* tp_hash  */
    0,                         /* tp_call */
    0,                         /* tp_str */
    0,                         /* tp_getattro */
    0,                         /* tp_setattro */
    0,                         /* tp_as_buffer */
    Py_TPFLAGS_DEFAULT,        /* tp_flags */
    "Noddy objects",           /* tp_doc */
};

Теперь, если вы заглянете в определение PyTypeObject в object.h, то увидите, что оно содержит гораздо больше полей, чем показано выше. Остальные поля будут заполнены нулями компилятором C, и обычно их не указывают явно, если они не нужны.

Это настолько важно, что мы разберём его верхнюю часть ещё подробнее:

PyObject_HEAD_INIT(NULL)

Эта строка – небольшой изъян; хотелось бы написать:

PyObject_HEAD_INIT(&PyType_Type)

поскольку типом объекта типа является «type», но это не строго соответствует C и некоторые компиляторы выдают предупреждения. К счастью, этот член будет заполнен за нас PyType_Ready.

"noddy.Noddy",              /* tp_name */

Имя нашего типа. Оно будет отображаться в стандартном текстовом представлении наших объектов и в некоторых сообщениях об ошибках, например:

>>> "" + noddy.new_noddy()
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
TypeError: cannot add type "noddy.Noddy" to string

Обратите внимание, что имя является точечным и включает как имя модуля, так и имя типа внутри модуля. В данном случае модуль – noddy, а тип – Noddy, поэтому мы устанавливаем имя типа noddy.Noddy.

sizeof(noddy_NoddyObject),  /* tp_basicsize */

Это нужно, чтобы Python знал, сколько памяти выделять при вызове PyObject_New.

Примечание

Если вы хотите, чтобы ваш тип мог быть подклассом из Python, и ваш тип имеет такое же значение tp_basicsize, как и его базовый тип, у вас могут возникнуть проблемы с множественным наследованием. Подкласс Python вашего типа должен будет указывать ваш тип первым в своем __bases__, иначе он не сможет вызвать метод __new__() вашего типа без ошибки. Вы можете избежать этой проблемы, убедившись, что ваш тип имеет большее значение tp_basicsize, чем его базовый тип. В большинстве случаев это будет верно, потому что либо вашим базовым типом будет object, либо вы будете добавлять члены данных в базовый тип, тем самым увеличивая его размер.

0,                          /* tp_itemsize */

Это относится к объектам переменной длины, таким как списки и строки. Пока проигнорируйте это.

Пропуская ряд методов типа, которые мы не предоставляем, устанавливаем флаги класса в Py_TPFLAGS_DEFAULT.

Py_TPFLAGS_DEFAULT,        /* tp_flags */

Все типы должны включать эту константу в свои флаги. Она включает все члены, определённые текущей версией Python.

Строку документации для типа мы указываем в tp_doc.

"Noddy objects",           /* tp_doc */

Теперь мы переходим к методам типа – тому, что делает ваши объекты отличными от других. В этой версии модуля мы не будем реализовывать ни один из них. Позже мы расширим этот пример, добавив более интересное поведение.

Пока что всё, что нам нужно уметь делать, это создавать новые объекты Noddy. Чтобы включить создание объектов, нужно предоставить реализацию tp_new. В данном случае можно просто использовать реализацию по умолчанию, предоставляемую функцией API PyType_GenericNew. Хотелось бы просто присвоить это слоту tp_new, но из соображений переносимости это невозможно: на некоторых платформах или компиляторах нельзя статически инициализировать член структуры функцией, определённой в другом C-модуле. Поэтому присвоим слоту tp_new значение в функции инициализации модуля перед вызовом PyType_Ready:

noddy_NoddyType.tp_new = PyType_GenericNew;
if (PyType_Ready(&noddy_NoddyType) < 0)
    return;

Все остальные методы типа равны NULL, поэтому мы рассмотрим их позже – это для следующего раздела!

Всё остальное в файле должно быть знакомо, за исключением некоторого кода в PyInit_noddy:

if (PyType_Ready(&noddy_NoddyType) < 0)
    return;

Это инициализирует тип Noddy, заполняя ряд членов, включая ob_type, который изначально устанавливается в NULL.

PyModule_AddObject(m, "Noddy", (PyObject *)&noddy_NoddyType);

Это добавляет тип в словарь модуля. Это позволяет нам создавать экземпляры Noddy, вызывая класс Noddy:

>>> import noddy
>>> mynoddy = noddy.Noddy()

Вот и всё! Осталось только собрать это; поместите приведённый выше код в файл с именем noddy.c и

from distutils.core import setup, Extension
setup(name="noddy", version="1.0",
      ext_modules=[Extension("noddy", ["noddy.c"])])

в файл с именем setup.py; затем, набрав

$ python setup.py build

в командной оболочке, вы получите файл noddy.so в подкаталоге; перейдите в этот каталог и запустите Python – вы сможете выполнить import noddy и поиграться с объектами Noddy.

Было не так сложно, правда?

Конечно, текущий тип Noddy довольно неинтересен. У него нет данных и он ничего не делает. Его даже нельзя наследовать.

Добавление данных и методов к базовому примеру¶Adding data and methods to the Basic example

Расширим базовый пример, добавив некоторые данные и методы. Также сделаем тип пригодным для использования в качестве базового класса. Создадим новый модуль noddy2, который добавляет эти возможности:

#include <Python.h>
#include "structmember.h"

typedef struct {
    PyObject_HEAD
    PyObject *first; /* имя */
    PyObject *last;  /* фамилия */
    int number;
} Noddy;

static void
Noddy_dealloc(Noddy* self)
{
    Py_XDECREF(self->first);
    Py_XDECREF(self->last);
    Py_TYPE(self)->tp_free((PyObject*)self);
}

static PyObject *
Noddy_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
{
    Noddy *self;

    self = (Noddy *)type->tp_alloc(type, 0);
    if (self != NULL) {
        self->first = PyUnicode_FromString("");
        if (self->first == NULL)
          {
            Py_DECREF(self);
            return NULL;
          }
        
        self->last = PyUnicode_FromString("");
        if (self->last == NULL)
          {
            Py_DECREF(self);
            return NULL;
          }

        self->number = 0;
    }

    return (PyObject *)self;
}

static int
Noddy_init(Noddy *self, PyObject *args, PyObject *kwds)
{
    PyObject *first=NULL, *last=NULL, *tmp;

    static char *kwlist[] = {"first", "last", "number", NULL};

    if (! PyArg_ParseTupleAndKeywords(args, kwds, "|OOi", kwlist, 
                                      &first, &last, 
                                      &self->number))
        return -1; 

    if (first) {
        tmp = self->first;
        Py_INCREF(first);
        self->first = first;
        Py_XDECREF(tmp);
    }

    if (last) {
        tmp = self->last;
        Py_INCREF(last);
        self->last = last;
        Py_XDECREF(tmp);
    }

    return 0;
}


static PyMemberDef Noddy_members[] = {
    {"first", T_OBJECT_EX, offsetof(Noddy, first), 0,
     "first name"},
    {"last", T_OBJECT_EX, offsetof(Noddy, last), 0,
     "last name"},
    {"number", T_INT, offsetof(Noddy, number), 0,
     "noddy number"},
    {NULL}  /* Страж */
};

static PyObject *
Noddy_name(Noddy* self)
{
    static PyObject *format = NULL;
    PyObject *args, *result;

    if (format == NULL) {
        format = PyUnicode_FromString("%s %s");
        if (format == NULL)
            return NULL;
    }

    if (self->first == NULL) {
        PyErr_SetString(PyExc_AttributeError, "first");
        return NULL;
    }

    if (self->last == NULL) {
        PyErr_SetString(PyExc_AttributeError, "last");
        return NULL;
    }

    args = Py_BuildValue("OO", self->first, self->last);
    if (args == NULL)
        return NULL;

    result = PyUnicode_Format(format, args);
    Py_DECREF(args);
    
    return result;
}

static PyMethodDef Noddy_methods[] = {
    {"name", (PyCFunction)Noddy_name, METH_NOARGS,
     "Return the name, combining the first and last name"
    },
    {NULL}  /* Страж */
};

static PyTypeObject NoddyType = {
    PyObject_HEAD_INIT(NULL)
    "noddy.Noddy",             /* tp_name */
    sizeof(Noddy),             /* tp_basicsize */
    0,                         /* tp_itemsize */
    (destructor)Noddy_dealloc, /* tp_dealloc */
    0,                         /* tp_print */
    0,                         /* tp_getattr */
    0,                         /* tp_setattr */
    0,                         /* tp_reserved */
    0,                         /* tp_repr */
    0,                         /* tp_as_number */
    0,                         /* tp_as_sequence */
    0,                         /* tp_as_mapping */
    0,                         /* tp_hash  */
    0,                         /* tp_call */
    0,                         /* tp_str */
    0,                         /* tp_getattro */
    0,                         /* tp_setattro */
    0,                         /* tp_as_buffer */
    Py_TPFLAGS_DEFAULT |
        Py_TPFLAGS_BASETYPE,   /* tp_flags */
    "Noddy objects",           /* tp_doc */
    0,		               /* tp_traverse */
    0,		               /* tp_clear */
    0,		               /* tp_richcompare */
    0,		               /* tp_weaklistoffset */
    0,		               /* tp_iter */
    0,		               /* tp_iternext */
    Noddy_methods,             /* tp_methods */
    Noddy_members,             /* tp_members */
    0,                         /* tp_getset */
    0,                         /* tp_base */
    0,                         /* tp_dict */
    0,                         /* tp_descr_get */
    0,                         /* tp_descr_set */
    0,                         /* tp_dictoffset */
    (initproc)Noddy_init,      /* tp_init */
    0,                         /* tp_alloc */
    Noddy_new,                 /* tp_new */
};

static PyModuleDef noddy2module = {
    PyModuleDef_HEAD_INIT,
    "noddy2",
    "Example module that creates an extension type.",
    -1,
    NULL, NULL, NULL, NULL, NULL
};

PyMODINIT_FUNC
PyInit_noddy2(void) 
{
    PyObject* m;

    if (PyType_Ready(&NoddyType) < 0)
        return NULL;

    m = PyModule_Create(&noddy2module);
    if (m == NULL)
        return NULL;

    Py_INCREF(&NoddyType);
    PyModule_AddObject(m, "Noddy", (PyObject *)&NoddyType);
    return m;
}

Эта версия модуля содержит ряд изменений.

Мы добавили дополнительный include:

#include "structmember.h"

Этот include предоставляет объявления, которые мы используем для обработки атрибутов, как описано немного позже.

Имя структуры объекта Noddy было сокращено до Noddy. Имя объекта типа сокращено до NoddyType.

Тип Noddy теперь имеет три атрибута данных: first, last и number. Переменные first и last – это строки Python, содержащие имя и фамилию. Атрибут number – целое число.

Структура объекта обновляется соответствующим образом:

typedef struct {
    PyObject_HEAD
    PyObject *first;
    PyObject *last;
    int number;
} Noddy;

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

static void
Noddy_dealloc(Noddy* self)
{
    Py_XDECREF(self->first);
    Py_XDECREF(self->last);
    Py_TYPE(self)->tp_free((PyObject*)self);
}

которое присваивается члену tp_dealloc:

(destructor)Noddy_dealloc, /*tp_dealloc*/

Этот метод уменьшает счётчики ссылок двух атрибутов Python. Здесь используется Py_XDECREF, потому что члены first и last могут быть NULL. Затем он вызывает член tp_free типа объекта, чтобы освободить память объекта. Обратите внимание, что тип объекта может не быть NoddyType, потому что объект может быть экземпляром подкласса.

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

static PyObject *
Noddy_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
{
    Noddy *self;

    self = (Noddy *)type->tp_alloc(type, 0);
    if (self != NULL) {
        self->first = PyString_FromString("");
        if (self->first == NULL)
          {
            Py_DECREF(self);
            return NULL;
          }

        self->last = PyString_FromString("");
        if (self->last == NULL)
          {
            Py_DECREF(self);
            return NULL;
          }

        self->number = 0;
    }

    return (PyObject *)self;
}

и устанавливаем его в член tp_new:

Noddy_new,                 /* tp_new */

Член new отвечает за создание (в отличие от инициализации) объектов типа. Он доступен в Python как метод __new__(). Подробное обсуждение метода __new__() приведено в статье «Unifying types and classes in Python». Одна из причин реализовать метод new – гарантировать начальные значения переменных экземпляра. В данном случае мы используем метод new, чтобы убедиться, что начальные значения членов first и last не равны NULL. Если бы нас не волновало, что начальные значения равны NULL, можно было бы использовать PyType_GenericNew в качестве метода new, как и раньше. PyType_GenericNew инициализирует все переменные-члены экземпляра значением NULL.

Метод new – это статический метод, которому передаются тип, создаваемый экземпляр, и любые аргументы, переданные при вызове типа, и который возвращает созданный новый объект. Методы new всегда принимают позиционные и именованные аргументы, но часто игнорируют их, оставляя обработку аргументов методам инициализации. Обратите внимание: если тип поддерживает создание подклассов, переданный тип может не быть определяемым типом. Метод new вызывает слот tp_alloc для выделения памяти. Мы не заполняем слот tp_alloc самостоятельно. Вместо этого PyType_Ready заполняет его, наследуя от базового класса, который по умолчанию является object. Большинство типов используют выделение по умолчанию.

Примечание

Если вы создаёте кооперативный tp_new (тот, который вызывает tp_new базового типа или __new__()), вы не должны пытаться определить, какой метод вызывать, используя порядок разрешения методов во время выполнения. Всегда статически определяйте, какой тип вы собираетесь вызвать, и вызывайте его tp_new напрямую или через type->tp_base->tp_new. Если этого не сделать, подклассы вашего типа в Python, которые также наследуют от других классов, определённых в Python, могут работать некорректно. (В частности, вы не сможете создавать экземпляры таких подклассов без получения TypeError.)

Мы предоставляем функцию инициализации:

static int
Noddy_init(Noddy *self, PyObject *args, PyObject *kwds)
{
    PyObject *first=NULL, *last=NULL, *tmp;

    static char *kwlist[] = {"first", "last", "number", NULL};

    if (! PyArg_ParseTupleAndKeywords(args, kwds, "|OOi", kwlist,
                                      &first, &last,
                                      &self->number))
        return -1;

    if (first) {
        tmp = self->first;
        Py_INCREF(first);
        self->first = first;
        Py_XDECREF(tmp);
    }

    if (last) {
        tmp = self->last;
        Py_INCREF(last);
        self->last = last;
        Py_XDECREF(tmp);
    }

    return 0;
}

заполнив слот tp_init.

(initproc)Noddy_init,         /* tp_init */

Слот tp_init доступен в Python как метод __init__(). Он используется для инициализации объекта после его создания. В отличие от метода new, нельзя гарантировать, что инициализатор будет вызван. Инициализатор не вызывается при распаковке объектов и может быть переопределён. Наш инициализатор принимает аргументы для начальных значений экземпляра. Инициализаторы всегда принимают позиционные и именованные аргументы.

Инициализаторы могут вызываться несколько раз. Любой может вызвать метод __init__() на наших объектах. Поэтому нужно быть особенно осторожными при присваивании новых значений. Например, можно было бы попытаться присвоить члену first значение так:

if (first) {
    Py_XDECREF(self->first);
    Py_INCREF(first);
    self->first = first;
}

Но это было бы рискованно. Наш тип не ограничивает тип члена first, поэтому он может быть объектом любого типа. У него может быть деструктор, который вызывает код, пытающийся обратиться к члену first. Чтобы быть предусмотрительными и защититься от такой возможности, мы почти всегда переприсваиваем члены перед уменьшением их счётчиков ссылок. Когда же этого делать не нужно?

когда точно известно, что счётчик ссылок больше 1
когда известно, что освобождение объекта [1] не вызовет никаких вызовов обратно в код нашего типа
при уменьшении счётчика ссылок в обработчике tp_dealloc, когда сборка мусора не поддерживается [2]

Мы хотим предоставить доступ к переменным экземпляра как к атрибутам. Есть несколько способов сделать это. Самый простой – определить определения членов:

static PyMemberDef Noddy_members[] = {
    {"first", T_OBJECT_EX, offsetof(Noddy, first), 0,
     "first name"},
    {"last", T_OBJECT_EX, offsetof(Noddy, last), 0,
     "last name"},
    {"number", T_INT, offsetof(Noddy, number), 0,
     "noddy number"},
    {NULL}  /* Страж */
};

и поместите определения в слот tp_members:

Noddy_members,             /* tp_members */

Каждое определение члена содержит имя члена, тип, смещение, флаги доступа и строку документации. Подробнее см. раздел «Generic Attribute Management» ниже.

Недостаток такого подхода в том, что он не позволяет ограничить типы объектов, которые могут быть присвоены атрибутам Python. Мы ожидаем, что имя и фамилия будут строками, но можно присвоить любые объекты Python. Более того, атрибуты можно удалять, устанавливая C-указатели в NULL. Даже если мы можем гарантировать, что члены инициализированы не-NULL значениями, эти члены могут быть установлены в NULL, если атрибуты удалены.

Определяем один метод name(), который выводит имя объекта как объединение имени и фамилии.

static PyObject *
Noddy_name(Noddy* self)
{
    static PyObject *format = NULL;
    PyObject *args, *result;

    if (format == NULL) {
        format = PyString_FromString("%s %s");
        if (format == NULL)
            return NULL;
    }

    if (self->first == NULL) {
        PyErr_SetString(PyExc_AttributeError, "first");
        return NULL;
    }

    if (self->last == NULL) {
        PyErr_SetString(PyExc_AttributeError, "last");
        return NULL;
    }

    args = Py_BuildValue("OO", self->first, self->last);
    if (args == NULL)
        return NULL;

    result = PyString_Format(format, args);
    Py_DECREF(args);

    return result;
}

Метод реализован как C-функция, которая принимает экземпляр Noddy (или подкласса Noddy) в качестве первого аргумента. Методы всегда принимают экземпляр как первый аргумент. Методы часто также принимают позиционные и именованные аргументы, но в данном случае мы не принимаем никаких и не нуждаемся в принятии кортежа позиционных аргументов или словаря именованных аргументов. Этот метод эквивалентен следующему методу Python:

def name(self):
   return "%s %s" % (self.first, self.last)

Обратите внимание, что нужно проверять возможность того, что наши члены first и last равны NULL. Это связано с тем, что их можно удалить, и в этом случае они устанавливаются в NULL. Было бы лучше предотвратить удаление этих атрибутов и ограничить значения атрибутов строками. Мы увидим, как это сделать, в следующем разделе.

Теперь, когда мы определили метод, нужно создать массив определений методов:

static PyMethodDef Noddy_methods[] = {
    {"name", (PyCFunction)Noddy_name, METH_NOARGS,
     "Return the name, combining the first and last name"
    },
    {NULL}  /* Страж */
};

и назначаем их в слот tp_methods:

Noddy_methods,             /* tp_methods */

Обратите внимание, что мы использовали флаг METH_NOARGS, чтобы указать, что методу не передаются аргументы.

Наконец, сделаем наш тип пригодным для использования в качестве базового класса. До сих пор мы писали наши методы осторожно, чтобы они не делали предположений о типе создаваемого или используемого объекта, поэтому всё, что нам нужно сделать, это добавить Py_TPFLAGS_BASETYPE в определение флагов нашего класса:

Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /*tp_flags*/

Мы переименовываем PyInit_noddy в PyInit_noddy2 и обновляем имя модуля в структуре PyModuleDef.

Наконец, обновляем наш файл setup.py для сборки нового модуля:

from distutils.core import setup, Extension
setup(name="noddy", version="1.0",
      ext_modules=[
         Extension("noddy", ["noddy.c"]),
         Extension("noddy2", ["noddy2.c"]),
         ])

Более тонкое управление атрибутами данных¶Providing finer control over data attributes

В этом разделе мы обеспечим более тонкий контроль над тем, как устанавливаются атрибуты first и last в примере Noddy. В предыдущей версии нашего модуля переменные экземпляра first и last могли быть установлены в нестроковые значения или даже удалены. Мы хотим гарантировать, что эти атрибуты всегда содержат строки.

#include <Python.h>
#include "structmember.h"

typedef struct {
    PyObject_HEAD
    PyObject *first;
    PyObject *last;
    int number;
} Noddy;

static void
Noddy_dealloc(Noddy* self)
{
    Py_XDECREF(self->first);
    Py_XDECREF(self->last);
    Py_TYPE(self)->tp_free((PyObject*)self);
}

static PyObject *
Noddy_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
{
    Noddy *self;

    self = (Noddy *)type->tp_alloc(type, 0);
    if (self != NULL) {
        self->first = PyUnicode_FromString("");
        if (self->first == NULL)
          {
            Py_DECREF(self);
            return NULL;
          }
        
        self->last = PyUnicode_FromString("");
        if (self->last == NULL)
          {
            Py_DECREF(self);
            return NULL;
          }

        self->number = 0;
    }

    return (PyObject *)self;
}

static int
Noddy_init(Noddy *self, PyObject *args, PyObject *kwds)
{
    PyObject *first=NULL, *last=NULL, *tmp;

    static char *kwlist[] = {"first", "last", "number", NULL};

    if (! PyArg_ParseTupleAndKeywords(args, kwds, "|SSi", kwlist, 
                                      &first, &last, 
                                      &self->number))
        return -1; 

    if (first) {
        tmp = self->first;
        Py_INCREF(first);
        self->first = first;
        Py_DECREF(tmp);
    }

    if (last) {
        tmp = self->last;
        Py_INCREF(last);
        self->last = last;
        Py_DECREF(tmp);
    }

    return 0;
}

static PyMemberDef Noddy_members[] = {
    {"number", T_INT, offsetof(Noddy, number), 0,
     "noddy number"},
    {NULL}  /* Страж */
};

static PyObject *
Noddy_getfirst(Noddy *self, void *closure)
{
    Py_INCREF(self->first);
    return self->first;
}

static int
Noddy_setfirst(Noddy *self, PyObject *value, void *closure)
{
  if (value == NULL) {
    PyErr_SetString(PyExc_TypeError, "Cannot delete the first attribute");
    return -1;
  }
  
  if (! PyUnicode_Check(value)) {
    PyErr_SetString(PyExc_TypeError, 
                    "The first attribute value must be a string");
    return -1;
  }
      
  Py_DECREF(self->first);
  Py_INCREF(value);
  self->first = value;    

  return 0;
}

static PyObject *
Noddy_getlast(Noddy *self, void *closure)
{
    Py_INCREF(self->last);
    return self->last;
}

static int
Noddy_setlast(Noddy *self, PyObject *value, void *closure)
{
  if (value == NULL) {
    PyErr_SetString(PyExc_TypeError, "Cannot delete the last attribute");
    return -1;
  }
  
  if (! PyUnicode_Check(value)) {
    PyErr_SetString(PyExc_TypeError, 
                    "The last attribute value must be a string");
    return -1;
  }
      
  Py_DECREF(self->last);
  Py_INCREF(value);
  self->last = value;    

  return 0;
}

static PyGetSetDef Noddy_getseters[] = {
    {"first", 
     (getter)Noddy_getfirst, (setter)Noddy_setfirst,
     "first name",
     NULL},
    {"last", 
     (getter)Noddy_getlast, (setter)Noddy_setlast,
     "last name",
     NULL},
    {NULL}  /* Страж */
};

static PyObject *
Noddy_name(Noddy* self)
{
    static PyObject *format = NULL;
    PyObject *args, *result;

    if (format == NULL) {
        format = PyUnicode_FromString("%s %s");
        if (format == NULL)
            return NULL;
    }

    args = Py_BuildValue("OO", self->first, self->last);
    if (args == NULL)
        return NULL;

    result = PyUnicode_Format(format, args);
    Py_DECREF(args);
    
    return result;
}

static PyMethodDef Noddy_methods[] = {
    {"name", (PyCFunction)Noddy_name, METH_NOARGS,
     "Return the name, combining the first and last name"
    },
    {NULL}  /* Страж */
};

static PyTypeObject NoddyType = {
    PyObject_HEAD_INIT(NULL)
    "noddy.Noddy",             /* tp_name */
    sizeof(Noddy),             /* tp_basicsize */
    0,                         /* tp_itemsize */
    (destructor)Noddy_dealloc, /* tp_dealloc */
    0,                         /* tp_print */
    0,                         /* tp_getattr */
    0,                         /* tp_setattr */
    0,                         /* tp_reserved */
    0,                         /* tp_repr */
    0,                         /* tp_as_number */
    0,                         /* tp_as_sequence */
    0,                         /* tp_as_mapping */
    0,                         /* tp_hash  */
    0,                         /* tp_call */
    0,                         /* tp_str */
    0,                         /* tp_getattro */
    0,                         /* tp_setattro */
    0,                         /* tp_as_buffer */
    Py_TPFLAGS_DEFAULT |
        Py_TPFLAGS_BASETYPE,   /* tp_flags */
    "Noddy objects",           /* tp_doc */
    0,		               /* tp_traverse */
    0,		               /* tp_clear */
    0,		               /* tp_richcompare */
    0,		               /* tp_weaklistoffset */
    0,		               /* tp_iter */
    0,		               /* tp_iternext */
    Noddy_methods,             /* tp_methods */
    Noddy_members,             /* tp_members */
    Noddy_getseters,           /* tp_getset */
    0,                         /* tp_base */
    0,                         /* tp_dict */
    0,                         /* tp_descr_get */
    0,                         /* tp_descr_set */
    0,                         /* tp_dictoffset */
    (initproc)Noddy_init,      /* tp_init */
    0,                         /* tp_alloc */
    Noddy_new,                 /* tp_new */
};

static PyModuleDef noddy3module = {
    PyModuleDef_HEAD_INIT,
    "noddy3",
    "Example module that creates an extension type.",
    -1,
    NULL, NULL, NULL, NULL, NULL
};

PyMODINIT_FUNC
PyInit_noddy3(void) 
{
    PyObject* m;

    if (PyType_Ready(&NoddyType) < 0)
        return NULL;

    m = PyModule_Create(&noddy3module);
    if (m == NULL)
        return NULL;

    Py_INCREF(&NoddyType);
    PyModule_AddObject(m, "Noddy", (PyObject *)&NoddyType);
    return m;
}

Чтобы обеспечить больший контроль над атрибутами first и last, мы будем использовать пользовательские функции получения и установки. Вот функции для получения и установки атрибута first:

Noddy_getfirst(Noddy *self, void *closure)
{
    Py_INCREF(self->first);
    return self->first;
}

static int
Noddy_setfirst(Noddy *self, PyObject *value, void *closure)
{
  if (value == NULL) {
    PyErr_SetString(PyExc_TypeError, "Cannot delete the first attribute");
    return -1;
  }

  if (! PyString_Check(value)) {
    PyErr_SetString(PyExc_TypeError,
                    "The first attribute value must be a string");
    return -1;
  }

  Py_DECREF(self->first);
  Py_INCREF(value);
  self->first = value;

  return 0;
}

Функции получения передаётся объект Noddy и «замыкание», которое является указателем void. В данном случае замыкание игнорируется. (Замыкание поддерживает расширенное использование, при котором данные определения передаются функциям получения и установки. Это, например, можно использовать, чтобы позволить единому набору функций получения и установки решать, какой атрибут получать или устанавливать, на основе данных в замыкании.)

Функции установки передаётся объект Noddy, новое значение и замыкание. Новое значение может быть NULL, в этом случае атрибут удаляется. В нашей функции установки мы вызываем ошибку, если атрибут удаляется или если значение атрибута не является строкой.

Создаём массив структур PyGetSetDef:

static PyGetSetDef Noddy_getseters[] = {
    {"first",
     (getter)Noddy_getfirst, (setter)Noddy_setfirst,
     "first name",
     NULL},
    {"last",
     (getter)Noddy_getlast, (setter)Noddy_setlast,
     "last name",
     NULL},
    {NULL}  /* Страж */
};

и регистрируем его в слоте tp_getset:

Noddy_getseters,           /* tp_getset */

для регистрации геттеров и сеттеров наших атрибутов.

Последний элемент структуры PyGetSetDef – это упомянутое выше замыкание. В данном случае мы не используем замыкание, поэтому просто передаём NULL.

Также удаляем определения членов для этих атрибутов:

static PyMemberDef Noddy_members[] = {
    {"number", T_INT, offsetof(Noddy, number), 0,
     "noddy number"},
    {NULL}  /* Страж */
};

Также необходимо обновить обработчик tp_init, чтобы разрешить передачу только строк [3]:

static int
Noddy_init(Noddy *self, PyObject *args, PyObject *kwds)
{
    PyObject *first=NULL, *last=NULL, *tmp;

    static char *kwlist[] = {"first", "last", "number", NULL};

    if (! PyArg_ParseTupleAndKeywords(args, kwds, "|SSi", kwlist,
                                      &first, &last,
                                      &self->number))
        return -1;

    if (first) {
        tmp = self->first;
        Py_INCREF(first);
        self->first = first;
        Py_DECREF(tmp);
    }

    if (last) {
        tmp = self->last;
        Py_INCREF(last);
        self->last = last;
        Py_DECREF(tmp);
    }

    return 0;
}

Благодаря этим изменениям можно гарантировать, что члены first и last никогда не будут NULL, так что проверки на NULL можно удалить почти во всех случаях. Это означает, что большинство вызовов Py_XDECREF можно заменить на Py_DECREF. Единственное место, где эти вызовы нельзя изменить – деаллокатор, так как существует вероятность, что инициализация этих членов не удалась в конструкторе.

Также переименовываем функцию инициализации модуля и имя модуля в функции инициализации, как мы делали ранее, и добавляем дополнительное определение в файл setup.py.

Поддержка циклической сборки мусора¶Supporting cyclic garbage collection

В Python есть циклический сборщик мусора, который может обнаруживать ненужные объекты даже когда их счётчики ссылок не равны нулю. Это может происходить, когда объекты участвуют в циклах. Например, рассмотрим:

>>> l = []
>>> l.append(l)
>>> del l

В этом примере мы создаём список, который содержит сам себя. Когда мы его удаляем, у него всё ещё есть ссылка от самого себя. Его счётчик ссылок не падает до нуля. К счастью, циклический сборщик мусора Python в конечном итоге определит, что список является мусором, и освободит его.

Во второй версии примера Noddy мы разрешили хранить объекты любого типа в атрибутах first или last. [4] Это означает, что объекты Noddy могут участвовать в циклах:

>>> import noddy2
>>> n = noddy2.Noddy()
>>> l = [n]
>>> n.first = l

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

#include <Python.h>
#include "structmember.h"

typedef struct {
    PyObject_HEAD
    PyObject *first;
    PyObject *last;
    int number;
} Noddy;

static int
Noddy_traverse(Noddy *self, visitproc visit, void *arg)
{
    int vret;

    if (self->first) {
        vret = visit(self->first, arg);
        if (vret != 0)
            return vret;
    }
    if (self->last) {
        vret = visit(self->last, arg);
        if (vret != 0)
            return vret;
    }

    return 0;
}

static int 
Noddy_clear(Noddy *self)
{
    PyObject *tmp;

    tmp = self->first;
    self->first = NULL;
    Py_XDECREF(tmp);

    tmp = self->last;
    self->last = NULL;
    Py_XDECREF(tmp);

    return 0;
}

static void
Noddy_dealloc(Noddy* self)
{
    Noddy_clear(self);
    Py_TYPE(self)->tp_free((PyObject*)self);
}

static PyObject *
Noddy_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
{
    Noddy *self;

    self = (Noddy *)type->tp_alloc(type, 0);
    if (self != NULL) {
        self->first = PyUnicode_FromString("");
        if (self->first == NULL)
          {
            Py_DECREF(self);
            return NULL;
          }
        
        self->last = PyUnicode_FromString("");
        if (self->last == NULL)
          {
            Py_DECREF(self);
            return NULL;
          }

        self->number = 0;
    }

    return (PyObject *)self;
}

static int
Noddy_init(Noddy *self, PyObject *args, PyObject *kwds)
{
    PyObject *first=NULL, *last=NULL, *tmp;

    static char *kwlist[] = {"first", "last", "number", NULL};

    if (! PyArg_ParseTupleAndKeywords(args, kwds, "|OOi", kwlist, 
                                      &first, &last, 
                                      &self->number))
        return -1; 

    if (first) {
        tmp = self->first;
        Py_INCREF(first);
        self->first = first;
        Py_XDECREF(tmp);
    }

    if (last) {
        tmp = self->last;
        Py_INCREF(last);
        self->last = last;
        Py_XDECREF(tmp);
    }

    return 0;
}


static PyMemberDef Noddy_members[] = {
    {"first", T_OBJECT_EX, offsetof(Noddy, first), 0,
     "first name"},
    {"last", T_OBJECT_EX, offsetof(Noddy, last), 0,
     "last name"},
    {"number", T_INT, offsetof(Noddy, number), 0,
     "noddy number"},
    {NULL}  /* Страж */
};

static PyObject *
Noddy_name(Noddy* self)
{
    static PyObject *format = NULL;
    PyObject *args, *result;

    if (format == NULL) {
        format = PyUnicode_FromString("%s %s");
        if (format == NULL)
            return NULL;
    }

    if (self->first == NULL) {
        PyErr_SetString(PyExc_AttributeError, "first");
        return NULL;
    }

    if (self->last == NULL) {
        PyErr_SetString(PyExc_AttributeError, "last");
        return NULL;
    }

    args = Py_BuildValue("OO", self->first, self->last);
    if (args == NULL)
        return NULL;

    result = PyUnicode_Format(format, args);
    Py_DECREF(args);
    
    return result;
}

static PyMethodDef Noddy_methods[] = {
    {"name", (PyCFunction)Noddy_name, METH_NOARGS,
     "Return the name, combining the first and last name"
    },
    {NULL}  /* Страж */
};

static PyTypeObject NoddyType = {
    PyObject_HEAD_INIT(NULL)
    "noddy.Noddy",             /* tp_name */
    sizeof(Noddy),             /* tp_basicsize */
    0,                         /* tp_itemsize */
    (destructor)Noddy_dealloc, /* tp_dealloc */
    0,                         /* tp_print */
    0,                         /* tp_getattr */
    0,                         /* tp_setattr */
    0,                         /* tp_reserved */
    0,                         /* tp_repr */
    0,                         /* tp_as_number */
    0,                         /* tp_as_sequence */
    0,                         /* tp_as_mapping */
    0,                         /* tp_hash  */
    0,                         /* tp_call */
    0,                         /* tp_str */
    0,                         /* tp_getattro */
    0,                         /* tp_setattro */
    0,                         /* tp_as_buffer */
    Py_TPFLAGS_DEFAULT |
        Py_TPFLAGS_BASETYPE |
        Py_TPFLAGS_HAVE_GC,    /* tp_flags */
    "Noddy objects",           /* tp_doc */
    (traverseproc)Noddy_traverse,   /* tp_traverse */
    (inquiry)Noddy_clear,           /* tp_clear */
    0,		               /* tp_richcompare */
    0,		               /* tp_weaklistoffset */
    0,		               /* tp_iter */
    0,		               /* tp_iternext */
    Noddy_methods,             /* tp_methods */
    Noddy_members,             /* tp_members */
    0,                         /* tp_getset */
    0,                         /* tp_base */
    0,                         /* tp_dict */
    0,                         /* tp_descr_get */
    0,                         /* tp_descr_set */
    0,                         /* tp_dictoffset */
    (initproc)Noddy_init,      /* tp_init */
    0,                         /* tp_alloc */
    Noddy_new,                 /* tp_new */
};

static PyModuleDef noddy4module = {
    PyModuleDef_HEAD_INIT,
    "noddy4",
    "Example module that creates an extension type.",
    -1,
    NULL, NULL, NULL, NULL, NULL
};

PyMODINIT_FUNC
PyInit_noddy4(void) 
{
    PyObject* m;

    if (PyType_Ready(&NoddyType) < 0)
        return NULL;

    m = PyModule_Create(&noddy4module);
    if (m == NULL)
        return NULL;

    Py_INCREF(&NoddyType);
    PyModule_AddObject(m, "Noddy", (PyObject *)&NoddyType);
    return m;
}

Метод обхода (traversal) предоставляет доступ к подобъектам, которые могут участвовать в циклах:

static int
Noddy_traverse(Noddy *self, visitproc visit, void *arg)
{
    int vret;

    if (self->first) {
        vret = visit(self->first, arg);
        if (vret != 0)
            return vret;
    }
    if (self->last) {
        vret = visit(self->last, arg);
        if (vret != 0)
            return vret;
    }

    return 0;
}

Для каждого подобъекта, который может участвовать в циклах, нужно вызвать функцию visit, которая передаётся методу обхода. Функция visit принимает в качестве аргументов подобъект и дополнительный аргумент arg, переданный методу обхода. Она возвращает целое значение, которое должно быть возвращено, если оно не равно нулю.

Python предоставляет макрос Py_VISIT, который автоматизирует вызов функций visit. С Py_VISIT функцию Noddy_traverse можно упростить:

static int
Noddy_traverse(Noddy *self, visitproc visit, void *arg)
{
    Py_VISIT(self->first);
    Py_VISIT(self->last);
    return 0;
}

Примечание

Обратите внимание, что в реализации tp_traverse аргументы должны называться именно visit и arg, чтобы можно было использовать Py_VISIT. Это сделано для единообразия в этих скучных реализациях.

Также необходимо предоставить метод для очистки любых подобъектов, которые могут участвовать в циклах. Реализуем этот метод и перереализуем деаллокатор для его использования:

static int
Noddy_clear(Noddy *self)
{
    PyObject *tmp;

    tmp = self->first;
    self->first = NULL;
    Py_XDECREF(tmp);

    tmp = self->last;
    self->last = NULL;
    Py_XDECREF(tmp);

    return 0;
}

static void
Noddy_dealloc(Noddy* self)
{
    Noddy_clear(self);
    Py_TYPE(self)->tp_free((PyObject*)self);
}

Обратите внимание на использование временной переменной в Noddy_clear. Временная переменная нужна, чтобы можно было установить каждый член в NULL перед уменьшением его счётчика ссылок. Это делается потому, что, как обсуждалось ранее, если счётчик ссылок упадёт до нуля, может быть запущен код, который вызовет обращение к объекту. Кроме того, теперь, когда поддерживается сборка мусора, нужно также опасаться кода, который может запустить сборку мусора. Если сборка мусора будет запущена, может быть вызван наш обработчик tp_traverse. Нельзя допустить, чтобы Noddy_traverse был вызван, когда счётчик ссылок члена упал до нуля, а его значение ещё не установлено в NULL.

Python предоставляет макрос Py_CLEAR, который автоматизирует аккуратное уменьшение счётчиков ссылок. С Py_CLEAR функцию Noddy_clear можно упростить:

static int
Noddy_clear(Noddy *self)
{
    Py_CLEAR(self->first);
    Py_CLEAR(self->last);
    return 0;
}

Наконец, добавляем флаг Py_TPFLAGS_HAVE_GC в флаги класса:

Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC, /* tp_flags */

В общем, это всё. Если бы мы написали пользовательские слоты tp_alloc или tp_free, их нужно было бы изменить для циклической сборки мусора. Большинство расширений будут использовать автоматически предоставленные версии.

Наследование от других типов¶Subclassing other types

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

В этом примере мы создадим тип Shoddy, наследующий от встроенного типа list. Новый тип будет полностью совместим с обычными списками, но будет иметь дополнительный метод increment(), который увеличивает внутренний счётчик.

>>> import shoddy
>>> s = shoddy.Shoddy(range(3))
>>> s.extend(s)
>>> print(len(s))
6
>>> print(s.increment())
1
>>> print(s.increment())
2

#include <Python.h>

typedef struct {
    PyListObject list;
    int state;
} Shoddy;


static PyObject *
Shoddy_increment(Shoddy *self, PyObject *unused)
{
    self->state++;
    return PyLong_FromLong(self->state);
}


static PyMethodDef Shoddy_methods[] = {
    {"increment", (PyCFunction)Shoddy_increment, METH_NOARGS,
     PyDoc_STR("increment state counter")},
    {NULL,	NULL},
};

static int
Shoddy_init(Shoddy *self, PyObject *args, PyObject *kwds)
{
    if (PyList_Type.tp_init((PyObject *)self, args, kwds) < 0)
        return -1;
    self->state = 0;
    return 0;
}


static PyTypeObject ShoddyType = {
    PyObject_HEAD_INIT(NULL)
    "shoddy.Shoddy",         /* tp_name */
    sizeof(Shoddy),          /* tp_basicsize */
    0,                       /* tp_itemsize */
    0,                       /* tp_dealloc */
    0,                       /* tp_print */
    0,                       /* tp_getattr */
    0,                       /* tp_setattr */
    0,                       /* tp_reserved */
    0,                       /* tp_repr */
    0,                       /* tp_as_number */
    0,                       /* tp_as_sequence */
    0,                       /* tp_as_mapping */
    0,                       /* tp_hash */
    0,                       /* tp_call */
    0,                       /* tp_str */
    0,                       /* tp_getattro */
    0,                       /* tp_setattro */
    0,                       /* tp_as_buffer */
    Py_TPFLAGS_DEFAULT |
        Py_TPFLAGS_BASETYPE, /* tp_flags */
    0,                       /* tp_doc */
    0,                       /* tp_traverse */
    0,                       /* tp_clear */
    0,                       /* tp_richcompare */
    0,                       /* tp_weaklistoffset */
    0,                       /* tp_iter */
    0,                       /* tp_iternext */
    Shoddy_methods,          /* tp_methods */
    0,                       /* tp_members */
    0,                       /* tp_getset */
    0,                       /* tp_base */
    0,                       /* tp_dict */
    0,                       /* tp_descr_get */
    0,                       /* tp_descr_set */
    0,                       /* tp_dictoffset */
    (initproc)Shoddy_init,   /* tp_init */
    0,                       /* tp_alloc */
    0,                       /* tp_new */
};

static PyModuleDef shoddymodule = {
    PyModuleDef_HEAD_INIT,
    "shoddy",
    "Shoddy module",
    -1,
    NULL, NULL, NULL, NULL, NULL
};

PyMODINIT_FUNC
PyInit_shoddy(void)
{
    PyObject *m;

    ShoddyType.tp_base = &PyList_Type;
    if (PyType_Ready(&ShoddyType) < 0)
        return NULL;

    m = PyModule_Create(&shoddymodule);
    if (m == NULL)
        return NULL;

    Py_INCREF(&ShoddyType);
    PyModule_AddObject(m, "Shoddy", (PyObject *) &ShoddyType);
}

Как видите, исходный код очень похож на примеры Noddy из предыдущих разделов. Разберём основные различия между ними.

typedef struct {
    PyListObject list;
    int state;
} Shoddy;

Основное отличие для объектов производного типа заключается в том, что структура объекта базового типа должна быть первым значением. Базовый тип уже будет включать PyObject_HEAD в начале своей структуры.

Когда объект Python является экземпляром Shoddy, его указатель PyObject* можно безопасно приводить как к PyListObject*, так и к Shoddy*.

static int
Shoddy_init(Shoddy *self, PyObject *args, PyObject *kwds)
{
    if (PyList_Type.tp_init((PyObject *)self, args, kwds) < 0)
       return -1;
    self->state = 0;
    return 0;
}

В методе __init__ нашего типа видно, как вызвать метод __init__ базового типа.

Этот шаблон важен при написании типа с пользовательскими методами new и dealloc. Метод new не должен непосредственно выделять память для объекта с помощью tp_alloc – это будет сделано базовым классом при вызове его tp_new.

При заполнении PyTypeObject для типа Shoddy есть слот для tp_base. Из-за проблем с межплатформенными компиляторами нельзя заполнить это поле напрямую PyList_Type; это можно сделать позже в функции init модуля.

PyMODINIT_FUNC
PyInit_shoddy(void)
{
    PyObject *m;

    ShoddyType.tp_base = &PyList_Type;
    if (PyType_Ready(&ShoddyType) < 0)
        return NULL;

    m = PyModule_Create(&shoddymodule);
    if (m == NULL)
        return NULL;

    Py_INCREF(&ShoddyType);
    PyModule_AddObject(m, "Shoddy", (PyObject *) &ShoddyType);
}

Перед вызовом PyType_Ready слот tp_base в структуре типа должен быть заполнен. При создании производного типа необязательно заполнять слот tp_alloc значением PyType_GenericNew – функция выделения памяти будет унаследована от базового типа.

После этого вызов PyType_Ready и добавление объекта типа в модуль выполняются так же, как в базовых примерах с Noddy.

Методы типа¶Type Methods

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

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

typedef struct _typeobject {
    PyObject_VAR_HEAD
    char *tp_name; /* Для вывода в формате "<module>.<name>" */
    int tp_basicsize, tp_itemsize; /* Для выделения памяти */

    /* Методы для реализации стандартных операций */

    destructor tp_dealloc;
    printfunc tp_print;
    getattrfunc tp_getattr;
    setattrfunc tp_setattr;
    void *tp_reserved;
    reprfunc tp_repr;

    /* Наборы методов для стандартных классов */

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

    /* Дополнительные стандартные операции (здесь для двоичной совместимости) */

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

    /* Функции для доступа к объекту как к буферу ввода/вывода */
    PyBufferProcs *tp_as_buffer;

    /* Флаги для определения наличия опциональных/расширенных возможностей */
    long tp_flags;

    char *tp_doc; /* Строка документации */

    /* вызов функции для всех доступных объектов */
    traverseproc tp_traverse;

    /* удаление ссылок на содержащиеся объекты */
    inquiry tp_clear;

    /* расширенные сравнения */
    richcmpfunc tp_richcompare;

    /* включение слабых ссылок */
    long tp_weaklistoffset;

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

    /* Дескриптор атрибутов и механизмы подклассов */
    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;
    long tp_dictoffset;
    initproc tp_init;
    allocfunc tp_alloc;
    newfunc tp_new;
    freefunc tp_free; /* Низкоуровневая процедура освобождения памяти */
    inquiry tp_is_gc; /* Для PyObject_IS_GC */
    PyObject *tp_bases;
    PyObject *tp_mro; /* порядок разрешения методов */
    PyObject *tp_cache;
    PyObject *tp_subclasses;
    PyObject *tp_weaklist;

} PyTypeObject;

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

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

char *tp_name; /* Для вывода */

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

int tp_basicsize, tp_itemsize; /* Для выделения памяти */

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

char *tp_doc;

Сюда можно поместить строку (или её адрес), которая должна возвращаться, когда скрипт на Python обращается к obj.__doc__ для получения строки документации.

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

Финализация и освобождение памяти¶Finalization and De-allocation

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;
        int have_error = PyErr_Occurred() ? 1 : 0;

        if (have_error)
            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);

        if (have_error)
            PyErr_Restore(err_type, err_value, err_traceback);

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

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

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

reprfunc tp_repr;
reprfunc tp_str;

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

static PyObject *
newdatatype_repr(newdatatypeobject * obj)
{
    return PyString_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 PyString_FromFormat("Stringified_newdatatype{{size:\%d}}",
                               obj->obj_UnderlyingDatatypePtr->size);
}

Управление атрибутами¶Attribute Management

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

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

getattrfunc  tp_getattr;        /* char * version */
setattrfunc  tp_setattr;
/* ... */
getattrofunc tp_getattro;       /* PyObject * version */
setattrofunc tp_setattro;

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

Общее управление атрибутами¶Generic Attribute Management

Большинство типов расширений используют только простые атрибуты. Что делает атрибуты простыми? Нужно выполнить лишь несколько условий:

Имена атрибутов должны быть известны на момент вызова 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 {
    char        *ml_name;       /* имя метода */
    PyCFunction  ml_meth;       /* функция реализации */
    int          ml_flags;      /* флаги */
    char        *ml_doc;        /* докстринг */
} PyMethodDef;

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

XXX Нужно сослаться на какое-то единое обсуждение полей структуры, общее со следующим разделом.

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

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

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

XXX Нужно перенести часть этого в общий раздел!

Следующие константы флагов определены в structmember.h; их можно комбинировать с помощью побитового ИЛИ.

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

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

Как и в таблице tp_methods, требуется сигнальный элемент со значением name равным NULL.

Управление атрибутами, специфичное для типа¶Type-specific Attribute Management

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

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

Вот пример:

static PyObject *
newdatatype_getattr(newdatatypeobject *obj, char *name)
{
    if (strcmp(name, "data") == 0)
    {
        return PyInt_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)
{
    (void)PyErr_Format(PyExc_RuntimeError, "Read-only attribute: \%s", name);
    return -1;
}

Поддержка абстрактных протоколов¶Abstract Protocol Support

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 long
newdatatype_hash(newdatatypeobject *obj)
{
    long result;
    result = obj->obj_UnderlyingDatatypePtr->size;
    result = result * 3;
    return result;
}

ternaryfunc tp_call;

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

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

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

Вот бессистемный пример реализации функции call.

/* Реализовать функцию вызова.
 *    obj1 – экземпляр, принимающий вызов.
 *    obj2 – кортеж, содержащий аргументы вызова, в данном
 *         случае 3 строки.
 */
static PyObject *
newdatatype_call(newdatatypeobject *obj, PyObject *args, PyObject *other)
{
    PyObject *result;
    char *arg1;
    char *arg2;
    char *arg3;

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

XXX некоторые поля нужно добавить сюда...

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

Эти функции обеспечивают поддержку протокола итератора. Любой объект, который должен поддерживать итерацию по своему содержимому (которое может генерироваться во время итерации), должен реализовать обработчик tp_iter. Объекты, возвращаемые обработчиком tp_iter, должны реализовывать оба обработчика: tp_iter и tp_iternext. Оба обработчика принимают ровно один параметр – экземпляр, для которого они вызываются, и возвращают новую ссылку. В случае ошибки они должны установить исключение и вернуть NULL.

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

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

Поддержка слабых ссылок¶Weak Reference Support

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

Чтобы объект можно было использовать в слабых ссылках, расширение должно включить поле PyObject* в структуру экземпляра для использования механизмом слабых ссылок; оно должно быть инициализировано NULL конструктором объекта. Также необходимо установить поле tp_weaklistoffset соответствующего объекта типа в смещение этого поля. Например, тип экземпляра определён следующей структурой:

typedef struct {
    PyObject_HEAD
    PyClassObject *in_class;       /* Объект класса */
    PyObject      *in_dict;        /* Словарь */
    PyObject      *in_weakreflist; /* Список слабых ссылок */
} PyInstanceObject;

Статически объявленный объект типа для экземпляров определяется следующим образом:

PyTypeObject PyInstance_Type = {
    PyObject_HEAD_INIT(&PyType_Type)
    0,
    "module.instance",

    /* Многое опущено для краткости... */

    Py_TPFLAGS_DEFAULT,                         /* tp_flags */
    0,                                          /* tp_doc */
    0,                                          /* tp_traverse */
    0,                                          /* tp_clear */
    0,                                          /* tp_richcompare */
    offsetof(PyInstanceObject, in_weakreflist), /* tp_weaklistoffset */
};

Конструктор типа отвечает за инициализацию списка слабых ссылок значением NULL:

static PyObject *
instance_new() {
    /* Прочие детали инициализации опущены для краткости */

    self->in_weakreflist = NULL;

    return (PyObject *) self;
}

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

static void
instance_dealloc(PyInstanceObject *inst)
{
    /* Выделить временные объекты, если нужно, но не начинать
       уничтожение пока не начинать
     */

    if (inst->in_weakreflist != NULL)
        PyObject_ClearWeakRefs((PyObject *) inst);

    /* Продолжить уничтожение объекта обычным образом. */
}

Дополнительные рекомендации¶More Suggestions

Помните, что большинство этих функций можно опустить; в этом случае нужно указать 0 в качестве значения. Для каждой функции, которую необходимо предоставить, существуют определения типов. Они находятся в object.h в каталоге include Python, который поставляется с дистрибутивом исходного кода Python.

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

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

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

Сноски

[1]	Это верно, когда известно, что объект относится к базовому типу, например, строке или числу с плавающей запятой.

[2]	В этом примере мы полагались на это в обработчике `tp_dealloc`, поскольку наш тип не поддерживает сборку мусора. Даже если тип поддерживает сборку мусора, существуют вызовы, которые позволяют «открепить» объект от сборки мусора, однако эти вызовы являются продвинутыми и не рассматриваются здесь.

[3]

Теперь мы знаем, что первый и последний элементы являются строками, поэтому, возможно, мы могли бы быть менее осторожны с уменьшением их счётчиков ссылок, однако мы принимаем экземпляры подклассов строк. Хотя освобождение обычных строк не будет вызывать обратные вызовы в наши объекты, мы не можем гарантировать, что освобождение экземпляра подкласса строки не вызовет обратные вызовы.

[4]	Даже в третьей версии мы не гарантированы от циклов. Допускаются экземпляры подклассов строк, и подклассы строк могут допускать циклы, даже если обычные строки этого не делают.