newtypes.md
1> **Источник:** https://python-all.ru/3.8/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.8/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.8/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(obj);134}135```136137Важное требование к функции деаллокатора: она не должна вмешиваться в уже установленные исключения. Это важно, поскольку деаллокаторы часто вызываются при раскрутке стека Python; когда стек раскручивается из-за исключения (а не при обычном возврате), ничего не делается для защиты деаллокаторов от того, что исключение уже установлено. Любые действия деаллокатора, которые могут вызвать выполнение дополнительного кода Python, могут обнаружить установленное исключение. Это может привести к вводящим в заблуждение ошибкам интерпретатора. Правильный способ защиты – сохранить текущее исключение перед выполнением небезопасного действия и восстановить его после завершения. Это можно сделать с помощью функций [`PyErr_Fetch()`](https://python-all.ru/3.8/c-api/exceptions.html#c.PyErr_Fetch) и [`PyErr_Restore()`](https://python-all.ru/3.8/c-api/exceptions.html#c.PyErr_Restore):138139```c140static void141my_dealloc(PyObject *obj)142{143 MyObject *self = (MyObject *) obj;144 PyObject *cbresult;145146 if (self->my_callback != NULL) {147 PyObject *err_type, *err_value, *err_traceback;148149 /* Сохраняет текущее состояние исключения */150 PyErr_Fetch(&err_type, &err_value, &err_traceback);151152 cbresult = PyObject_CallObject(self->my_callback, NULL);153 if (cbresult == NULL)154 PyErr_WriteUnraisable(self->my_callback);155 else156 Py_DECREF(cbresult);157158 /* Восстанавливает сохранённое состояние исключения */159 PyErr_Restore(err_type, err_value, err_traceback);160161 Py_DECREF(self->my_callback);162 }163 Py_TYPE(obj)->tp_free((PyObject*)self);164}165```166167> **Примечание**168>169> Существуют ограничения на то, что можно безопасно делать в функции деаллокатора. Во-первых, если ваш тип поддерживает сборку мусора (с помощью [`tp_traverse`](https://python-all.ru/3.8/c-api/typeobj.html#c.PyTypeObject.tp_traverse) и/или [`tp_clear`](https://python-all.ru/3.8/c-api/typeobj.html#c.PyTypeObject.tp_clear)), некоторые члены объекта могут быть очищены или финализированы к моменту вызова [`tp_dealloc`](https://python-all.ru/3.8/c-api/typeobj.html#c.PyTypeObject.tp_dealloc). Во-вторых, в [`tp_dealloc`](https://python-all.ru/3.8/c-api/typeobj.html#c.PyTypeObject.tp_dealloc) объект находится в нестабильном состоянии: его счётчик ссылок равен нулю. Любой вызов нетривиального объекта или API (как в примере выше) может снова вызвать [`tp_dealloc`](https://python-all.ru/3.8/c-api/typeobj.html#c.PyTypeObject.tp_dealloc), что приведёт к двойному освобождению и аварийному завершению.170>171> Начиная с Python 3.4, рекомендуется не помещать сложный код финализации в [`tp_dealloc`](https://python-all.ru/3.8/c-api/typeobj.html#c.PyTypeObject.tp_dealloc), а вместо этого использовать новый метод типа [`tp_finalize`](https://python-all.ru/3.8/c-api/typeobj.html#c.PyTypeObject.tp_finalize).172>173> > **См. также**174> >175> > [**PEP 442**](https://python-all.ru/3.8/extending/newtypes.html) описывает новую схему финализации.176177## 3.2. Представление объектов178179В Python есть два способа создать текстовое представление объекта: функция [`repr()`](https://python-all.ru/3.8/library/functions.html#repr) и функция [`str()`](https://python-all.ru/3.8/library/stdtypes.html#str). (Функция [`print()`](https://python-all.ru/3.8/library/functions.html#print) просто вызывает [`str()`](https://python-all.ru/3.8/library/stdtypes.html#str).) Оба этих обработчика необязательны.180181```c182reprfunc tp_repr;183reprfunc tp_str;184```185186Обработчик [`tp_repr`](https://python-all.ru/3.8/c-api/typeobj.html#c.PyTypeObject.tp_repr) должен возвращать строковый объект, содержащий представление экземпляра, для которого он вызван. Вот простой пример:187188```c189static PyObject *190newdatatype_repr(newdatatypeobject * obj)191{192 return PyUnicode_FromFormat("Repr-ified_newdatatype{{size:%d}}",193 obj->obj_UnderlyingDatatypePtr->size);194}195```196197Если обработчик [`tp_repr`](https://python-all.ru/3.8/c-api/typeobj.html#c.PyTypeObject.tp_repr) не задан, интерпретатор предоставит представление, использующее [`tp_name`](https://python-all.ru/3.8/c-api/typeobj.html#c.PyTypeObject.tp_name) типа и уникальный идентификатор объекта.198199Обработчик [`tp_str`](https://python-all.ru/3.8/c-api/typeobj.html#c.PyTypeObject.tp_str) относится к [`str()`](https://python-all.ru/3.8/library/stdtypes.html#str) так же, как описанный выше обработчик [`tp_repr`](https://python-all.ru/3.8/c-api/typeobj.html#c.PyTypeObject.tp_repr) относится к [`repr()`](https://python-all.ru/3.8/library/functions.html#repr): он вызывается, когда код Python вызывает [`str()`](https://python-all.ru/3.8/library/stdtypes.html#str) для экземпляра вашего объекта. Его реализация очень похожа на функцию [`tp_repr`](https://python-all.ru/3.8/c-api/typeobj.html#c.PyTypeObject.tp_repr), но итоговая строка предназначена для чтения человеком. Если [`tp_str`](https://python-all.ru/3.8/c-api/typeobj.html#c.PyTypeObject.tp_str) не указан, используется обработчик [`tp_repr`](https://python-all.ru/3.8/c-api/typeobj.html#c.PyTypeObject.tp_repr).200201Вот простой пример:202203```c204static PyObject *205newdatatype_str(newdatatypeobject * obj)206{207 return PyUnicode_FromFormat("Stringified_newdatatype{{size:%d}}",208 obj->obj_UnderlyingDatatypePtr->size);209}210```211212## 3.3. Управление атрибутами213214Для каждого объекта, который может поддерживать атрибуты, соответствующий тип должен предоставлять функции, управляющие разрешением атрибутов. Нужна функция, которая может получать атрибуты (если они определены), и другая – для установки атрибутов (если установка разрешена). Удаление атрибута – особый случай: новое значение, передаваемое обработчику, равно `NULL`.215216Python поддерживает две пары обработчиков атрибутов; типу, поддерживающему атрибуты, нужно реализовать функции только одной пары. Разница в том, что одна пара принимает имя атрибута как `char*`, а другая – как [`PyObject*`](https://python-all.ru/3.8/c-api/structures.html#c.PyObject). Каждый тип может использовать ту пару, которая удобнее для реализации.217218```c219getattrfunc tp_getattr; /* char * version */220setattrfunc tp_setattr;221/* ... */222getattrofunc tp_getattro; /* PyObject * version */223setattrofunc tp_setattro;224```225226Если доступ к атрибутам объекта всегда является простой операцией (это будет объяснено чуть позже), существуют универсальные реализации, которые можно использовать для предоставления версии [`PyObject*`](https://python-all.ru/3.8/c-api/structures.html#c.PyObject) функций управления атрибутами. Необходимость в специфических для типа обработчиках атрибутов практически полностью исчезла, начиная с Python 2.2, хотя есть много примеров, которые не были обновлены для использования нового универсального механизма.227228### 3.3.1. Общее управление атрибутами229230Большинство типов расширений используют только *простые* атрибуты. Что делает атрибуты простыми? Нужно выполнить лишь несколько условий:2312321. Имена атрибутов должны быть известны на момент вызова [`PyType_Ready()`](https://python-all.ru/3.8/c-api/type.html#c.PyType_Ready).2332. Не требуется специальной обработки для фиксации факта поиска или установки атрибута, и не нужно предпринимать действий в зависимости от значения.234235Обратите внимание, что этот список не накладывает никаких ограничений на значения атрибутов, момент их вычисления или способ хранения соответствующих данных.236237При вызове [`PyType_Ready()`](https://python-all.ru/3.8/c-api/type.html#c.PyType_Ready) используются три таблицы, на которые ссылается объект типа, для создания [дескрипторов](https://python-all.ru/3.8/glossary.html#term-descriptor), помещаемых в словарь объекта типа. Каждый дескриптор управляет доступом к одному атрибуту объекта-экземпляра. Каждая из таблиц необязательна; если все три равны `NULL`, экземпляры типа будут иметь только атрибуты, унаследованные от базового типа, и должны оставить поля [`tp_getattro`](https://python-all.ru/3.8/c-api/typeobj.html#c.PyTypeObject.tp_getattro) и [`tp_setattro`](https://python-all.ru/3.8/c-api/typeobj.html#c.PyTypeObject.tp_setattro) равными `NULL`, позволяя базовому типу обрабатывать атрибуты.238239Таблицы объявлены как три поля объекта типа:240241```c242struct PyMethodDef *tp_methods;243struct PyMemberDef *tp_members;244struct PyGetSetDef *tp_getset;245```246247Если [`tp_methods`](https://python-all.ru/3.8/c-api/typeobj.html#c.PyTypeObject.tp_methods) не равно `NULL`, оно должно указывать на массив структур [`PyMethodDef`](https://python-all.ru/3.8/c-api/structures.html#c.PyMethodDef). Каждая запись в таблице является экземпляром этой структуры:248249```c250typedef struct PyMethodDef {251 const char *ml_name; /* имя метода */252 PyCFunction ml_meth; /* функция реализации */253 int ml_flags; /* флаги */254 const char *ml_doc; /* докстринг */255} PyMethodDef;256```257258Для каждого метода, предоставляемого типом, должна быть определена одна запись; для методов, унаследованных от базового типа, записи не нужны. В конце требуется одна дополнительная запись – сигнальная метка, обозначающая конец массива. Поле `ml_name` сигнальной метки должно быть равно `NULL`.259260Вторая таблица используется для определения атрибутов, которые напрямую отображаются на данные, хранящиеся в экземпляре. Поддерживаются различные примитивные типы C, доступ может быть только для чтения или для чтения и записи. Структуры в таблице определены так:261262```c263typedef struct PyMemberDef {264 const char *name;265 int type;266 int offset;267 int flags;268 const char *doc;269} PyMemberDef;270```271272Для каждой записи в таблице будет создан [дескриптор](https://python-all.ru/3.8/glossary.html#term-descriptor) и добавлен к типу, который сможет извлекать значение из структуры экземпляра. Поле [`type`](https://python-all.ru/3.8/library/functions.html#type) должно содержать один из кодов типов, определённых в заголовке `structmember.h`; значение будет использоваться для определения того, как преобразовывать значения Python в значения C и обратно. Поле `flags` используется для хранения флагов, управляющих доступом к атрибуту.273274Следующие константы флагов определены в `structmember.h`; их можно комбинировать с помощью побитового ИЛИ.275276| Константа | Значение |277| --- | --- |278| `READONLY` | Никогда не доступен для записи. |279| `READ_RESTRICTED` | Не читается в ограниченном режиме. |280| `WRITE_RESTRICTED` | Не записывается в ограниченном режиме. |281| `RESTRICTED` | Не читается и не записывается в ограниченном режиме. |282283Интересное преимущество использования таблицы [`tp_members`](https://python-all.ru/3.8/c-api/typeobj.html#c.PyTypeObject.tp_members) для создания дескрипторов, используемых во время выполнения, заключается в том, что любой атрибут, определённый таким образом, может иметь связанную строку документации – достаточно просто указать текст в таблице. Приложение может использовать API интроспекции для получения дескриптора из объекта класса и получить строку документации через его атрибут `__doc__`.284285Как и в таблице [`tp_methods`](https://python-all.ru/3.8/c-api/typeobj.html#c.PyTypeObject.tp_methods), требуется сигнальная запись со значением `name` равным `NULL`.286287### 3.3.2. Управление атрибутами для конкретного типа288289Для простоты здесь будет продемонстрирована только версия `char*`; тип параметра name – единственное различие между вариантами интерфейса `char*` и [`PyObject*`](https://python-all.ru/3.8/c-api/structures.html#c.PyObject). Этот пример делает то же самое, что и универсальный пример выше, но не использует универсальную поддержку, добавленную в Python 2.2. В нём объясняется, как вызываются функции-обработчики, чтобы, если понадобится расширить их функциональность, было понятно, что нужно сделать.290291Обработчик [`tp_getattr`](https://python-all.ru/3.8/c-api/typeobj.html#c.PyTypeObject.tp_getattr) вызывается, когда объекту требуется поиск атрибута. Он вызывается в тех же ситуациях, что и метод [`__getattr__()`](https://python-all.ru/3.8/reference/datamodel.html#object.__getattr__) класса.292293Вот пример:294295```c296static PyObject *297newdatatype_getattr(newdatatypeobject *obj, char *name)298{299 if (strcmp(name, "data") == 0)300 {301 return PyLong_FromLong(obj->data);302 }303304 PyErr_Format(PyExc_AttributeError,305 "'%.50s' object has no attribute '%.400s'",306 tp->tp_name, name);307 return NULL;308}309```310311Обработчик [`tp_setattr`](https://python-all.ru/3.8/c-api/typeobj.html#c.PyTypeObject.tp_setattr) вызывается, когда вызывается метод [`__setattr__()`](https://python-all.ru/3.8/reference/datamodel.html#object.__setattr__) или [`__delattr__()`](https://python-all.ru/3.8/reference/datamodel.html#object.__delattr__) экземпляра класса. Когда атрибут должен быть удалён, третий параметр будет равен `NULL`. Вот пример, который просто возбуждает исключение; если бы это было всё, что требуется, обработчик [`tp_setattr`](https://python-all.ru/3.8/c-api/typeobj.html#c.PyTypeObject.tp_setattr) следовало бы установить в `NULL`.312313```c314static int315newdatatype_setattr(newdatatypeobject *obj, char *name, PyObject *v)316{317 PyErr_Format(PyExc_RuntimeError, "Read-only attribute: %s", name);318 return -1;319}320```321322## 3.4. Сравнение объектов323324```c325richcmpfunc tp_richcompare;326```327328Обработчик [`tp_richcompare`](https://python-all.ru/3.8/c-api/typeobj.html#c.PyTypeObject.tp_richcompare) вызывается, когда требуется сравнение. Он аналогичен [методам расширенного сравнения](https://python-all.ru/3.8/reference/datamodel.html#richcmpfuncs), таким как [`__lt__()`](https://python-all.ru/3.8/reference/datamodel.html#object.__lt__), а также вызывается [`PyObject_RichCompare()`](https://python-all.ru/3.8/c-api/object.html#c.PyObject_RichCompare) и [`PyObject_RichCompareBool()`](https://python-all.ru/3.8/c-api/object.html#c.PyObject_RichCompareBool).329330Эта функция вызывается с двумя объектами Python и оператором в качестве аргументов; оператором может быть `Py_EQ`, `Py_NE`, `Py_LE`, `Py_GT`, `Py_LT` или `Py_GT`. Она должна сравнить два объекта в соответствии с указанным оператором и вернуть `Py_True` или `Py_False` при успешном сравнении, `Py_NotImplemented` чтобы указать, что сравнение не реализовано и следует попробовать метод сравнения другого объекта, или `NULL`, если было установлено исключение.331332Вот пример реализации для типа данных, который считается равным, если размер внутреннего указателя одинаков:333334```c335static PyObject *336newdatatype_richcmp(PyObject *obj1, PyObject *obj2, int op)337{338 PyObject *result;339 int c, size1, size2;340341 /* код для проверки, что оба аргумента имеют нужный тип342 newdatatype опущен */343344 size1 = obj1->obj_UnderlyingDatatypePtr->size;345 size2 = obj2->obj_UnderlyingDatatypePtr->size;346347 switch (op) {348 case Py_LT: c = size1 < size2; break;349 case Py_LE: c = size1 <= size2; break;350 case Py_EQ: c = size1 == size2; break;351 case Py_NE: c = size1 != size2; break;352 case Py_GT: c = size1 > size2; break;353 case Py_GE: c = size1 >= size2; break;354 }355 result = c ? Py_True : Py_False;356 Py_INCREF(result);357 return result;358 }359```360361## 3.5. Поддержка абстрактных протоколов362363Python поддерживает множество *абстрактных* «протоколов»; конкретные интерфейсы для их использования описаны в разделе [Уровень абстрактных объектов](https://python-all.ru/3.8/c-api/abstract.html#abstract).364365Некоторые из этих абстрактных интерфейсов были определены на ранних этапах разработки реализации Python. В частности, протоколы чисел, отображений и последовательностей были частью Python с самого начала. Со временем были добавлены и другие протоколы. Для протоколов, которые зависят от нескольких процедур-обработчиков из реализации типа, старые протоколы были определены как необязательные блоки обработчиков, на которые ссылается объект типа. Для более новых протоколов в основном объекте типа есть дополнительные слоты, при этом устанавливается бит флага, указывающий на наличие слотов, которые должен проверять интерпретатор. (Бит флага не указывает, что значения слотов не равны `NULL`. Флаг может быть установлен для обозначения наличия слота, но слот может оставаться незаполненным.)366367```c368PyNumberMethods *tp_as_number;369PySequenceMethods *tp_as_sequence;370PyMappingMethods *tp_as_mapping;371```372373Если требуется, чтобы объект мог вести себя как число, последовательность или отображение, нужно поместить адрес структуры, реализующей C-тип [`PyNumberMethods`](https://python-all.ru/3.8/c-api/typeobj.html#c.PyNumberMethods), [`PySequenceMethods`](https://python-all.ru/3.8/c-api/typeobj.html#c.PySequenceMethods) или [`PyMappingMethods`](https://python-all.ru/3.8/c-api/typeobj.html#c.PyMappingMethods) соответственно. Заполнять эту структуру подходящими значениями – ваша задача. Примеры использования каждой из них можно найти в каталоге `Objects` дистрибутива исходного кода Python.374375```c376hashfunc tp_hash;377```378379Эта функция, если вы решите её предоставить, должна возвращать хеш-число для экземпляра вашего типа данных. Вот простой пример:380381```c382static Py_hash_t383newdatatype_hash(newdatatypeobject *obj)384{385 Py_hash_t result;386 result = obj->some_size + 32767 * obj->some_number;387 if (result == -1)388 result = -2;389 return result;390}391```392393`Py_hash_t` – знаковый целочисленный тип с шириной, зависящей от платформы. Возврат `-1` из [`tp_hash`](https://python-all.ru/3.8/c-api/typeobj.html#c.PyTypeObject.tp_hash) указывает на ошибку, поэтому следует избегать его возврата при успешном вычислении хеша, как показано выше.394395```c396ternaryfunc tp_call;397```398399Эта функция вызывается, когда экземпляр вашего типа данных «вызывается», например, если `obj1` является экземпляром вашего типа данных и скрипт Python содержит `obj1('hello')`, то вызывается обработчик [`tp_call`](https://python-all.ru/3.8/c-api/typeobj.html#c.PyTypeObject.tp_call).400401Эта функция принимает три аргумента:4024031. *self* – это экземпляр типа данных, для которого выполняется вызов. Если вызов имеет вид `obj1('hello')`, то *self* равно `obj1`.4042. *args* – кортеж с аргументами вызова. Для извлечения аргументов можно использовать [`PyArg_ParseTuple()`](https://python-all.ru/3.8/c-api/arg.html#c.PyArg_ParseTuple).4053. *kwds* – словарь переданных именованных аргументов. Если он не равен `NULL` и вы поддерживаете именованные аргументы, используйте [`PyArg_ParseTupleAndKeywords()`](https://python-all.ru/3.8/c-api/arg.html#c.PyArg_ParseTupleAndKeywords) для их извлечения. Если вы не хотите поддерживать именованные аргументы и этот словарь не равен `NULL`, возбудите исключение [`TypeError`](https://python-all.ru/3.8/library/exceptions.html#TypeError) с сообщением о том, что именованные аргументы не поддерживаются.406407Вот игрушечная реализация `tp_call`:408409```c410static PyObject *411newdatatype_call(newdatatypeobject *self, PyObject *args, PyObject *kwds)412{413 PyObject *result;414 const char *arg1;415 const char *arg2;416 const char *arg3;417418 if (!PyArg_ParseTuple(args, "sss:call", &arg1, &arg2, &arg3)) {419 return NULL;420 }421 result = PyUnicode_FromFormat(422 "Returning -- value: [%d] arg1: [%s] arg2: [%s] arg3: [%s]\n",423 obj->obj_UnderlyingDatatypePtr->size,424 arg1, arg2, arg3);425 return result;426}427```428429```c430/* Итераторы */431getiterfunc tp_iter;432iternextfunc tp_iternext;433```434435Эти функции обеспечивают поддержку протокола итератора. Оба обработчика принимают ровно один параметр – экземпляр, для которого они вызываются, и возвращают новую ссылку. В случае ошибки они должны установить исключение и вернуть `NULL`. [`tp_iter`](https://python-all.ru/3.8/c-api/typeobj.html#c.PyTypeObject.tp_iter) соответствует методу Python [`__iter__()`](https://python-all.ru/3.8/reference/datamodel.html#object.__iter__), а [`tp_iternext`](https://python-all.ru/3.8/c-api/typeobj.html#c.PyTypeObject.tp_iternext) – методу Python [`__next__()`](https://python-all.ru/3.8/library/stdtypes.html#iterator.__next__).436437Любой [итерируемый](https://python-all.ru/3.8/glossary.html#term-iterable) объект должен реализовывать обработчик [`tp_iter`](https://python-all.ru/3.8/c-api/typeobj.html#c.PyTypeObject.tp_iter), который должен возвращать [итератор](https://python-all.ru/3.8/glossary.html#term-iterator). Здесь действуют те же правила, что и для классов Python:438439- Для коллекций (например, списков и кортежей), которые могут поддерживать несколько независимых итераторов, при каждом вызове [`tp_iter`](https://python-all.ru/3.8/c-api/typeobj.html#c.PyTypeObject.tp_iter) следует создавать и возвращать новый итератор.440- Объекты, которые можно обойти только один раз (обычно из-за побочных эффектов итерации, например файловые объекты), могут реализовать [`tp_iter`](https://python-all.ru/3.8/c-api/typeobj.html#c.PyTypeObject.tp_iter), возвращая новую ссылку на себя – и, следовательно, также должны реализовать обработчик [`tp_iternext`](https://python-all.ru/3.8/c-api/typeobj.html#c.PyTypeObject.tp_iternext).441442Любой объект [итератор](https://python-all.ru/3.8/glossary.html#term-iterator) должен реализовывать как [`tp_iter`](https://python-all.ru/3.8/c-api/typeobj.html#c.PyTypeObject.tp_iter), так и [`tp_iternext`](https://python-all.ru/3.8/c-api/typeobj.html#c.PyTypeObject.tp_iternext). Обработчик [`tp_iter`](https://python-all.ru/3.8/c-api/typeobj.html#c.PyTypeObject.tp_iter) итератора должен возвращать новую ссылку на итератор. Его обработчик [`tp_iternext`](https://python-all.ru/3.8/c-api/typeobj.html#c.PyTypeObject.tp_iternext) должен возвращать новую ссылку на следующий объект в итерации, если таковой имеется. Если итерация завершена, [`tp_iternext`](https://python-all.ru/3.8/c-api/typeobj.html#c.PyTypeObject.tp_iternext) может вернуть `NULL` без установки исключения или установить [`StopIteration`](https://python-all.ru/3.8/library/exceptions.html#StopIteration) *в дополнение* к возврату `NULL`; отказ от исключения может дать немного лучшую производительность. Если произошла настоящая ошибка, [`tp_iternext`](https://python-all.ru/3.8/c-api/typeobj.html#c.PyTypeObject.tp_iternext) всегда должен установить исключение и вернуть `NULL`.443444## 3.6. Поддержка слабых ссылок445446Одна из целей реализации слабых ссылок в Python – позволить любому типу участвовать в механизме слабых ссылок без дополнительных накладных расходов для критичных к производительности объектов (например, чисел).447448> **См. также**449>450> Документация по модулю [`weakref`](https://python-all.ru/3.8/library/weakref.html#module-weakref).451452Чтобы объект мог поддерживать слабые ссылки, тип расширения должен выполнить два условия:4534541. Включите поле [`PyObject*`](https://python-all.ru/3.8/c-api/structures.html#c.PyObject) в структуру объекта C, предназначенное для механизма слабых ссылок. Конструктор объекта должен оставлять его `NULL` (это автоматически происходит при использовании стандартного [`tp_alloc`](https://python-all.ru/3.8/c-api/typeobj.html#c.PyTypeObject.tp_alloc)).4552. Установить член типа [`tp_weaklistoffset`](https://python-all.ru/3.8/c-api/typeobj.html#c.PyTypeObject.tp_weaklistoffset) в смещение упомянутого поля в структуре C-объекта, чтобы интерпретатор знал, как получить доступ к этому полю и изменить его.456457Конкретно, вот как тривиальная структура объекта будет дополнена необходимым полем:458459```c460typedef struct {461 PyObject_HEAD462 PyObject *weakreflist; /* Список слабых ссылок */463} TrivialObject;464```465466И соответствующее поле в статически объявленном объекте типа:467468```c469static PyTypeObject TrivialType = {470 PyVarObject_HEAD_INIT(NULL, 0)471 /* ... остальные поля опущены для краткости ... */472 .tp_weaklistoffset = offsetof(TrivialObject, weakreflist),473};474```475476Единственное дополнительное изменение заключается в том, что `tp_dealloc` должен очистить все слабые ссылки (вызвав `PyObject_ClearWeakRefs()`), если поле не равно `NULL`:477478```c479static void480Trivial_dealloc(TrivialObject *self)481{482 /* Сначала очистить слабые ссылки перед вызовом любых деструкторов */483 if (self->weakreflist != NULL)484 PyObject_ClearWeakRefs((PyObject *) self);485 /* ... остальной код уничтожения опущен для краткости ... */486 Py_TYPE(self)->tp_free((PyObject *) self);487}488```489490## 3.7. Дополнительные рекомендации491492Чтобы научиться реализовывать любой конкретный метод для вашего нового типа данных, возьмите исходный код [CPython](https://python-all.ru/3.8/glossary.html#term-cpython). Перейдите в каталог `Objects`, затем выполните поиск по C-файлам на `tp_` и нужную вам функцию (например, `tp_richcompare`). Вы найдете примеры функции, которую хотите реализовать.493494Когда нужно проверить, что объект является конкретным экземпляром типа, который вы реализуете, используйте функцию [`PyObject_TypeCheck()`](https://python-all.ru/3.8/c-api/object.html#c.PyObject_TypeCheck). Пример её использования может выглядеть так:495496```c497if (!PyObject_TypeCheck(some_object, &MyType)) {498 PyErr_SetString(PyExc_TypeError, "arg #1 not a mything");499 return NULL;500}501```502503> **См. также**504>505> **Скачать исходные дистрибутивы CPython.**506>507> [https://www.python.org/downloads/source/](https://python-all.ru/3.8/extending/newtypes.html)508>509> **Проект CPython на GitHub, где разрабатывается исходный код CPython.**510>511> [https://github.com/python/cpython](https://python-all.ru/3.8/extending/newtypes.html)512