newtypes.md
1> **Источник:** https://python-all.ru/3.16/extending/newtypes.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Определение типов-расширений: разное89Этот раздел представляет краткий обзор различных методов типа, которые можно реализовать, и их назначения.1011Вот определение [`PyTypeObject`](https://python-all.ru/3.16/c-api/type.html#c.PyTypeObject), из которого исключены некоторые поля, используемые только в [отладочных сборках](https://python-all.ru/3.16/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 PyMethodDef *tp_methods;71 PyMemberDef *tp_members;72 PyGetSetDef *tp_getset;73 // Сильная ссылка на тип в куче, заимствованная ссылка на статический тип74 PyTypeObject *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 void *tp_subclasses; /* для статических встроенных типов это индекс */88 PyObject *tp_weaklist; /* не используется для статических встроенных типов */89 destructor tp_del;9091 /* Тег версии кэша атрибутов типа. Добавлено в версии 2.6.92 * Если ноль, кэш недействителен и должен быть инициализирован.93 */94 unsigned int tp_version_tag;9596 destructor tp_finalize;97 vectorcallfunc tp_vectorcall;9899 /* битовый набор, указывающий, какие наблюдатели типов следят за этим типом */100 unsigned char tp_watched;101102 /* Количество используемых значений tp_version_tag.103 * Устанавливается в _Py_ATTR_CACHE_UNUSED, если кэш атрибутов104 * отключен для этого типа (например, из-за пользовательских записей MRO).105 * В противном случае ограничено MAX_VERSIONS_PER_CLASS (определено в другом месте).106 */107 uint16_t tp_versions_used;108} PyTypeObject;109```110111Это целое *множество* методов. Но не стоит слишком беспокоиться: если нужно определить тип, скорее всего, потребуется реализовать лишь некоторые из них.112113Как вы, вероятно, уже ожидаете, мы рассмотрим это и предоставим дополнительную информацию о различных обработчиках. Мы не будем следовать порядку их определения в структуре, поскольку на порядок полей сильно повлияло историческое наследие. Чаще всего проще найти пример, содержащий нужные поля, а затем изменить их значения под свой новый тип.114115```c116const char *tp_name; /* Для вывода */117```118119Имя типа – как упоминалось в предыдущей главе, оно будет появляться в разных местах, в основном для диагностики. Постарайтесь выбрать что-то, что будет полезно в такой ситуации!120121```c122Py_ssize_t tp_basicsize, tp_itemsize; /* Для выделения памяти */123```124125Эти поля сообщают среде выполнения, сколько памяти выделять при создании новых объектов этого типа. В Python есть встроенная поддержка структур переменной длины (например, строки, кортежи), для чего и предназначено поле [`tp_itemsize`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_itemsize). Оно будет рассмотрено позже.126127```c128const char *tp_doc;129```130131Здесь можно указать строку (или её адрес), которая будет возвращена, когда скрипт Python обратится к `obj.__doc__` для получения строки документации.132133Теперь перейдём к основным методам типа – тем, которые будут реализованы в большинстве типов-расширений.134135## Финализация и освобождение памяти136137```c138destructor tp_dealloc;139```140141Эта функция вызывается, когда счётчик ссылок на экземпляр вашего типа уменьшается до нуля и интерпретатор Python хочет освободить его. Если ваш тип требует освобождения памяти или другой очистки, этот код можно разместить здесь. Сам объект также должен быть освобождён здесь. Вот пример такой функции:142143```c144static void145newdatatype_dealloc(PyObject *op)146{147 newdatatypeobject *self = (newdatatypeobject *) op;148 free(self->obj_UnderlyingDatatypePtr);149 Py_TYPE(self)->tp_free(self);150}151```152153Если ваш тип поддерживает сборку мусора, деструктор должен вызвать [`PyObject_GC_UnTrack()`](https://python-all.ru/3.16/c-api/gcsupport.html#c.PyObject_GC_UnTrack) перед очисткой любых полей-членов:154155```c156static void157newdatatype_dealloc(PyObject *op)158{159 newdatatypeobject *self = (newdatatypeobject *) op;160 PyObject_GC_UnTrack(op);161 Py_CLEAR(self->other_obj);162 ...163 Py_TYPE(self)->tp_free(self);164}165```166167Важное требование к функции деаллокатора: она не должна вмешиваться в уже установленные исключения. Это важно, поскольку деаллокаторы часто вызываются при раскрутке стека Python; когда стек раскручивается из-за исключения (а не при обычном возврате), ничего не делается для защиты деаллокаторов от того, что исключение уже установлено. Любые действия деаллокатора, которые могут вызвать выполнение дополнительного кода Python, могут обнаружить установленное исключение. Это может привести к вводящим в заблуждение ошибкам интерпретатора. Правильный способ защиты – сохранить текущее исключение перед выполнением небезопасного действия и восстановить его после завершения. Это можно сделать с помощью функций [`PyErr_Fetch()`](https://python-all.ru/3.16/c-api/exceptions.html#c.PyErr_Fetch) и [`PyErr_Restore()`](https://python-all.ru/3.16/c-api/exceptions.html#c.PyErr_Restore):168169```c170static void171my_dealloc(PyObject *obj)172{173 MyObject *self = (MyObject *) obj;174 PyObject *cbresult;175176 if (self->my_callback != NULL) {177 PyObject *err_type, *err_value, *err_traceback;178179 /* Сохраняет текущее состояние исключения */180 PyErr_Fetch(&err_type, &err_value, &err_traceback);181182 cbresult = PyObject_CallNoArgs(self->my_callback);183 if (cbresult == NULL) {184 PyErr_WriteUnraisable(self->my_callback);185 }186 else {187 Py_DECREF(cbresult);188 }189190 /* Восстанавливает сохранённое состояние исключения */191 PyErr_Restore(err_type, err_value, err_traceback);192193 Py_DECREF(self->my_callback);194 }195 Py_TYPE(self)->tp_free(self);196}197```198199> **Примечание**200>201> Существуют ограничения на то, что можно безопасно делать в функции деаллокатора. Во-первых, если ваш тип поддерживает сборку мусора (с помощью [`tp_traverse`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_traverse) и/или [`tp_clear`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_clear)), некоторые члены объекта могут быть очищены или финализированы к моменту вызова [`tp_dealloc`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_dealloc). Во-вторых, в `tp_dealloc` объект находится в нестабильном состоянии: его счётчик ссылок равен нулю. Любой вызов нетривиального объекта или API (как в примере выше) может снова вызвать `tp_dealloc`, что приведёт к двойному освобождению и аварийному завершению.202>203> Начиная с Python 3.4, рекомендуется не помещать сложный код финализации в [`tp_dealloc`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_dealloc), а вместо этого использовать новый метод типа [`tp_finalize`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_finalize).204>205> > **См. также**206> >207> > [**PEP 442**](https://python-all.ru/3.16/extending/newtypes.html) описывает новую схему финализации.208209## Представление объекта210211В Python есть два способа создать текстовое представление объекта: функция [`repr()`](https://python-all.ru/3.16/library/functions.html#repr) и функция [`str()`](https://python-all.ru/3.16/library/stdtypes.html#str). (Функция [`print()`](https://python-all.ru/3.16/library/functions.html#print) просто вызывает `str()`.) Оба этих обработчика необязательны.212213```c214reprfunc tp_repr;215reprfunc tp_str;216```217218Обработчик [`tp_repr`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_repr) должен возвращать строковый объект, содержащий представление экземпляра, для которого он вызван. Вот простой пример:219220```c221static PyObject *222newdatatype_repr(PyObject *op)223{224 newdatatypeobject *self = (newdatatypeobject *) op;225 return PyUnicode_FromFormat("Repr-ified_newdatatype{{size:%d}}",226 self->obj_UnderlyingDatatypePtr->size);227}228```229230Если обработчик [`tp_repr`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_repr) не указан, интерпретатор предоставит представление, использующее [`tp_name`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_name) типа и уникальное идентифицирующее значение объекта.231232Обработчик [`tp_str`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_str) относится к [`str()`](https://python-all.ru/3.16/library/stdtypes.html#str) так же, как описанный выше обработчик [`tp_repr`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_repr) относится к [`repr()`](https://python-all.ru/3.16/library/functions.html#repr): он вызывается, когда код Python вызывает `str()` для экземпляра вашего объекта. Его реализация очень похожа на функцию `tp_repr`, но итоговая строка предназначена для чтения человеком. Если `tp_str` не указан, используется обработчик `tp_repr`.233234Вот простой пример:235236```c237static PyObject *238newdatatype_str(PyObject *op)239{240 newdatatypeobject *self = (newdatatypeobject *) op;241 return PyUnicode_FromFormat("Stringified_newdatatype{{size:%d}}",242 self->obj_UnderlyingDatatypePtr->size);243}244```245246## Управление атрибутами247248Для каждого объекта, который может поддерживать атрибуты, соответствующий тип должен предоставлять функции, управляющие разрешением атрибутов. Нужна функция, которая может получать атрибуты (если они определены), и другая – для установки атрибутов (если установка разрешена). Удаление атрибута – особый случай: новое значение, передаваемое обработчику, равно `NULL`.249250Python поддерживает две пары обработчиков атрибутов; типу, поддерживающему атрибуты, нужно реализовать функции только для одной пары. Разница в том, что одна пара принимает имя атрибута как char\*, а другая – как [PyObject](https://python-all.ru/3.16/c-api/structures.html#c.PyObject)\*. Каждый тип может использовать ту пару, которая удобнее для реализации.251252```c253getattrfunc tp_getattr; /* char * version */254setattrfunc tp_setattr;255/* ... */256getattrofunc tp_getattro; /* PyObject * version */257setattrofunc tp_setattro;258```259260Если доступ к атрибутам объекта всегда является простой операцией (это будет объяснено далее), существуют общие реализации, которые можно использовать для предоставления версии функций управления атрибутами [PyObject](https://python-all.ru/3.16/c-api/structures.html#c.PyObject)\*. Реальная потребность в типоспецифичных обработчиках атрибутов практически полностью исчезла начиная с Python 2.2, хотя есть много примеров, которые не были обновлены для использования нового общего механизма.261262### Общее управление атрибутами263264Большинство типов расширений используют только *простые* атрибуты. Что делает атрибуты простыми? Нужно выполнить лишь несколько условий:2652661. Имена атрибутов должны быть известны на момент вызова [`PyType_Ready()`](https://python-all.ru/3.16/c-api/type.html#c.PyType_Ready).2672. Не требуется специальной обработки для фиксации факта поиска или установки атрибута, и не нужно предпринимать действий в зависимости от значения.268269Обратите внимание, что этот список не накладывает никаких ограничений на значения атрибутов, момент их вычисления или способ хранения соответствующих данных.270271При вызове [`PyType_Ready()`](https://python-all.ru/3.16/c-api/type.html#c.PyType_Ready) используются три таблицы, на которые ссылается объект типа, для создания [дескрипторов](https://python-all.ru/3.16/glossary.html#term-descriptor), помещаемых в словарь объекта типа. Каждый дескриптор управляет доступом к одному атрибуту объекта-экземпляра. Каждая из таблиц необязательна; если все три равны `NULL`, экземпляры типа будут иметь только атрибуты, унаследованные от базового типа, и должны оставить поля [`tp_getattro`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_getattro) и [`tp_setattro`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_setattro) равными `NULL`, позволяя базовому типу обрабатывать атрибуты.272273Таблицы объявлены как три поля объекта типа:274275```c276struct PyMethodDef *tp_methods;277struct PyMemberDef *tp_members;278struct PyGetSetDef *tp_getset;279```280281Если [`tp_methods`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_methods) не равно `NULL`, оно должно указывать на массив структур [`PyMethodDef`](https://python-all.ru/3.16/c-api/structures.html#c.PyMethodDef). Каждая запись в таблице является экземпляром этой структуры:282283```c284typedef struct PyMethodDef {285 const char *ml_name; /* имя метода */286 PyCFunction ml_meth; /* функция реализации */287 int ml_flags; /* флаги */288 const char *ml_doc; /* докстринг */289} PyMethodDef;290```291292Для каждого метода, предоставляемого типом, должна быть определена одна запись; для методов, унаследованных от базового типа, записи не нужны. В конце требуется одна дополнительная запись – сигнальная метка, обозначающая конец массива. Поле [`ml_name`](https://python-all.ru/3.16/c-api/structures.html#c.PyMethodDef.ml_name) сигнальной метки должно быть равно `NULL`.293294Вторая таблица используется для определения атрибутов, которые напрямую отображаются на данные, хранящиеся в экземпляре. Поддерживаются различные примитивные типы C, доступ может быть только для чтения или для чтения и записи. Структуры в таблице определены так:295296```c297typedef struct PyMemberDef {298 const char *name;299 int type;300 int offset;301 int flags;302 const char *doc;303} PyMemberDef;304```305306Для каждой записи в таблице будет создан [дескриптор](https://python-all.ru/3.16/glossary.html#term-descriptor) и добавлен к типу; он сможет извлекать значение из структуры экземпляра. Поле [`type`](https://python-all.ru/3.16/c-api/structures.html#c.PyMemberDef.type) должно содержать код типа, например [`Py_T_INT`](https://python-all.ru/3.16/c-api/structures.html#c.Py_T_INT) или [`Py_T_DOUBLE`](https://python-all.ru/3.16/c-api/structures.html#c.Py_T_DOUBLE); это значение будет использоваться для определения того, как преобразовывать значения Python в C и обратно. Поле [`flags`](https://python-all.ru/3.16/c-api/structures.html#c.PyMemberDef.flags) используется для хранения флагов, управляющих доступом к атрибуту: его можно установить в [`Py_READONLY`](https://python-all.ru/3.16/c-api/structures.html#c.Py_READONLY), чтобы запретить установку из кода Python.307308Интересное преимущество использования таблицы [`tp_members`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_members) для создания дескрипторов, используемых во время выполнения, заключается в том, что любой атрибут, определённый таким образом, может иметь связанную строку документации – достаточно просто указать текст в таблице. Приложение может использовать API интроспекции для получения дескриптора из объекта класса и получить строку документации через его атрибут [`__doc__`](https://python-all.ru/3.16/reference/datamodel.html#type.__doc__).309310Как и в таблице [`tp_methods`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_methods), требуется сигнальная запись со значением [`ml_name`](https://python-all.ru/3.16/c-api/structures.html#c.PyMethodDef.ml_name) равным `NULL`.311312### Управление атрибутами, специфичное для типа313314Для простоты здесь будет показана только версия с char\*; единственное различие между вариантами интерфейса char\* и [PyObject](https://python-all.ru/3.16/c-api/structures.html#c.PyObject)\* заключается в типе параметра name. Этот пример делает по сути то же самое, что и общий пример выше, но не использует общую поддержку, добавленную в Python 2.2. В нём объясняется, как вызываются функции-обработчики, чтобы, если понадобится расширить их функциональность, было понятно, что нужно делать.315316Обработчик [`tp_getattr`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_getattr) вызывается, когда объекту требуется поиск атрибута. Он вызывается в тех же ситуациях, что и метод [`__getattr__()`](https://python-all.ru/3.16/reference/datamodel.html#object.__getattr__) класса.317318Вот пример:319320```c321static PyObject *322newdatatype_getattr(PyObject *op, char *name)323{324 newdatatypeobject *self = (newdatatypeobject *) op;325 if (strcmp(name, "data") == 0) {326 return PyLong_FromLong(self->data);327 }328329 PyErr_Format(PyExc_AttributeError,330 "'%.100s' object has no attribute '%.400s'",331 Py_TYPE(self)->tp_name, name);332 return NULL;333}334```335336Обработчик [`tp_setattr`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_setattr) вызывается, когда вызывается метод [`__setattr__()`](https://python-all.ru/3.16/reference/datamodel.html#object.__setattr__) или [`__delattr__()`](https://python-all.ru/3.16/reference/datamodel.html#object.__delattr__) экземпляра класса. Когда атрибут должен быть удалён, третий параметр будет равен `NULL`. Вот пример, который просто возбуждает исключение; если бы это было всё, что требуется, обработчик `tp_setattr` следовало бы установить в `NULL`.337338```c339static int340newdatatype_setattr(PyObject *op, char *name, PyObject *v)341{342 PyErr_Format(PyExc_RuntimeError, "Read-only attribute: %s", name);343 return -1;344}345```346347## Сравнение объектов348349```c350richcmpfunc tp_richcompare;351```352353Обработчик [`tp_richcompare`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_richcompare) вызывается, когда требуется сравнение. Он аналогичен [методам расширенного сравнения](https://python-all.ru/3.16/reference/datamodel.html#richcmpfuncs), таким как `__lt__()`, а также вызывается [`PyObject_RichCompare()`](https://python-all.ru/3.16/c-api/object.html#c.PyObject_RichCompare) и [`PyObject_RichCompareBool()`](https://python-all.ru/3.16/c-api/object.html#c.PyObject_RichCompareBool).354355Эта функция вызывается с двумя объектами Python и оператором в качестве аргументов; оператором может быть `Py_EQ`, `Py_NE`, `Py_LE`, `Py_GE`, `Py_LT` или `Py_GT`. Она должна сравнить два объекта в соответствии с указанным оператором и вернуть `Py_True` или `Py_False` при успешном сравнении, `Py_NotImplemented` чтобы указать, что сравнение не реализовано и следует попробовать метод сравнения другого объекта, или `NULL`, если было установлено исключение.356357Вот пример реализации для типа данных, который считается равным, если размер внутреннего указателя одинаков:358359```c360static PyObject *361newdatatype_richcmp(PyObject *lhs, PyObject *rhs, int op)362{363 newdatatypeobject *obj1 = (newdatatypeobject *) lhs;364 newdatatypeobject *obj2 = (newdatatypeobject *) rhs;365 PyObject *result;366 int c, size1, size2;367368 /* код для проверки, что оба аргумента имеют нужный тип369 newdatatype опущен */370371 size1 = obj1->obj_UnderlyingDatatypePtr->size;372 size2 = obj2->obj_UnderlyingDatatypePtr->size;373374 switch (op) {375 case Py_LT: c = size1 < size2; break;376 case Py_LE: c = size1 <= size2; break;377 case Py_EQ: c = size1 == size2; break;378 case Py_NE: c = size1 != size2; break;379 case Py_GT: c = size1 > size2; break;380 case Py_GE: c = size1 >= size2; break;381 }382 result = c ? Py_True : Py_False;383 return Py_NewRef(result);384 }385```386387## Поддержка абстрактных протоколов388389Python поддерживает множество *абстрактных* «протоколов»; конкретные интерфейсы для их использования описаны в разделе [Уровень абстрактных объектов](https://python-all.ru/3.16/c-api/abstract.html#abstract).390391Некоторые из этих абстрактных интерфейсов были определены на ранних этапах разработки реализации Python. В частности, протоколы чисел, отображений и последовательностей были частью Python с самого начала. Со временем были добавлены и другие протоколы. Для протоколов, которые зависят от нескольких процедур-обработчиков из реализации типа, старые протоколы были определены как необязательные блоки обработчиков, на которые ссылается объект типа. Для более новых протоколов в основном объекте типа есть дополнительные слоты, при этом устанавливается бит флага, указывающий на наличие слотов, которые должен проверять интерпретатор. (Бит флага не указывает, что значения слотов не равны `NULL`. Флаг может быть установлен для обозначения наличия слота, но слот может оставаться незаполненным.)392393```c394PyNumberMethods *tp_as_number;395PySequenceMethods *tp_as_sequence;396PyMappingMethods *tp_as_mapping;397```398399Если требуется, чтобы объект мог вести себя как число, последовательность или отображение, нужно поместить адрес структуры, реализующей C-тип [`PyNumberMethods`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyNumberMethods), [`PySequenceMethods`](https://python-all.ru/3.16/c-api/typeobj.html#c.PySequenceMethods) или [`PyMappingMethods`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyMappingMethods) соответственно. Заполнять эту структуру подходящими значениями – ваша задача. Примеры использования каждой из них можно найти в каталоге `Objects` дистрибутива исходного кода Python.400401```c402hashfunc tp_hash;403```404405Эта функция, если вы решите её предоставить, должна возвращать хеш-число для экземпляра вашего типа данных. Вот простой пример:406407```c408static Py_hash_t409newdatatype_hash(PyObject *op)410{411 newdatatypeobject *self = (newdatatypeobject *) op;412 Py_hash_t result;413 result = self->some_size + 32767 * self->some_number;414 if (result == -1) {415 result = -2;416 }417 return result;418}419```420421[`Py_hash_t`](https://python-all.ru/3.16/c-api/hash.html#c.Py_hash_t) – знаковый целочисленный тип с шириной, зависящей от платформы. Возврат `-1` из [`tp_hash`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_hash) указывает на ошибку, поэтому следует избегать его возврата при успешном вычислении хеша, как показано выше.422423```c424ternaryfunc tp_call;425```426427Эта функция вызывается, когда экземпляр вашего типа данных «вызывается», например, если `obj1` является экземпляром вашего типа данных и скрипт Python содержит `obj1('hello')`, то вызывается обработчик [`tp_call`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_call).428429Эта функция принимает три аргумента:4304311. *self* – это экземпляр типа данных, для которого выполняется вызов. Если вызов имеет вид `obj1('hello')`, то *self* равно `obj1`.4322. *args* – кортеж с аргументами вызова. Для извлечения аргументов можно использовать [`PyArg_ParseTuple()`](https://python-all.ru/3.16/c-api/arg.html#c.PyArg_ParseTuple).4333. *kwds* – словарь переданных именованных аргументов. Если он не равен `NULL` и вы поддерживаете именованные аргументы, используйте [`PyArg_ParseTupleAndKeywords()`](https://python-all.ru/3.16/c-api/arg.html#c.PyArg_ParseTupleAndKeywords) для их извлечения. Если вы не хотите поддерживать именованные аргументы и этот словарь не равен `NULL`, возбудите исключение [`TypeError`](https://python-all.ru/3.16/library/exceptions.html#TypeError) с сообщением о том, что именованные аргументы не поддерживаются.434435Вот игрушечная реализация `tp_call`:436437```c438static PyObject *439newdatatype_call(PyObject *op, PyObject *args, PyObject *kwds)440{441 newdatatypeobject *self = (newdatatypeobject *) op;442 PyObject *result;443 const char *arg1;444 const char *arg2;445 const char *arg3;446447 if (!PyArg_ParseTuple(args, "sss:call", &arg1, &arg2, &arg3)) {448 return NULL;449 }450 result = PyUnicode_FromFormat(451 "Returning -- value: [%d] arg1: [%s] arg2: [%s] arg3: [%s]\n",452 self->obj_UnderlyingDatatypePtr->size,453 arg1, arg2, arg3);454 return result;455}456```457458```c459/* Итераторы */460getiterfunc tp_iter;461iternextfunc tp_iternext;462```463464Эти функции обеспечивают поддержку протокола итератора. Оба обработчика принимают ровно один параметр – экземпляр, для которого они вызываются, и возвращают новую ссылку. В случае ошибки они должны установить исключение и вернуть `NULL`. [`tp_iter`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_iter) соответствует методу Python [`__iter__()`](https://python-all.ru/3.16/reference/datamodel.html#object.__iter__), а [`tp_iternext`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_iternext) – методу Python [`__next__()`](https://python-all.ru/3.16/library/stdtypes.html#iterator.__next__).465466Любой [итерируемый](https://python-all.ru/3.16/glossary.html#term-iterable) объект должен реализовывать обработчик [`tp_iter`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_iter), который должен возвращать [итератор](https://python-all.ru/3.16/glossary.html#term-iterator). Здесь действуют те же правила, что и для классов Python:467468- Для коллекций (например, списков и кортежей), которые могут поддерживать несколько независимых итераторов, при каждом вызове [`tp_iter`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_iter) следует создавать и возвращать новый итератор.469- Объекты, которые можно обойти только один раз (обычно из-за побочных эффектов итерации, например файловые объекты), могут реализовать [`tp_iter`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_iter), возвращая новую ссылку на себя – и, следовательно, также должны реализовать обработчик [`tp_iternext`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_iternext).470471Любой объект [итератор](https://python-all.ru/3.16/glossary.html#term-iterator) должен реализовывать как [`tp_iter`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_iter), так и [`tp_iternext`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_iternext). Обработчик `tp_iter` итератора должен возвращать новую ссылку на итератор. Его обработчик `tp_iternext` должен возвращать новую ссылку на следующий объект в итерации, если таковой имеется. Если итерация завершена, `tp_iternext` может вернуть `NULL` без установки исключения или установить [`StopIteration`](https://python-all.ru/3.16/library/exceptions.html#StopIteration) *в дополнение* к возврату `NULL`; отказ от исключения может дать немного лучшую производительность. Если произошла настоящая ошибка, `tp_iternext` всегда должен установить исключение и вернуть `NULL`.472473## Поддержка слабых ссылок474475Одна из целей реализации слабых ссылок в Python – позволить любому типу участвовать в механизме слабых ссылок без дополнительных накладных расходов для критичных к производительности объектов (например, чисел).476477> **См. также**478>479> Документация по модулю [`weakref`](https://python-all.ru/3.16/library/weakref.html#module-weakref).480481Чтобы объект мог быть слабо ссылаемым, тип расширения должен установить бит `Py_TPFLAGS_MANAGED_WEAKREF` в поле [`tp_flags`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_flags). Поле [`tp_weaklistoffset`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_weaklistoffset) (устаревшее) должно оставаться нулевым.482483Если этот флаг установлен, [`Py_TPFLAGS_HAVE_GC`](https://python-all.ru/3.16/c-api/typeobj.html#c.Py_TPFLAGS_HAVE_GC) также должен быть установлен.484485Конкретно, вот как будет выглядеть статически объявленный объект типа:486487```c488static PyTypeObject TrivialType = {489 PyVarObject_HEAD_INIT(NULL, 0)490 /* ... остальные поля опущены для краткости ... */491 .tp_flags = Py_TPFLAGS_MANAGED_WEAKREF | ...,492};493```494495Единственное дополнение – `tp_dealloc` должен удалить все слабые ссылки (вызовом [`PyObject_ClearWeakRefs()`](https://python-all.ru/3.16/c-api/weakref.html#c.PyObject_ClearWeakRefs)):496497```c498static void499Trivial_dealloc(PyObject *op)500{501 /* Сначала очистить слабые ссылки перед вызовом любых деструкторов */502 PyObject_ClearWeakRefs(op);503 /* ... остальной код уничтожения опущен для краткости ... */504 Py_TYPE(op)->tp_free(op);505}506```507508## Дополнительные рекомендации509510Чтобы научиться реализовывать любой конкретный метод для вашего нового типа данных, возьмите исходный код [CPython](https://python-all.ru/3.16/glossary.html#term-CPython). Перейдите в каталог `Objects`, затем выполните поиск по C-файлам на `tp_` и нужную вам функцию (например, `tp_richcompare`). Вы найдете примеры функции, которую хотите реализовать.511512Когда нужно проверить, что объект является конкретным экземпляром типа, который вы реализуете, используйте функцию [`PyObject_TypeCheck()`](https://python-all.ru/3.16/c-api/object.html#c.PyObject_TypeCheck). Пример её использования может выглядеть так:513514```c515if (!PyObject_TypeCheck(some_object, &MyType)) {516 PyErr_SetString(PyExc_TypeError, "arg #1 not a mything");517 return NULL;518}519```520521> **См. также**522>523> **Скачать исходные дистрибутивы CPython.**524>525> [https://www.python.org/downloads/source/](https://python-all.ru/3.16/extending/newtypes.html)526>527> **Проект CPython на GitHub, где разрабатывается исходный код CPython.**528>529> [https://github.com/python/cpython](https://python-all.ru/3.16/extending/newtypes.html)530