newtypes.md
1> **Источник:** https://python-all.ru/3.13/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.13/c-api/type.html#c.PyTypeObject), из которого исключены некоторые поля, используемые только в [отладочных сборках](https://python-all.ru/3.13/using/configure.html#debug-build):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 /* Назначенное значение в версии 2.0 */52 /* вызов функции для всех доступных объектов */53 traverseproc tp_traverse;5455 /* удаление ссылок на содержащиеся объекты */56 inquiry tp_clear;5758 /* Назначенное значение в версии 2.1 */59 /* расширенные сравнения */60 richcmpfunc tp_richcompare;6162 /* включение слабых ссылок */63 Py_ssize_t tp_weaklistoffset;6465 /* Итераторы */66 getiterfunc tp_iter;67 iternextfunc tp_iternext;6869 /* Дескриптор атрибутов и механизмы подклассов */70 struct PyMethodDef *tp_methods;71 struct PyMemberDef *tp_members;72 struct PyGetSetDef *tp_getset;73 // Сильная ссылка на тип в куче, заимствованная ссылка на статический тип74 struct _typeobject *tp_base;75 PyObject *tp_dict;76 descrgetfunc tp_descr_get;77 descrsetfunc tp_descr_set;78 Py_ssize_t tp_dictoffset;79 initproc tp_init;80 allocfunc tp_alloc;81 newfunc tp_new;82 freefunc tp_free; /* Низкоуровневая процедура освобождения памяти */83 inquiry tp_is_gc; /* Для PyObject_IS_GC */84 PyObject *tp_bases;85 PyObject *tp_mro; /* порядок разрешения методов */86 PyObject *tp_cache;87 PyObject *tp_subclasses;88 PyObject *tp_weaklist;89 destructor tp_del;9091 /* Метка версии кэша атрибутов типа. Добавлено в версии 2.6. */92 unsigned int tp_version_tag;9394 destructor tp_finalize;95 vectorcallfunc tp_vectorcall;9697 /* битовый набор, указывающий, какие наблюдатели типов следят за этим типом */98 unsigned char tp_watched;99} PyTypeObject;100```101102Это целое *множество* методов. Но не стоит слишком беспокоиться: если нужно определить тип, скорее всего, потребуется реализовать лишь некоторые из них.103104Как вы, вероятно, уже ожидаете, мы рассмотрим это и предоставим дополнительную информацию о различных обработчиках. Мы не будем следовать порядку их определения в структуре, поскольку на порядок полей сильно повлияло историческое наследие. Чаще всего проще найти пример, содержащий нужные поля, а затем изменить их значения под свой новый тип.105106```c107const char *tp_name; /* Для вывода */108```109110Имя типа – как упоминалось в предыдущей главе, оно будет появляться в разных местах, в основном для диагностики. Постарайтесь выбрать что-то, что будет полезно в такой ситуации!111112```c113Py_ssize_t tp_basicsize, tp_itemsize; /* Для выделения памяти */114```115116Эти поля сообщают среде выполнения, сколько памяти выделять при создании новых объектов этого типа. В Python есть встроенная поддержка структур переменной длины (например, строки, кортежи), для чего и предназначено поле [`tp_itemsize`](https://python-all.ru/3.13/c-api/typeobj.html#c.PyTypeObject.tp_itemsize). Оно будет рассмотрено позже.117118```c119const char *tp_doc;120```121122Здесь можно указать строку (или её адрес), которая будет возвращена, когда скрипт Python обратится к `obj.__doc__` для получения строки документации.123124Теперь перейдём к основным методам типа – тем, которые будут реализованы в большинстве типов-расширений.125126## 3.1. Завершение и освобождение памяти127128```c129destructor tp_dealloc;130```131132Эта функция вызывается, когда счётчик ссылок на экземпляр вашего типа уменьшается до нуля и интерпретатор Python хочет освободить его. Если ваш тип требует освобождения памяти или другой очистки, этот код можно разместить здесь. Сам объект также должен быть освобождён здесь. Вот пример такой функции:133134```c135static void136newdatatype_dealloc(newdatatypeobject *obj)137{138 free(obj->obj_UnderlyingDatatypePtr);139 Py_TYPE(obj)->tp_free((PyObject *)obj);140}141```142143Если ваш тип поддерживает сборку мусора, деструктор должен вызвать [`PyObject_GC_UnTrack()`](https://python-all.ru/3.13/c-api/gcsupport.html#c.PyObject_GC_UnTrack) перед очисткой любых полей-членов:144145```c146static void147newdatatype_dealloc(newdatatypeobject *obj)148{149 PyObject_GC_UnTrack(obj);150 Py_CLEAR(obj->other_obj);151 ...152 Py_TYPE(obj)->tp_free((PyObject *)obj);153}154```155156Важное требование к функции деаллокатора: она не должна вмешиваться в уже установленные исключения. Это важно, поскольку деаллокаторы часто вызываются при раскрутке стека Python; когда стек раскручивается из-за исключения (а не при обычном возврате), ничего не делается для защиты деаллокаторов от того, что исключение уже установлено. Любые действия деаллокатора, которые могут вызвать выполнение дополнительного кода Python, могут обнаружить установленное исключение. Это может привести к вводящим в заблуждение ошибкам интерпретатора. Правильный способ защиты – сохранить текущее исключение перед выполнением небезопасного действия и восстановить его после завершения. Это можно сделать с помощью функций [`PyErr_Fetch()`](https://python-all.ru/3.13/c-api/exceptions.html#c.PyErr_Fetch) и [`PyErr_Restore()`](https://python-all.ru/3.13/c-api/exceptions.html#c.PyErr_Restore):157158```c159static void160my_dealloc(PyObject *obj)161{162 MyObject *self = (MyObject *) obj;163 PyObject *cbresult;164165 if (self->my_callback != NULL) {166 PyObject *err_type, *err_value, *err_traceback;167168 /* Сохраняет текущее состояние исключения */169 PyErr_Fetch(&err_type, &err_value, &err_traceback);170171 cbresult = PyObject_CallNoArgs(self->my_callback);172 if (cbresult == NULL)173 PyErr_WriteUnraisable(self->my_callback);174 else175 Py_DECREF(cbresult);176177 /* Восстанавливает сохранённое состояние исключения */178 PyErr_Restore(err_type, err_value, err_traceback);179180 Py_DECREF(self->my_callback);181 }182 Py_TYPE(obj)->tp_free((PyObject*)self);183}184```185186> **Примечание**187>188> Существуют ограничения на то, что можно безопасно делать в функции деаллокатора. Во-первых, если ваш тип поддерживает сборку мусора (с помощью [`tp_traverse`](https://python-all.ru/3.13/c-api/typeobj.html#c.PyTypeObject.tp_traverse) и/или [`tp_clear`](https://python-all.ru/3.13/c-api/typeobj.html#c.PyTypeObject.tp_clear)), некоторые члены объекта могут быть очищены или финализированы к моменту вызова [`tp_dealloc`](https://python-all.ru/3.13/c-api/typeobj.html#c.PyTypeObject.tp_dealloc). Во-вторых, в `tp_dealloc` объект находится в нестабильном состоянии: его счётчик ссылок равен нулю. Любой вызов нетривиального объекта или API (как в примере выше) может снова вызвать `tp_dealloc`, что приведёт к двойному освобождению и аварийному завершению.189>190> Начиная с Python 3.4, рекомендуется не помещать сложный код финализации в [`tp_dealloc`](https://python-all.ru/3.13/c-api/typeobj.html#c.PyTypeObject.tp_dealloc), а вместо этого использовать новый метод типа [`tp_finalize`](https://python-all.ru/3.13/c-api/typeobj.html#c.PyTypeObject.tp_finalize).191>192> > **См. также**193> >194> > [**PEP 442**](https://python-all.ru/3.13/extending/newtypes.html) описывает новую схему финализации.195196## 3.2. Представление объектов197198В Python есть два способа создать текстовое представление объекта: функция [`repr()`](https://python-all.ru/3.13/library/functions.html#repr) и функция [`str()`](https://python-all.ru/3.13/library/stdtypes.html#str). (Функция [`print()`](https://python-all.ru/3.13/library/functions.html#print) просто вызывает `str()`.) Оба этих обработчика необязательны.199200```c201reprfunc tp_repr;202reprfunc tp_str;203```204205Обработчик [`tp_repr`](https://python-all.ru/3.13/c-api/typeobj.html#c.PyTypeObject.tp_repr) должен возвращать строковый объект, содержащий представление экземпляра, для которого он вызван. Вот простой пример:206207```c208static PyObject *209newdatatype_repr(newdatatypeobject *obj)210{211 return PyUnicode_FromFormat("Repr-ified_newdatatype{{size:%d}}",212 obj->obj_UnderlyingDatatypePtr->size);213}214```215216Если обработчик [`tp_repr`](https://python-all.ru/3.13/c-api/typeobj.html#c.PyTypeObject.tp_repr) не указан, интерпретатор предоставит представление, использующее [`tp_name`](https://python-all.ru/3.13/c-api/typeobj.html#c.PyTypeObject.tp_name) типа и уникальное идентифицирующее значение объекта.217218Обработчик [`tp_str`](https://python-all.ru/3.13/c-api/typeobj.html#c.PyTypeObject.tp_str) относится к [`str()`](https://python-all.ru/3.13/library/stdtypes.html#str) так же, как описанный выше обработчик [`tp_repr`](https://python-all.ru/3.13/c-api/typeobj.html#c.PyTypeObject.tp_repr) относится к [`repr()`](https://python-all.ru/3.13/library/functions.html#repr): он вызывается, когда код Python вызывает `str()` для экземпляра вашего объекта. Его реализация очень похожа на функцию `tp_repr`, но итоговая строка предназначена для чтения человеком. Если `tp_str` не указан, используется обработчик `tp_repr`.219220Вот простой пример:221222```c223static PyObject *224newdatatype_str(newdatatypeobject *obj)225{226 return PyUnicode_FromFormat("Stringified_newdatatype{{size:%d}}",227 obj->obj_UnderlyingDatatypePtr->size);228}229```230231## 3.3. Управление атрибутами232233Для каждого объекта, который может поддерживать атрибуты, соответствующий тип должен предоставлять функции, управляющие разрешением атрибутов. Нужна функция, которая может получать атрибуты (если они определены), и другая – для установки атрибутов (если установка разрешена). Удаление атрибута – особый случай: новое значение, передаваемое обработчику, равно `NULL`.234235Python поддерживает две пары обработчиков атрибутов; типу, поддерживающему атрибуты, нужно реализовать функции только для одной пары. Разница в том, что одна пара принимает имя атрибута как char\*, а другая – как [PyObject](https://python-all.ru/3.13/c-api/structures.html#c.PyObject)\*. Каждый тип может использовать ту пару, которая удобнее для реализации.236237```c238getattrfunc tp_getattr; /* char * version */239setattrfunc tp_setattr;240/* ... */241getattrofunc tp_getattro; /* PyObject * version */242setattrofunc tp_setattro;243```244245Если доступ к атрибутам объекта всегда является простой операцией (это будет объяснено далее), существуют общие реализации, которые можно использовать для предоставления версии функций управления атрибутами [PyObject](https://python-all.ru/3.13/c-api/structures.html#c.PyObject)\*. Реальная потребность в типоспецифичных обработчиках атрибутов практически полностью исчезла начиная с Python 2.2, хотя есть много примеров, которые не были обновлены для использования нового общего механизма.246247### 3.3.1. Общее управление атрибутами248249Большинство типов расширений используют только *простые* атрибуты. Что делает атрибуты простыми? Нужно выполнить лишь несколько условий:2502511. Имена атрибутов должны быть известны на момент вызова [`PyType_Ready()`](https://python-all.ru/3.13/c-api/type.html#c.PyType_Ready).2522. Не требуется специальной обработки для фиксации факта поиска или установки атрибута, и не нужно предпринимать действий в зависимости от значения.253254Обратите внимание, что этот список не накладывает никаких ограничений на значения атрибутов, момент их вычисления или способ хранения соответствующих данных.255256При вызове [`PyType_Ready()`](https://python-all.ru/3.13/c-api/type.html#c.PyType_Ready) используются три таблицы, на которые ссылается объект типа, для создания [дескрипторов](https://python-all.ru/3.13/glossary.html#term-descriptor), помещаемых в словарь объекта типа. Каждый дескриптор управляет доступом к одному атрибуту объекта-экземпляра. Каждая из таблиц необязательна; если все три равны `NULL`, экземпляры типа будут иметь только атрибуты, унаследованные от базового типа, и должны оставить поля [`tp_getattro`](https://python-all.ru/3.13/c-api/typeobj.html#c.PyTypeObject.tp_getattro) и [`tp_setattro`](https://python-all.ru/3.13/c-api/typeobj.html#c.PyTypeObject.tp_setattro) равными `NULL`, позволяя базовому типу обрабатывать атрибуты.257258Таблицы объявлены как три поля объекта типа:259260```c261struct PyMethodDef *tp_methods;262struct PyMemberDef *tp_members;263struct PyGetSetDef *tp_getset;264```265266Если [`tp_methods`](https://python-all.ru/3.13/c-api/typeobj.html#c.PyTypeObject.tp_methods) не равно `NULL`, оно должно указывать на массив структур [`PyMethodDef`](https://python-all.ru/3.13/c-api/structures.html#c.PyMethodDef). Каждая запись в таблице является экземпляром этой структуры:267268```c269typedef struct PyMethodDef {270 const char *ml_name; /* имя метода */271 PyCFunction ml_meth; /* функция реализации */272 int ml_flags; /* флаги */273 const char *ml_doc; /* докстринг */274} PyMethodDef;275```276277Для каждого метода, предоставляемого типом, должна быть определена одна запись; для методов, унаследованных от базового типа, записи не нужны. В конце требуется одна дополнительная запись – сигнальная метка, обозначающая конец массива. Поле [`ml_name`](https://python-all.ru/3.13/c-api/structures.html#c.PyMethodDef.ml_name) сигнальной метки должно быть равно `NULL`.278279Вторая таблица используется для определения атрибутов, которые напрямую отображаются на данные, хранящиеся в экземпляре. Поддерживаются различные примитивные типы C, доступ может быть только для чтения или для чтения и записи. Структуры в таблице определены так:280281```c282typedef struct PyMemberDef {283 const char *name;284 int type;285 int offset;286 int flags;287 const char *doc;288} PyMemberDef;289```290291Для каждой записи в таблице будет создан [дескриптор](https://python-all.ru/3.13/glossary.html#term-descriptor) и добавлен к типу; он сможет извлекать значение из структуры экземпляра. Поле [`type`](https://python-all.ru/3.13/c-api/structures.html#c.PyMemberDef.type) должно содержать код типа, например [`Py_T_INT`](https://python-all.ru/3.13/c-api/structures.html#c.Py_T_INT) или [`Py_T_DOUBLE`](https://python-all.ru/3.13/c-api/structures.html#c.Py_T_DOUBLE); это значение будет использоваться для определения того, как преобразовывать значения Python в C и обратно. Поле [`flags`](https://python-all.ru/3.13/c-api/structures.html#c.PyMemberDef.flags) используется для хранения флагов, управляющих доступом к атрибуту: его можно установить в [`Py_READONLY`](https://python-all.ru/3.13/c-api/structures.html#c.Py_READONLY), чтобы запретить установку из кода Python.292293Интересное преимущество использования таблицы [`tp_members`](https://python-all.ru/3.13/c-api/typeobj.html#c.PyTypeObject.tp_members) для создания дескрипторов, используемых во время выполнения, заключается в том, что любой атрибут, определённый таким образом, может иметь связанную строку документации – достаточно просто указать текст в таблице. Приложение может использовать API интроспекции для получения дескриптора из объекта класса и получить строку документации через его атрибут [`__doc__`](https://python-all.ru/3.13/reference/datamodel.html#type.__doc__).294295Как и в таблице [`tp_methods`](https://python-all.ru/3.13/c-api/typeobj.html#c.PyTypeObject.tp_methods), требуется сигнальная запись со значением [`ml_name`](https://python-all.ru/3.13/c-api/structures.html#c.PyMethodDef.ml_name) равным `NULL`.296297### 3.3.2. Управление атрибутами для конкретного типа298299Для простоты здесь будет показана только версия с char\*; единственное различие между вариантами интерфейса char\* и [PyObject](https://python-all.ru/3.13/c-api/structures.html#c.PyObject)\* заключается в типе параметра name. Этот пример делает по сути то же самое, что и общий пример выше, но не использует общую поддержку, добавленную в Python 2.2. В нём объясняется, как вызываются функции-обработчики, чтобы, если понадобится расширить их функциональность, было понятно, что нужно делать.300301Обработчик [`tp_getattr`](https://python-all.ru/3.13/c-api/typeobj.html#c.PyTypeObject.tp_getattr) вызывается, когда объекту требуется поиск атрибута. Он вызывается в тех же ситуациях, что и метод [`__getattr__()`](https://python-all.ru/3.13/reference/datamodel.html#object.__getattr__) класса.302303Вот пример:304305```c306static PyObject *307newdatatype_getattr(newdatatypeobject *obj, char *name)308{309 if (strcmp(name, "data") == 0)310 {311 return PyLong_FromLong(obj->data);312 }313314 PyErr_Format(PyExc_AttributeError,315 "'%.100s' object has no attribute '%.400s'",316 Py_TYPE(obj)->tp_name, name);317 return NULL;318}319```320321Обработчик [`tp_setattr`](https://python-all.ru/3.13/c-api/typeobj.html#c.PyTypeObject.tp_setattr) вызывается, когда вызывается метод [`__setattr__()`](https://python-all.ru/3.13/reference/datamodel.html#object.__setattr__) или [`__delattr__()`](https://python-all.ru/3.13/reference/datamodel.html#object.__delattr__) экземпляра класса. Когда атрибут должен быть удалён, третий параметр будет равен `NULL`. Вот пример, который просто возбуждает исключение; если бы это было всё, что требуется, обработчик `tp_setattr` следовало бы установить в `NULL`.322323```c324static int325newdatatype_setattr(newdatatypeobject *obj, char *name, PyObject *v)326{327 PyErr_Format(PyExc_RuntimeError, "Read-only attribute: %s", name);328 return -1;329}330```331332## 3.4. Сравнение объектов333334```c335richcmpfunc tp_richcompare;336```337338Обработчик [`tp_richcompare`](https://python-all.ru/3.13/c-api/typeobj.html#c.PyTypeObject.tp_richcompare) вызывается, когда требуется сравнение. Он аналогичен [методам расширенного сравнения](https://python-all.ru/3.13/reference/datamodel.html#richcmpfuncs), таким как `__lt__()`, а также вызывается [`PyObject_RichCompare()`](https://python-all.ru/3.13/c-api/object.html#c.PyObject_RichCompare) и [`PyObject_RichCompareBool()`](https://python-all.ru/3.13/c-api/object.html#c.PyObject_RichCompareBool).339340Эта функция вызывается с двумя объектами Python и оператором в качестве аргументов; оператором может быть `Py_EQ`, `Py_NE`, `Py_LE`, `Py_GE`, `Py_LT` или `Py_GT`. Она должна сравнить два объекта в соответствии с указанным оператором и вернуть `Py_True` или `Py_False` при успешном сравнении, `Py_NotImplemented` чтобы указать, что сравнение не реализовано и следует попробовать метод сравнения другого объекта, или `NULL`, если было установлено исключение.341342Вот пример реализации для типа данных, который считается равным, если размер внутреннего указателя одинаков:343344```c345static PyObject *346newdatatype_richcmp(newdatatypeobject *obj1, newdatatypeobject *obj2, int op)347{348 PyObject *result;349 int c, size1, size2;350351 /* код для проверки, что оба аргумента имеют нужный тип352 newdatatype опущен */353354 size1 = obj1->obj_UnderlyingDatatypePtr->size;355 size2 = obj2->obj_UnderlyingDatatypePtr->size;356357 switch (op) {358 case Py_LT: c = size1 < size2; break;359 case Py_LE: c = size1 <= size2; break;360 case Py_EQ: c = size1 == size2; break;361 case Py_NE: c = size1 != size2; break;362 case Py_GT: c = size1 > size2; break;363 case Py_GE: c = size1 >= size2; break;364 }365 result = c ? Py_True : Py_False;366 Py_INCREF(result);367 return result;368 }369```370371## 3.5. Поддержка абстрактных протоколов372373Python поддерживает множество *абстрактных* «протоколов»; конкретные интерфейсы для их использования описаны в разделе [Уровень абстрактных объектов](https://python-all.ru/3.13/c-api/abstract.html#abstract).374375Некоторые из этих абстрактных интерфейсов были определены на ранних этапах разработки реализации Python. В частности, протоколы чисел, отображений и последовательностей были частью Python с самого начала. Со временем были добавлены и другие протоколы. Для протоколов, которые зависят от нескольких процедур-обработчиков из реализации типа, старые протоколы были определены как необязательные блоки обработчиков, на которые ссылается объект типа. Для более новых протоколов в основном объекте типа есть дополнительные слоты, при этом устанавливается бит флага, указывающий на наличие слотов, которые должен проверять интерпретатор. (Бит флага не указывает, что значения слотов не равны `NULL`. Флаг может быть установлен для обозначения наличия слота, но слот может оставаться незаполненным.)376377```c378PyNumberMethods *tp_as_number;379PySequenceMethods *tp_as_sequence;380PyMappingMethods *tp_as_mapping;381```382383Если требуется, чтобы объект мог вести себя как число, последовательность или отображение, нужно поместить адрес структуры, реализующей C-тип [`PyNumberMethods`](https://python-all.ru/3.13/c-api/typeobj.html#c.PyNumberMethods), [`PySequenceMethods`](https://python-all.ru/3.13/c-api/typeobj.html#c.PySequenceMethods) или [`PyMappingMethods`](https://python-all.ru/3.13/c-api/typeobj.html#c.PyMappingMethods) соответственно. Заполнять эту структуру подходящими значениями – ваша задача. Примеры использования каждой из них можно найти в каталоге `Objects` дистрибутива исходного кода Python.384385```c386hashfunc tp_hash;387```388389Эта функция, если вы решите её предоставить, должна возвращать хеш-число для экземпляра вашего типа данных. Вот простой пример:390391```c392static Py_hash_t393newdatatype_hash(newdatatypeobject *obj)394{395 Py_hash_t result;396 result = obj->some_size + 32767 * obj->some_number;397 if (result == -1)398 result = -2;399 return result;400}401```402403[`Py_hash_t`](https://python-all.ru/3.13/c-api/hash.html#c.Py_hash_t) – знаковый целочисленный тип с шириной, зависящей от платформы. Возврат `-1` из [`tp_hash`](https://python-all.ru/3.13/c-api/typeobj.html#c.PyTypeObject.tp_hash) указывает на ошибку, поэтому следует избегать его возврата при успешном вычислении хеша, как показано выше.404405```c406ternaryfunc tp_call;407```408409Эта функция вызывается, когда экземпляр вашего типа данных «вызывается», например, если `obj1` является экземпляром вашего типа данных и скрипт Python содержит `obj1('hello')`, то вызывается обработчик [`tp_call`](https://python-all.ru/3.13/c-api/typeobj.html#c.PyTypeObject.tp_call).410411Эта функция принимает три аргумента:4124131. *self* – это экземпляр типа данных, для которого выполняется вызов. Если вызов имеет вид `obj1('hello')`, то *self* равно `obj1`.4142. *args* – кортеж с аргументами вызова. Для извлечения аргументов можно использовать [`PyArg_ParseTuple()`](https://python-all.ru/3.13/c-api/arg.html#c.PyArg_ParseTuple).4153. *kwds* – словарь переданных именованных аргументов. Если он не равен `NULL` и вы поддерживаете именованные аргументы, используйте [`PyArg_ParseTupleAndKeywords()`](https://python-all.ru/3.13/c-api/arg.html#c.PyArg_ParseTupleAndKeywords) для их извлечения. Если вы не хотите поддерживать именованные аргументы и этот словарь не равен `NULL`, возбудите исключение [`TypeError`](https://python-all.ru/3.13/library/exceptions.html#TypeError) с сообщением о том, что именованные аргументы не поддерживаются.416417Вот игрушечная реализация `tp_call`:418419```c420static PyObject *421newdatatype_call(newdatatypeobject *obj, PyObject *args, PyObject *kwds)422{423 PyObject *result;424 const char *arg1;425 const char *arg2;426 const char *arg3;427428 if (!PyArg_ParseTuple(args, "sss:call", &arg1, &arg2, &arg3)) {429 return NULL;430 }431 result = PyUnicode_FromFormat(432 "Returning -- value: [%d] arg1: [%s] arg2: [%s] arg3: [%s]\n",433 obj->obj_UnderlyingDatatypePtr->size,434 arg1, arg2, arg3);435 return result;436}437```438439```c440/* Итераторы */441getiterfunc tp_iter;442iternextfunc tp_iternext;443```444445Эти функции обеспечивают поддержку протокола итератора. Оба обработчика принимают ровно один параметр – экземпляр, для которого они вызываются, и возвращают новую ссылку. В случае ошибки они должны установить исключение и вернуть `NULL`. [`tp_iter`](https://python-all.ru/3.13/c-api/typeobj.html#c.PyTypeObject.tp_iter) соответствует методу Python [`__iter__()`](https://python-all.ru/3.13/reference/datamodel.html#object.__iter__), а [`tp_iternext`](https://python-all.ru/3.13/c-api/typeobj.html#c.PyTypeObject.tp_iternext) – методу Python [`__next__()`](https://python-all.ru/3.13/library/stdtypes.html#iterator.__next__).446447Любой [итерируемый](https://python-all.ru/3.13/glossary.html#term-iterable) объект должен реализовывать обработчик [`tp_iter`](https://python-all.ru/3.13/c-api/typeobj.html#c.PyTypeObject.tp_iter), который должен возвращать [итератор](https://python-all.ru/3.13/glossary.html#term-iterator). Здесь действуют те же правила, что и для классов Python:448449- Для коллекций (например, списков и кортежей), которые могут поддерживать несколько независимых итераторов, при каждом вызове [`tp_iter`](https://python-all.ru/3.13/c-api/typeobj.html#c.PyTypeObject.tp_iter) следует создавать и возвращать новый итератор.450- Объекты, которые можно обойти только один раз (обычно из-за побочных эффектов итерации, например файловые объекты), могут реализовать [`tp_iter`](https://python-all.ru/3.13/c-api/typeobj.html#c.PyTypeObject.tp_iter), возвращая новую ссылку на себя – и, следовательно, также должны реализовать обработчик [`tp_iternext`](https://python-all.ru/3.13/c-api/typeobj.html#c.PyTypeObject.tp_iternext).451452Любой объект [итератор](https://python-all.ru/3.13/glossary.html#term-iterator) должен реализовывать как [`tp_iter`](https://python-all.ru/3.13/c-api/typeobj.html#c.PyTypeObject.tp_iter), так и [`tp_iternext`](https://python-all.ru/3.13/c-api/typeobj.html#c.PyTypeObject.tp_iternext). Обработчик `tp_iter` итератора должен возвращать новую ссылку на итератор. Его обработчик `tp_iternext` должен возвращать новую ссылку на следующий объект в итерации, если таковой имеется. Если итерация завершена, `tp_iternext` может вернуть `NULL` без установки исключения или установить [`StopIteration`](https://python-all.ru/3.13/library/exceptions.html#StopIteration) *в дополнение* к возврату `NULL`; отказ от исключения может дать немного лучшую производительность. Если произошла настоящая ошибка, `tp_iternext` всегда должен установить исключение и вернуть `NULL`.453454## 3.6. Поддержка слабых ссылок455456Одна из целей реализации слабых ссылок в Python – позволить любому типу участвовать в механизме слабых ссылок без дополнительных накладных расходов для критичных к производительности объектов (например, чисел).457458> **См. также**459>460> Документация по модулю [`weakref`](https://python-all.ru/3.13/library/weakref.html#module-weakref).461462Чтобы объект мог быть слабо ссылаемым, тип расширения должен установить бит `Py_TPFLAGS_MANAGED_WEAKREF` в поле [`tp_flags`](https://python-all.ru/3.13/c-api/typeobj.html#c.PyTypeObject.tp_flags). Поле [`tp_weaklistoffset`](https://python-all.ru/3.13/c-api/typeobj.html#c.PyTypeObject.tp_weaklistoffset) (устаревшее) должно оставаться нулевым.463464Конкретно, вот как будет выглядеть статически объявленный объект типа:465466```c467static PyTypeObject TrivialType = {468 PyVarObject_HEAD_INIT(NULL, 0)469 /* ... остальные поля опущены для краткости ... */470 .tp_flags = Py_TPFLAGS_MANAGED_WEAKREF | ...,471};472```473474Единственное дополнение – `tp_dealloc` должен удалить все слабые ссылки (вызовом [`PyObject_ClearWeakRefs()`](https://python-all.ru/3.13/c-api/weakref.html#c.PyObject_ClearWeakRefs)):475476```c477static void478Trivial_dealloc(TrivialObject *self)479{480 /* Сначала очистить слабые ссылки перед вызовом любых деструкторов */481 PyObject_ClearWeakRefs((PyObject *) self);482 /* ... остальной код уничтожения опущен для краткости ... */483 Py_TYPE(self)->tp_free((PyObject *) self);484}485```486487## 3.7. Дополнительные рекомендации488489Чтобы научиться реализовывать любой конкретный метод для вашего нового типа данных, возьмите исходный код [CPython](https://python-all.ru/3.13/glossary.html#term-CPython). Перейдите в каталог `Objects`, затем выполните поиск по C-файлам на `tp_` и нужную вам функцию (например, `tp_richcompare`). Вы найдете примеры функции, которую хотите реализовать.490491Когда нужно проверить, что объект является конкретным экземпляром типа, который вы реализуете, используйте функцию [`PyObject_TypeCheck()`](https://python-all.ru/3.13/c-api/object.html#c.PyObject_TypeCheck). Пример её использования может выглядеть так:492493```c494if (!PyObject_TypeCheck(some_object, &MyType)) {495 PyErr_SetString(PyExc_TypeError, "arg #1 not a mything");496 return NULL;497}498```499500> **См. также**501>502> **Скачать исходные дистрибутивы CPython.**503>504> [https://www.python.org/downloads/source/](https://python-all.ru/3.13/extending/newtypes.html)505>506> **Проект CPython на GitHub, где разрабатывается исходный код CPython.**507>508> [https://github.com/python/cpython](https://python-all.ru/3.13/extending/newtypes.html)509