newtypes.md
1> **Источник:** https://python-all.ru/3.9/extending/newtypes.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 3. Определение типов расширений: разные темы89Этот раздел представляет краткий обзор различных методов типа, которые можно реализовать, и их назначения.1011Здесь приводится определение [`PyTypeObject`](https://python-all.ru/3.9/c-api/type.html#c.PyTypeObject), некоторые поля, используемые только в отладочных сборках, опущены:1213```c14typedef struct _typeobject {15 PyObject_VAR_HEAD16 const char *tp_name; /* Для вывода в формате "<module>.<name>" */17 Py_ssize_t tp_basicsize, tp_itemsize; /* Для выделения памяти */1819 /* Методы для реализации стандартных операций */2021 destructor tp_dealloc;22 Py_ssize_t tp_vectorcall_offset;23 getattrfunc tp_getattr;24 setattrfunc tp_setattr;25 PyAsyncMethods *tp_as_async; /* ранее известный как tp_compare (Python 2)26 или tp_reserved (Python 3) */27 reprfunc tp_repr;2829 /* Наборы методов для стандартных классов */3031 PyNumberMethods *tp_as_number;32 PySequenceMethods *tp_as_sequence;33 PyMappingMethods *tp_as_mapping;3435 /* Дополнительные стандартные операции (здесь для двоичной совместимости) */3637 hashfunc tp_hash;38 ternaryfunc tp_call;39 reprfunc tp_str;40 getattrofunc tp_getattro;41 setattrofunc tp_setattro;4243 /* Функции для доступа к объекту как к буферу ввода/вывода */44 PyBufferProcs *tp_as_buffer;4546 /* Флаги для определения наличия опциональных/расширенных возможностей */47 unsigned long tp_flags;4849 const char *tp_doc; /* Строка документации */5051 /* вызов функции для всех доступных объектов */52 traverseproc tp_traverse;5354 /* удаление ссылок на содержащиеся объекты */55 inquiry tp_clear;5657 /* расширенные сравнения */58 richcmpfunc tp_richcompare;5960 /* включение слабых ссылок */61 Py_ssize_t tp_weaklistoffset;6263 /* Итераторы */64 getiterfunc tp_iter;65 iternextfunc tp_iternext;6667 /* Дескриптор атрибутов и механизмы подклассов */68 struct PyMethodDef *tp_methods;69 struct PyMemberDef *tp_members;70 struct PyGetSetDef *tp_getset;71 struct _typeobject *tp_base;72 PyObject *tp_dict;73 descrgetfunc tp_descr_get;74 descrsetfunc tp_descr_set;75 Py_ssize_t tp_dictoffset;76 initproc tp_init;77 allocfunc tp_alloc;78 newfunc tp_new;79 freefunc tp_free; /* Низкоуровневая процедура освобождения памяти */80 inquiry tp_is_gc; /* Для PyObject_IS_GC */81 PyObject *tp_bases;82 PyObject *tp_mro; /* порядок разрешения методов */83 PyObject *tp_cache;84 PyObject *tp_subclasses;85 PyObject *tp_weaklist;86 destructor tp_del;8788 /* Метка версии кэша атрибутов типа. Добавлено в версии 2.6. */89 unsigned int tp_version_tag;9091 destructor tp_finalize;9293} PyTypeObject;94```9596Это целое *множество* методов. Но не стоит слишком беспокоиться: если нужно определить тип, скорее всего, потребуется реализовать лишь некоторые из них.9798Как вы, вероятно, уже ожидаете, мы рассмотрим это и предоставим дополнительную информацию о различных обработчиках. Мы не будем следовать порядку их определения в структуре, поскольку на порядок полей сильно повлияло историческое наследие. Чаще всего проще найти пример, содержащий нужные поля, а затем изменить их значения под свой новый тип.99100```c101const char *tp_name; /* Для вывода */102```103104Имя типа – как упоминалось в предыдущей главе, оно будет появляться в разных местах, в основном для диагностики. Постарайтесь выбрать что-то, что будет полезно в такой ситуации!105106```c107Py_ssize_t tp_basicsize, tp_itemsize; /* Для выделения памяти */108```109110Эти поля сообщают среде выполнения, сколько памяти выделять при создании новых объектов этого типа. В Python есть встроенная поддержка структур переменной длины (например, строки, кортежи), для чего и предназначено поле [`tp_itemsize`](https://python-all.ru/3.9/c-api/typeobj.html#c.PyTypeObject.tp_itemsize). Оно будет рассмотрено позже.111112```c113const char *tp_doc;114```115116Здесь можно указать строку (или её адрес), которая будет возвращена, когда скрипт Python обратится к `obj.__doc__` для получения строки документации.117118Теперь перейдём к основным методам типа – тем, которые будут реализованы в большинстве типов-расширений.119120## 3.1. Завершение и освобождение памяти121122```c123destructor tp_dealloc;124```125126Эта функция вызывается, когда счётчик ссылок на экземпляр вашего типа уменьшается до нуля и интерпретатор Python хочет освободить его. Если ваш тип требует освобождения памяти или другой очистки, этот код можно разместить здесь. Сам объект также должен быть освобождён здесь. Вот пример такой функции:127128```c129static void130newdatatype_dealloc(newdatatypeobject *obj)131{132 free(obj->obj_UnderlyingDatatypePtr);133 Py_TYPE(obj)->tp_free((PyObject *)obj);134}135```136137Если ваш тип поддерживает сборку мусора, деструктор должен вызвать [`PyObject_GC_UnTrack()`](https://python-all.ru/3.9/c-api/gcsupport.html#c.PyObject_GC_UnTrack) перед очисткой любых полей-членов:138139```c140static void141newdatatype_dealloc(newdatatypeobject *obj)142{143 PyObject_GC_UnTrack(obj);144 Py_CLEAR(obj->other_obj);145 ...146 Py_TYPE(obj)->tp_free((PyObject *)obj);147}148```149150Важное требование к функции деаллокатора: она не должна вмешиваться в уже установленные исключения. Это важно, поскольку деаллокаторы часто вызываются при раскрутке стека Python; когда стек раскручивается из-за исключения (а не при обычном возврате), ничего не делается для защиты деаллокаторов от того, что исключение уже установлено. Любые действия деаллокатора, которые могут вызвать выполнение дополнительного кода Python, могут обнаружить установленное исключение. Это может привести к вводящим в заблуждение ошибкам интерпретатора. Правильный способ защиты – сохранить текущее исключение перед выполнением небезопасного действия и восстановить его после завершения. Это можно сделать с помощью функций [`PyErr_Fetch()`](https://python-all.ru/3.9/c-api/exceptions.html#c.PyErr_Fetch) и [`PyErr_Restore()`](https://python-all.ru/3.9/c-api/exceptions.html#c.PyErr_Restore):151152```c153static void154my_dealloc(PyObject *obj)155{156 MyObject *self = (MyObject *) obj;157 PyObject *cbresult;158159 if (self->my_callback != NULL) {160 PyObject *err_type, *err_value, *err_traceback;161162 /* Сохраняет текущее состояние исключения */163 PyErr_Fetch(&err_type, &err_value, &err_traceback);164165 cbresult = PyObject_CallNoArgs(self->my_callback);166 if (cbresult == NULL)167 PyErr_WriteUnraisable(self->my_callback);168 else169 Py_DECREF(cbresult);170171 /* Восстанавливает сохранённое состояние исключения */172 PyErr_Restore(err_type, err_value, err_traceback);173174 Py_DECREF(self->my_callback);175 }176 Py_TYPE(obj)->tp_free((PyObject*)self);177}178```179180> **Примечание**181>182> Существуют ограничения на то, что можно безопасно делать в функции деаллокатора. Во-первых, если ваш тип поддерживает сборку мусора (с помощью [`tp_traverse`](https://python-all.ru/3.9/c-api/typeobj.html#c.PyTypeObject.tp_traverse) и/или [`tp_clear`](https://python-all.ru/3.9/c-api/typeobj.html#c.PyTypeObject.tp_clear)), некоторые члены объекта могут быть очищены или финализированы к моменту вызова [`tp_dealloc`](https://python-all.ru/3.9/c-api/typeobj.html#c.PyTypeObject.tp_dealloc). Во-вторых, в [`tp_dealloc`](https://python-all.ru/3.9/c-api/typeobj.html#c.PyTypeObject.tp_dealloc) объект находится в нестабильном состоянии: его счётчик ссылок равен нулю. Любой вызов нетривиального объекта или API (как в примере выше) может снова вызвать [`tp_dealloc`](https://python-all.ru/3.9/c-api/typeobj.html#c.PyTypeObject.tp_dealloc), что приведёт к двойному освобождению и аварийному завершению.183>184> Начиная с Python 3.4, рекомендуется не помещать сложный код финализации в [`tp_dealloc`](https://python-all.ru/3.9/c-api/typeobj.html#c.PyTypeObject.tp_dealloc), а вместо этого использовать новый метод типа [`tp_finalize`](https://python-all.ru/3.9/c-api/typeobj.html#c.PyTypeObject.tp_finalize).185>186> > **См. также**187> >188> > [**PEP 442**](https://python-all.ru/3.9/extending/newtypes.html) описывает новую схему финализации.189190## 3.2. Представление объектов191192В Python есть два способа создать текстовое представление объекта: функция [`repr()`](https://python-all.ru/3.9/library/functions.html#repr) и функция [`str()`](https://python-all.ru/3.9/library/stdtypes.html#str). (Функция [`print()`](https://python-all.ru/3.9/library/functions.html#print) просто вызывает [`str()`](https://python-all.ru/3.9/library/stdtypes.html#str).) Оба этих обработчика необязательны.193194```c195reprfunc tp_repr;196reprfunc tp_str;197```198199Обработчик [`tp_repr`](https://python-all.ru/3.9/c-api/typeobj.html#c.PyTypeObject.tp_repr) должен возвращать строковый объект, содержащий представление экземпляра, для которого он вызван. Вот простой пример:200201```c202static PyObject *203newdatatype_repr(newdatatypeobject * obj)204{205 return PyUnicode_FromFormat("Repr-ified_newdatatype{{size:%d}}",206 obj->obj_UnderlyingDatatypePtr->size);207}208```209210Если обработчик [`tp_repr`](https://python-all.ru/3.9/c-api/typeobj.html#c.PyTypeObject.tp_repr) не задан, интерпретатор предоставит представление, использующее [`tp_name`](https://python-all.ru/3.9/c-api/typeobj.html#c.PyTypeObject.tp_name) типа и уникальный идентификатор объекта.211212Обработчик [`tp_str`](https://python-all.ru/3.9/c-api/typeobj.html#c.PyTypeObject.tp_str) относится к [`str()`](https://python-all.ru/3.9/library/stdtypes.html#str) так же, как описанный выше обработчик [`tp_repr`](https://python-all.ru/3.9/c-api/typeobj.html#c.PyTypeObject.tp_repr) относится к [`repr()`](https://python-all.ru/3.9/library/functions.html#repr): он вызывается, когда код Python вызывает [`str()`](https://python-all.ru/3.9/library/stdtypes.html#str) для экземпляра вашего объекта. Его реализация очень похожа на функцию [`tp_repr`](https://python-all.ru/3.9/c-api/typeobj.html#c.PyTypeObject.tp_repr), но итоговая строка предназначена для чтения человеком. Если [`tp_str`](https://python-all.ru/3.9/c-api/typeobj.html#c.PyTypeObject.tp_str) не указан, используется обработчик [`tp_repr`](https://python-all.ru/3.9/c-api/typeobj.html#c.PyTypeObject.tp_repr).213214Вот простой пример:215216```c217static PyObject *218newdatatype_str(newdatatypeobject * obj)219{220 return PyUnicode_FromFormat("Stringified_newdatatype{{size:%d}}",221 obj->obj_UnderlyingDatatypePtr->size);222}223```224225## 3.3. Управление атрибутами226227Для каждого объекта, который может поддерживать атрибуты, соответствующий тип должен предоставлять функции, управляющие разрешением атрибутов. Нужна функция, которая может получать атрибуты (если они определены), и другая – для установки атрибутов (если установка разрешена). Удаление атрибута – особый случай: новое значение, передаваемое обработчику, равно `NULL`.228229Python поддерживает две пары обработчиков атрибутов; типу, поддерживающему атрибуты, нужно реализовать функции только одной пары. Разница в том, что одна пара принимает имя атрибута как `char*`, а другая – как [`PyObject*`](https://python-all.ru/3.9/c-api/structures.html#c.PyObject). Каждый тип может использовать ту пару, которая удобнее для реализации.230231```c232getattrfunc tp_getattr; /* char * version */233setattrfunc tp_setattr;234/* ... */235getattrofunc tp_getattro; /* PyObject * version */236setattrofunc tp_setattro;237```238239Если доступ к атрибутам объекта всегда является простой операцией (это будет объяснено чуть позже), существуют универсальные реализации, которые можно использовать для предоставления версии [`PyObject*`](https://python-all.ru/3.9/c-api/structures.html#c.PyObject) функций управления атрибутами. Необходимость в специфических для типа обработчиках атрибутов практически полностью исчезла, начиная с Python 2.2, хотя есть много примеров, которые не были обновлены для использования нового универсального механизма.240241### 3.3.1. Общее управление атрибутами242243Большинство типов расширений используют только *простые* атрибуты. Что делает атрибуты простыми? Нужно выполнить лишь несколько условий:2442451. Имена атрибутов должны быть известны на момент вызова [`PyType_Ready()`](https://python-all.ru/3.9/c-api/type.html#c.PyType_Ready).2462. Не требуется специальной обработки для фиксации факта поиска или установки атрибута, и не нужно предпринимать действий в зависимости от значения.247248Обратите внимание, что этот список не накладывает никаких ограничений на значения атрибутов, момент их вычисления или способ хранения соответствующих данных.249250При вызове [`PyType_Ready()`](https://python-all.ru/3.9/c-api/type.html#c.PyType_Ready) используются три таблицы, на которые ссылается объект типа, для создания [дескрипторов](https://python-all.ru/3.9/glossary.html#term-descriptor), помещаемых в словарь объекта типа. Каждый дескриптор управляет доступом к одному атрибуту объекта-экземпляра. Каждая из таблиц необязательна; если все три равны `NULL`, экземпляры типа будут иметь только атрибуты, унаследованные от базового типа, и должны оставить поля [`tp_getattro`](https://python-all.ru/3.9/c-api/typeobj.html#c.PyTypeObject.tp_getattro) и [`tp_setattro`](https://python-all.ru/3.9/c-api/typeobj.html#c.PyTypeObject.tp_setattro) равными `NULL`, позволяя базовому типу обрабатывать атрибуты.251252Таблицы объявлены как три поля объекта типа:253254```c255struct PyMethodDef *tp_methods;256struct PyMemberDef *tp_members;257struct PyGetSetDef *tp_getset;258```259260Если [`tp_methods`](https://python-all.ru/3.9/c-api/typeobj.html#c.PyTypeObject.tp_methods) не равно `NULL`, оно должно указывать на массив структур [`PyMethodDef`](https://python-all.ru/3.9/c-api/structures.html#c.PyMethodDef). Каждая запись в таблице является экземпляром этой структуры:261262```c263typedef struct PyMethodDef {264 const char *ml_name; /* имя метода */265 PyCFunction ml_meth; /* функция реализации */266 int ml_flags; /* флаги */267 const char *ml_doc; /* докстринг */268} PyMethodDef;269```270271Для каждого метода, предоставляемого типом, должна быть определена одна запись; для методов, унаследованных от базового типа, записи не нужны. В конце требуется одна дополнительная запись – сигнальная метка, обозначающая конец массива. Поле `ml_name` сигнальной метки должно быть равно `NULL`.272273Вторая таблица используется для определения атрибутов, которые напрямую отображаются на данные, хранящиеся в экземпляре. Поддерживаются различные примитивные типы C, доступ может быть только для чтения или для чтения и записи. Структуры в таблице определены так:274275```c276typedef struct PyMemberDef {277 const char *name;278 int type;279 int offset;280 int flags;281 const char *doc;282} PyMemberDef;283```284285Для каждой записи в таблице будет создан [дескриптор](https://python-all.ru/3.9/glossary.html#term-descriptor) и добавлен к типу, который сможет извлекать значение из структуры экземпляра. Поле [`type`](https://python-all.ru/3.9/library/functions.html#type) должно содержать один из кодов типов, определённых в заголовке `structmember.h`; значение будет использоваться для определения того, как преобразовывать значения Python в значения C и обратно. Поле `flags` используется для хранения флагов, управляющих доступом к атрибуту.286287Следующие константы флагов определены в `structmember.h`; их можно комбинировать с помощью побитового ИЛИ.288289| Константа | Значение |290| --- | --- |291| `READONLY` | Никогда не доступен для записи. |292| `READ_RESTRICTED` | Не читается в ограниченном режиме. |293| `WRITE_RESTRICTED` | Не записывается в ограниченном режиме. |294| `RESTRICTED` | Не читается и не записывается в ограниченном режиме. |295296Интересное преимущество использования таблицы [`tp_members`](https://python-all.ru/3.9/c-api/typeobj.html#c.PyTypeObject.tp_members) для создания дескрипторов, используемых во время выполнения, заключается в том, что любой атрибут, определённый таким образом, может иметь связанную строку документации – достаточно просто указать текст в таблице. Приложение может использовать API интроспекции для получения дескриптора из объекта класса и получить строку документации через его атрибут `__doc__`.297298Как и в таблице [`tp_methods`](https://python-all.ru/3.9/c-api/typeobj.html#c.PyTypeObject.tp_methods), требуется сигнальная запись со значением `name` равным `NULL`.299300### 3.3.2. Управление атрибутами для конкретного типа301302Для простоты здесь будет продемонстрирована только версия `char*`; тип параметра name – единственное различие между вариантами интерфейса `char*` и [`PyObject*`](https://python-all.ru/3.9/c-api/structures.html#c.PyObject). Этот пример делает то же самое, что и универсальный пример выше, но не использует универсальную поддержку, добавленную в Python 2.2. В нём объясняется, как вызываются функции-обработчики, чтобы, если понадобится расширить их функциональность, было понятно, что нужно сделать.303304Обработчик [`tp_getattr`](https://python-all.ru/3.9/c-api/typeobj.html#c.PyTypeObject.tp_getattr) вызывается, когда объекту требуется поиск атрибута. Он вызывается в тех же ситуациях, что и метод [`__getattr__()`](https://python-all.ru/3.9/reference/datamodel.html#object.__getattr__) класса.305306Вот пример:307308```c309static PyObject *310newdatatype_getattr(newdatatypeobject *obj, char *name)311{312 if (strcmp(name, "data") == 0)313 {314 return PyLong_FromLong(obj->data);315 }316317 PyErr_Format(PyExc_AttributeError,318 "'%.50s' object has no attribute '%.400s'",319 tp->tp_name, name);320 return NULL;321}322```323324Обработчик [`tp_setattr`](https://python-all.ru/3.9/c-api/typeobj.html#c.PyTypeObject.tp_setattr) вызывается, когда вызывается метод [`__setattr__()`](https://python-all.ru/3.9/reference/datamodel.html#object.__setattr__) или [`__delattr__()`](https://python-all.ru/3.9/reference/datamodel.html#object.__delattr__) экземпляра класса. Когда атрибут должен быть удалён, третий параметр будет равен `NULL`. Вот пример, который просто возбуждает исключение; если бы это было всё, что требуется, обработчик [`tp_setattr`](https://python-all.ru/3.9/c-api/typeobj.html#c.PyTypeObject.tp_setattr) следовало бы установить в `NULL`.325326```c327static int328newdatatype_setattr(newdatatypeobject *obj, char *name, PyObject *v)329{330 PyErr_Format(PyExc_RuntimeError, "Read-only attribute: %s", name);331 return -1;332}333```334335## 3.4. Сравнение объектов336337```c338richcmpfunc tp_richcompare;339```340341Обработчик [`tp_richcompare`](https://python-all.ru/3.9/c-api/typeobj.html#c.PyTypeObject.tp_richcompare) вызывается, когда требуется сравнение. Он аналогичен [методам расширенного сравнения](https://python-all.ru/3.9/reference/datamodel.html#richcmpfuncs), таким как [`__lt__()`](https://python-all.ru/3.9/reference/datamodel.html#object.__lt__), а также вызывается [`PyObject_RichCompare()`](https://python-all.ru/3.9/c-api/object.html#c.PyObject_RichCompare) и [`PyObject_RichCompareBool()`](https://python-all.ru/3.9/c-api/object.html#c.PyObject_RichCompareBool).342343Эта функция вызывается с двумя объектами Python и оператором в качестве аргументов; оператором может быть `Py_EQ`, `Py_NE`, `Py_LE`, `Py_GE`, `Py_LT` или `Py_GT`. Она должна сравнить два объекта в соответствии с указанным оператором и вернуть `Py_True` или `Py_False` при успешном сравнении, `Py_NotImplemented` чтобы указать, что сравнение не реализовано и следует попробовать метод сравнения другого объекта, или `NULL`, если было установлено исключение.344345Вот пример реализации для типа данных, который считается равным, если размер внутреннего указателя одинаков:346347```c348static PyObject *349newdatatype_richcmp(PyObject *obj1, PyObject *obj2, int op)350{351 PyObject *result;352 int c, size1, size2;353354 /* код для проверки, что оба аргумента имеют нужный тип355 newdatatype опущен */356357 size1 = obj1->obj_UnderlyingDatatypePtr->size;358 size2 = obj2->obj_UnderlyingDatatypePtr->size;359360 switch (op) {361 case Py_LT: c = size1 < size2; break;362 case Py_LE: c = size1 <= size2; break;363 case Py_EQ: c = size1 == size2; break;364 case Py_NE: c = size1 != size2; break;365 case Py_GT: c = size1 > size2; break;366 case Py_GE: c = size1 >= size2; break;367 }368 result = c ? Py_True : Py_False;369 Py_INCREF(result);370 return result;371 }372```373374## 3.5. Поддержка абстрактных протоколов375376Python поддерживает множество *абстрактных* «протоколов»; конкретные интерфейсы для их использования описаны в разделе [Уровень абстрактных объектов](https://python-all.ru/3.9/c-api/abstract.html#abstract).377378Некоторые из этих абстрактных интерфейсов были определены на ранних этапах разработки реализации Python. В частности, протоколы чисел, отображений и последовательностей были частью Python с самого начала. Со временем были добавлены и другие протоколы. Для протоколов, которые зависят от нескольких процедур-обработчиков из реализации типа, старые протоколы были определены как необязательные блоки обработчиков, на которые ссылается объект типа. Для более новых протоколов в основном объекте типа есть дополнительные слоты, при этом устанавливается бит флага, указывающий на наличие слотов, которые должен проверять интерпретатор. (Бит флага не указывает, что значения слотов не равны `NULL`. Флаг может быть установлен для обозначения наличия слота, но слот может оставаться незаполненным.)379380```c381PyNumberMethods *tp_as_number;382PySequenceMethods *tp_as_sequence;383PyMappingMethods *tp_as_mapping;384```385386Если требуется, чтобы объект мог вести себя как число, последовательность или отображение, нужно поместить адрес структуры, реализующей C-тип [`PyNumberMethods`](https://python-all.ru/3.9/c-api/typeobj.html#c.PyNumberMethods), [`PySequenceMethods`](https://python-all.ru/3.9/c-api/typeobj.html#c.PySequenceMethods) или [`PyMappingMethods`](https://python-all.ru/3.9/c-api/typeobj.html#c.PyMappingMethods) соответственно. Заполнять эту структуру подходящими значениями – ваша задача. Примеры использования каждой из них можно найти в каталоге `Objects` дистрибутива исходного кода Python.387388```c389hashfunc tp_hash;390```391392Эта функция, если вы решите её предоставить, должна возвращать хеш-число для экземпляра вашего типа данных. Вот простой пример:393394```c395static Py_hash_t396newdatatype_hash(newdatatypeobject *obj)397{398 Py_hash_t result;399 result = obj->some_size + 32767 * obj->some_number;400 if (result == -1)401 result = -2;402 return result;403}404```405406`Py_hash_t` – знаковый целочисленный тип с шириной, зависящей от платформы. Возврат `-1` из [`tp_hash`](https://python-all.ru/3.9/c-api/typeobj.html#c.PyTypeObject.tp_hash) указывает на ошибку, поэтому следует избегать его возврата при успешном вычислении хеша, как показано выше.407408```c409ternaryfunc tp_call;410```411412Эта функция вызывается, когда экземпляр вашего типа данных «вызывается», например, если `obj1` является экземпляром вашего типа данных и скрипт Python содержит `obj1('hello')`, то вызывается обработчик [`tp_call`](https://python-all.ru/3.9/c-api/typeobj.html#c.PyTypeObject.tp_call).413414Эта функция принимает три аргумента:4154161. *self* – это экземпляр типа данных, для которого выполняется вызов. Если вызов имеет вид `obj1('hello')`, то *self* равно `obj1`.4172. *args* – кортеж с аргументами вызова. Для извлечения аргументов можно использовать [`PyArg_ParseTuple()`](https://python-all.ru/3.9/c-api/arg.html#c.PyArg_ParseTuple).4183. *kwds* – словарь переданных именованных аргументов. Если он не равен `NULL` и вы поддерживаете именованные аргументы, используйте [`PyArg_ParseTupleAndKeywords()`](https://python-all.ru/3.9/c-api/arg.html#c.PyArg_ParseTupleAndKeywords) для их извлечения. Если вы не хотите поддерживать именованные аргументы и этот словарь не равен `NULL`, возбудите исключение [`TypeError`](https://python-all.ru/3.9/library/exceptions.html#TypeError) с сообщением о том, что именованные аргументы не поддерживаются.419420Вот игрушечная реализация `tp_call`:421422```c423static PyObject *424newdatatype_call(newdatatypeobject *self, PyObject *args, PyObject *kwds)425{426 PyObject *result;427 const char *arg1;428 const char *arg2;429 const char *arg3;430431 if (!PyArg_ParseTuple(args, "sss:call", &arg1, &arg2, &arg3)) {432 return NULL;433 }434 result = PyUnicode_FromFormat(435 "Returning -- value: [%d] arg1: [%s] arg2: [%s] arg3: [%s]\n",436 obj->obj_UnderlyingDatatypePtr->size,437 arg1, arg2, arg3);438 return result;439}440```441442```c443/* Итераторы */444getiterfunc tp_iter;445iternextfunc tp_iternext;446```447448Эти функции обеспечивают поддержку протокола итератора. Оба обработчика принимают ровно один параметр – экземпляр, для которого они вызываются, и возвращают новую ссылку. В случае ошибки они должны установить исключение и вернуть `NULL`. [`tp_iter`](https://python-all.ru/3.9/c-api/typeobj.html#c.PyTypeObject.tp_iter) соответствует методу Python [`__iter__()`](https://python-all.ru/3.9/reference/datamodel.html#object.__iter__), а [`tp_iternext`](https://python-all.ru/3.9/c-api/typeobj.html#c.PyTypeObject.tp_iternext) – методу Python [`__next__()`](https://python-all.ru/3.9/library/stdtypes.html#iterator.__next__).449450Любой [итерируемый](https://python-all.ru/3.9/glossary.html#term-iterable) объект должен реализовывать обработчик [`tp_iter`](https://python-all.ru/3.9/c-api/typeobj.html#c.PyTypeObject.tp_iter), который должен возвращать [итератор](https://python-all.ru/3.9/glossary.html#term-iterator). Здесь действуют те же правила, что и для классов Python:451452- Для коллекций (например, списков и кортежей), которые могут поддерживать несколько независимых итераторов, при каждом вызове [`tp_iter`](https://python-all.ru/3.9/c-api/typeobj.html#c.PyTypeObject.tp_iter) следует создавать и возвращать новый итератор.453- Объекты, которые можно обойти только один раз (обычно из-за побочных эффектов итерации, например файловые объекты), могут реализовать [`tp_iter`](https://python-all.ru/3.9/c-api/typeobj.html#c.PyTypeObject.tp_iter), возвращая новую ссылку на себя – и, следовательно, также должны реализовать обработчик [`tp_iternext`](https://python-all.ru/3.9/c-api/typeobj.html#c.PyTypeObject.tp_iternext).454455Любой объект [итератор](https://python-all.ru/3.9/glossary.html#term-iterator) должен реализовывать как [`tp_iter`](https://python-all.ru/3.9/c-api/typeobj.html#c.PyTypeObject.tp_iter), так и [`tp_iternext`](https://python-all.ru/3.9/c-api/typeobj.html#c.PyTypeObject.tp_iternext). Обработчик [`tp_iter`](https://python-all.ru/3.9/c-api/typeobj.html#c.PyTypeObject.tp_iter) итератора должен возвращать новую ссылку на итератор. Его обработчик [`tp_iternext`](https://python-all.ru/3.9/c-api/typeobj.html#c.PyTypeObject.tp_iternext) должен возвращать новую ссылку на следующий объект в итерации, если таковой имеется. Если итерация завершена, [`tp_iternext`](https://python-all.ru/3.9/c-api/typeobj.html#c.PyTypeObject.tp_iternext) может вернуть `NULL` без установки исключения или установить [`StopIteration`](https://python-all.ru/3.9/library/exceptions.html#StopIteration) *в дополнение* к возврату `NULL`; отказ от исключения может дать немного лучшую производительность. Если произошла настоящая ошибка, [`tp_iternext`](https://python-all.ru/3.9/c-api/typeobj.html#c.PyTypeObject.tp_iternext) всегда должен установить исключение и вернуть `NULL`.456457## 3.6. Поддержка слабых ссылок458459Одна из целей реализации слабых ссылок в Python – позволить любому типу участвовать в механизме слабых ссылок без дополнительных накладных расходов для критичных к производительности объектов (например, чисел).460461> **См. также**462>463> Документация по модулю [`weakref`](https://python-all.ru/3.9/library/weakref.html#module-weakref).464465Чтобы объект мог поддерживать слабые ссылки, тип расширения должен выполнить два условия:4664671. Включите поле [`PyObject*`](https://python-all.ru/3.9/c-api/structures.html#c.PyObject) в структуру объекта C, предназначенное для механизма слабых ссылок. Конструктор объекта должен оставлять его `NULL` (это автоматически происходит при использовании стандартного [`tp_alloc`](https://python-all.ru/3.9/c-api/typeobj.html#c.PyTypeObject.tp_alloc)).4682. Установить член типа [`tp_weaklistoffset`](https://python-all.ru/3.9/c-api/typeobj.html#c.PyTypeObject.tp_weaklistoffset) в смещение упомянутого поля в структуре C-объекта, чтобы интерпретатор знал, как получить доступ к этому полю и изменить его.469470Конкретно, вот как тривиальная структура объекта будет дополнена необходимым полем:471472```c473typedef struct {474 PyObject_HEAD475 PyObject *weakreflist; /* Список слабых ссылок */476} TrivialObject;477```478479И соответствующее поле в статически объявленном объекте типа:480481```c482static PyTypeObject TrivialType = {483 PyVarObject_HEAD_INIT(NULL, 0)484 /* ... остальные поля опущены для краткости ... */485 .tp_weaklistoffset = offsetof(TrivialObject, weakreflist),486};487```488489Единственное дополнительное изменение заключается в том, что `tp_dealloc` должен очистить все слабые ссылки (вызвав `PyObject_ClearWeakRefs()`), если поле не равно `NULL`:490491```c492static void493Trivial_dealloc(TrivialObject *self)494{495 /* Сначала очистить слабые ссылки перед вызовом любых деструкторов */496 if (self->weakreflist != NULL)497 PyObject_ClearWeakRefs((PyObject *) self);498 /* ... остальной код уничтожения опущен для краткости ... */499 Py_TYPE(self)->tp_free((PyObject *) self);500}501```502503## 3.7. Дополнительные рекомендации504505Чтобы научиться реализовывать любой конкретный метод для вашего нового типа данных, возьмите исходный код [CPython](https://python-all.ru/3.9/glossary.html#term-cpython). Перейдите в каталог `Objects`, затем выполните поиск по C-файлам на `tp_` и нужную вам функцию (например, `tp_richcompare`). Вы найдете примеры функции, которую хотите реализовать.506507Когда нужно проверить, что объект является конкретным экземпляром типа, который вы реализуете, используйте функцию [`PyObject_TypeCheck()`](https://python-all.ru/3.9/c-api/object.html#c.PyObject_TypeCheck). Пример её использования может выглядеть так:508509```c510if (!PyObject_TypeCheck(some_object, &MyType)) {511 PyErr_SetString(PyExc_TypeError, "arg #1 not a mything");512 return NULL;513}514```515516> **См. также**517>518> **Скачать исходные дистрибутивы CPython.**519>520> [https://www.python.org/downloads/source/](https://python-all.ru/3.9/extending/newtypes.html)521>522> **Проект CPython на GitHub, где разрабатывается исходный код CPython.**523>524> [https://github.com/python/cpython](https://python-all.ru/3.9/extending/newtypes.html)525