Типовые объекты

type PyTypeObject
Часть Ограниченный API (в виде непрозрачной структуры).

C-структура объектов, используемых для описания встроенных типов.

PyTypeObject PyType_Type
Часть Стабильный ABI.

Это объект типа для объектов типа; это тот же объект, что и type в слое Python.

int PyType_Check(PyObject *o)

Возвращает ненулевое значение, если объект o является объектом типа, включая экземпляры типов, производных от стандартного объекта типа. Во всех остальных случаях возвращается 0. Эта функция всегда успешна.

int PyType_CheckExact(PyObject *o)

Возвращает ненулевое значение, если объект o является объектом типа, но не является подтипом стандартного объекта типа. Во всех остальных случаях возвращается 0. Эта функция всегда успешна.

unsigned int PyType_ClearCache()
Часть Стабильный ABI.

Очистить внутренний кэш поиска. Возвращает текущий тег версии.

unsigned long PyType_GetFlags(PyTypeObject *type)
Часть Стабильный ABI.

Возвращает член tp_flags типа type. Эта функция предназначена в первую очередь для использования с Py_LIMITED_API; отдельные биты флагов гарантированно стабильны во всех выпусках Python, но доступ к самому tp_flags не является частью limited API.

Added in version 3.2.

Изменено в версии 3.4: Тип возврата теперь unsigned long, а не long.

PyObject *PyType_GetDict(PyTypeObject *type)

Возвращает внутреннее пространство имен объекта типа, которое в противном случае доступно только через прокси (cls.__dict__). Это замена прямого доступа к tp_dict. Возвращаемый словарь должен рассматриваться как доступный только для чтения.

Эта функция предназначена для особых случаев встраивания и привязки к языку, когда необходим прямой доступ к dict, а косвенный (например, через прокси или PyObject_GetAttr()) не подходит.

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

Added in version 3.12.

void PyType_Modified(PyTypeObject *type)
Часть Стабильный ABI.

Аннулирует внутренний кэш поиска для типа и всех его подтипов. Эта функция должна вызываться после любого ручного изменения атрибутов или базовых классов типа.

int PyType_AddWatcher(PyType_WatchCallback callback)

Зарегистрируйте callback в качестве наблюдателя типов. Возвращает неотрицательный целочисленный идентификатор, который должен передаваться при последующих вызовах PyType_Watch(). В случае ошибки (например, нет больше доступных идентификаторов наблюдателя) верните -1 и установите исключение.

Added in version 3.12.

int PyType_ClearWatcher(int watcher_id)

Очистить наблюдателя, идентифицированного watcher_id (ранее возвращенного из PyType_AddWatcher()). Возвращает 0 при успехе, -1 при ошибке (например, если watcher_id никогда не был зарегистрирован).

Расширение никогда не должно вызывать PyType_ClearWatcher с watcher_id, который не был возвращен ему предыдущим вызовом PyType_AddWatcher().

Added in version 3.12.

int PyType_Watch(int watcher_id, PyObject *type)

Пометить type как наблюдаемый. Обратный вызов, которому PyType_AddWatcher() присвоил watcher_id, будет вызываться всякий раз, когда PyType_Modified() сообщит об изменении type. (Обратный вызов может быть вызван только один раз для серии последовательных модификаций type, если между модификациями не вызывается _PyType_Lookup() на type; это деталь реализации и может быть изменена).

Расширение никогда не должно вызывать PyType_Watch с watcher_id, который не был возвращен ему предыдущим вызовом PyType_AddWatcher().

Added in version 3.12.

typedef int (*PyType_WatchCallback)(PyObject *type)

Тип функции обратного вызова наблюдателя типов.

Обратный вызов не должен изменять type или вызывать PyType_Modified() для type или любого типа в его MRO; нарушение этого правила может привести к бесконечной рекурсии.

Added in version 3.12.

int PyType_HasFeature(PyTypeObject *o, int feature)

Возвращает ненулевое значение, если объект типа o устанавливает признак feature. Характеристики типа обозначаются однобитовыми флагами.

int PyType_IS_GC(PyTypeObject *o)

Возвращает true, если объект типа включает поддержку детектора цикла; при этом проверяется флаг типа Py_TPFLAGS_HAVE_GC.

int PyType_IsSubtype(PyTypeObject *a, PyTypeObject *b)
Часть Стабильный ABI.

Возвращает true, если a является подтипом b.

Эта функция проверяет только фактические подтипы, что означает, что __subclasscheck__() не вызывается на b. Вызовите PyObject_IsSubclass(), чтобы выполнить ту же проверку, что и issubclass().

PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.

Общий обработчик для слота tp_alloc объекта типа. Используйте стандартный механизм выделения памяти Python для выделения нового экземпляра и инициализации всего его содержимого в NULL.

PyObject *PyType_GenericNew(PyTypeObject *type, PyObject *args, PyObject *kwds)
Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.

Общий обработчик для слота tp_new объекта типа. Создайте новый экземпляр, используя слот tp_alloc типа.

int PyType_Ready(PyTypeObject *type)
Часть Стабильный ABI.

Завершает инициализацию объекта типа. Эта функция должна вызываться для всех объектов типа, чтобы завершить их инициализацию. Эта функция отвечает за добавление унаследованных слотов от базового класса типа. Возвращает 0 при успехе, или возвращает -1 и устанавливает исключение при ошибке.

Примечание

Если какой-то из базовых классов реализует протокол GC, а создаваемый тип не включает Py_TPFLAGS_HAVE_GC в свои флаги, то протокол GC будет автоматически реализован у его родителей. Напротив, если создаваемый тип включает Py_TPFLAGS_HAVE_GC в свои флаги, то он должен сам реализовать протокол GC, по крайней мере, реализовав хэндл tp_traverse.

PyObject *PyType_GetName(PyTypeObject *type)
Возвращаемое значение: Новая ссылка. Часть Стабильный ABI с версии 3.11.

Возвращает имя типа. Эквивалентно получению атрибута __name__ типа.

Added in version 3.11.

PyObject *PyType_GetQualName(PyTypeObject *type)
Возвращаемое значение: Новая ссылка. Часть Стабильный ABI с версии 3.11.

Возвращает квалифицированное имя типа. Эквивалентно получению атрибута __qualname__ типа.

Added in version 3.11.

PyObject *PyType_GetFullyQualifiedName(PyTypeObject *type)
Часть Стабильный ABI с версии 3.13.

Возвращает полное имя типа. Эквивалентно f"{type.__module__}.{type.__qualname__}", или type.__qualname__, если type.__module__ не является строкой или равно "builtins".

Added in version 3.13.

PyObject *PyType_GetModuleName(PyTypeObject *type)
Часть Стабильный ABI с версии 3.13.

Возвращает имя модуля типа. Эквивалентно получению атрибута type.__module__.

Added in version 3.13.

void *PyType_GetSlot(PyTypeObject *type, int slot)
Часть Стабильный ABI с версии 3.4.

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

Возможные значения аргумента slot см. в разделе PyType_Slot.slot.

Added in version 3.4.

Изменено в версии 3.10: PyType_GetSlot() теперь может принимать все типы. Ранее он был ограничен heap types.

PyObject *PyType_GetModule(PyTypeObject *type)
Часть Стабильный ABI с версии 3.10.

Возвращает объект модуля, связанный с данным типом, когда тип был создан с помощью PyType_FromModuleAndSpec().

Если ни один модуль не связан с данным типом, устанавливает TypeError и возвращает NULL.

Эта функция обычно используется для получения модуля, в котором определен метод. Обратите внимание, что в таком методе PyType_GetModule(Py_TYPE(self)) может не вернуть желаемый результат. Py_TYPE(self) может быть подклассом предполагаемого класса, а подклассы не обязательно определены в том же модуле, что и их суперкласс. Смотрите PyCMethod, чтобы узнать класс, определяющий метод. Смотрите PyType_GetModuleByDef() для случаев, когда PyCMethod не может быть использован.

Added in version 3.9.

void *PyType_GetModuleState(PyTypeObject *type)
Часть Стабильный ABI с версии 3.10.

Возвращает состояние объекта модуля, связанного с заданным типом. Это сокращение для вызова PyModule_GetState() по результату PyType_GetModule().

Если ни один модуль не связан с данным типом, устанавливает TypeError и возвращает NULL.

Если тип имеет связанный модуль, но его состояние NULL, возвращает NULL, не устанавливая исключения.

Added in version 3.9.

PyObject *PyType_GetModuleByDef(PyTypeObject *type, struct PyModuleDef *def)
Часть Стабильный ABI с версии 3.13.

Найдите первый суперкласс, модуль которого был создан на основе заданного PyModuleDef def, и вернуть этот модуль.

Если модуль не найден, возникает ошибка TypeError и возвращается NULL.

Эта функция предназначена для использования вместе с PyModule_GetState() для получения состояния модуля из слотовых методов (таких как tp_init или nb_add) и других мест, где определяющий класс метода не может быть передан с использованием соглашения о вызове PyCMethod.

Added in version 3.11.

int PyUnstable_Type_AssignVersionTag(PyTypeObject *type)
Это Нестабильный API. Она может меняться без предупреждения в небольших выпусках.

Попытка присвоить тег версии заданному типу.

Возвращает 1, если у типа уже есть действительный тег версии или был назначен новый, или 0, если новый тег назначить не удалось.

Added in version 3.12.

Создание типов, выделенных из кучи

Для создания heap types используются следующие функции и структуры.

PyObject *PyType_FromMetaclass(PyTypeObject *metaclass, PyObject *module, PyType_Spec *spec, PyObject *bases)
Часть Стабильный ABI с версии 3.12.

Создайте и верните heap type из спецификации (см. Py_TPFLAGS_HEAPTYPE).

Для построения объекта результирующего типа используется метакласс metaclass. Если metaclass имеет значение NULL, то метакласс получается из bases (или слотов Py_tp_base[s], если bases имеет значение NULL, см. ниже).

Метаклассы, переопределяющие tp_new, не поддерживаются, за исключением случаев, когда tp_new является NULL. (Для обратной совместимости другие функции PyType_From* допускают такие метаклассы. Они игнорируют tp_new, что может привести к неполной инициализации. Это устарело, и в Python 3.14+ такие метаклассы поддерживаться не будут).

Аргумент bases может использоваться для указания базовых классов; это может быть либо только один класс, либо кортеж классов. Если bases имеет значение NULL, вместо него используется слот Py_tp_bases. Если оно также равно NULL, вместо него используется слот Py_tp_base. Если это также NULL, то новый тип выводится из object.

Аргумент module может быть использован для записи модуля, в котором определен новый класс. Это должен быть объект модуля или NULL. Если не NULL, то модуль ассоциируется с новым типом и может быть позже получен с помощью PyType_GetModule(). Связанный модуль не наследуется подклассами; он должен быть указан для каждого класса отдельно.

Эта функция вызывает PyType_Ready() на новом типе.

Обратите внимание, что эта функция не полностью соответствует поведению вызова type() или использования оператора class. При использовании пользовательских базовых типов или метаклассов отдавайте предпочтение calling type (или метаклассу), а не функциям PyType_From*. В частности:

  • __new__() не вызывается для нового класса (и он должен быть установлен в type.__new__).

  • __init__() не вызывается для нового класса.

  • __init_subclass__() не вызывается ни на одной базе.

  • __set_name__() не вызывается для новых дескрипторов.

Added in version 3.12.

PyObject *PyType_FromModuleAndSpec(PyObject *module, PyType_Spec *spec, PyObject *bases)
Возвращаемое значение: Новая ссылка. Часть Стабильный ABI с версии 3.10.

Эквивалент PyType_FromMetaclass(NULL, module, spec, bases).

Added in version 3.9.

Изменено в версии 3.10: Теперь функция принимает один класс в качестве аргумента bases и NULL в качестве слота tp_doc.

Изменено в версии 3.12: Теперь функция находит и использует метакласс, соответствующий предоставленным базовым классам. Ранее возвращались только экземпляры type.

Метакласс tp_new игнорируется, что может привести к неполной инициализации. Создание классов, чей метакласс переопределяет tp_new, является устаревшим и в Python 3.14+ больше не будет разрешено.

PyObject *PyType_FromSpecWithBases(PyType_Spec *spec, PyObject *bases)
Возвращаемое значение: Новая ссылка. Часть Стабильный ABI с версии 3.3.

Эквивалент PyType_FromMetaclass(NULL, NULL, spec, bases).

Added in version 3.3.

Изменено в версии 3.12: Теперь функция находит и использует метакласс, соответствующий предоставленным базовым классам. Ранее возвращались только экземпляры type.

Метакласс tp_new игнорируется, что может привести к неполной инициализации. Создание классов, чей метакласс переопределяет tp_new, является устаревшим и в Python 3.14+ больше не будет разрешено.

PyObject *PyType_FromSpec(PyType_Spec *spec)
Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.

Эквивалент PyType_FromMetaclass(NULL, NULL, spec, NULL).

Изменено в версии 3.12: Теперь функция находит и использует метакласс, соответствующий базовым классам, представленным в слотах Py_tp_base[s]. Ранее возвращались только экземпляры type.

Метакласс tp_new игнорируется, что может привести к неполной инициализации. Создание классов, чей метакласс переопределяет tp_new, является устаревшим и в Python 3.14+ больше не будет разрешено.

type PyType_Spec
Часть Стабильный ABI (включая всех членов).

Структура, определяющая поведение типа.

const char *name

Имя типа, используемое для установки PyTypeObject.tp_name.

int basicsize

Если значение положительное, указывает размер экземпляра в байтах. Используется для установки PyTypeObject.tp_basicsize.

Если ноль, указывает, что tp_basicsize должен быть унаследован.

Если значение отрицательное, то абсолютное значение указывает, сколько места требуется экземплярам класса в дополнение к суперклассу. Используйте PyObject_GetTypeData(), чтобы получить указатель на память, зарезервированную таким образом для конкретного подкласса.

Изменено в версии 3.12: Ранее это поле не могло быть отрицательным.

int itemsize

Размер одного элемента типа переменного размера, в байтах. Используется для установки PyTypeObject.tp_itemsize. Оговорки см. в документации к tp_itemsize.

Если ноль, то наследуется tp_itemsize. Расширение классов с произвольным переменным размером опасно, так как некоторые типы используют фиксированное смещение для памяти переменного размера, которое может перекрыть память фиксированного размера, используемую подклассом. Чтобы избежать ошибок, наследование itemsize возможно только в следующих ситуациях:

  • База не имеет переменного размера (ее tp_itemsize).

  • Запрашиваемое значение PyType_Spec.basicsize положительно, что говорит о том, что расположение памяти базового класса известно.

  • Запрашиваемое значение PyType_Spec.basicsize равно нулю, что говорит о том, что подкласс не обращается к памяти экземпляра напрямую.

  • С флагом Py_TPFLAGS_ITEMS_AT_END.

unsigned int flags

Флаги типа, используемые для установки PyTypeObject.tp_flags.

Если флаг Py_TPFLAGS_HEAPTYPE не установлен, PyType_FromSpecWithBases() устанавливает его автоматически.

PyType_Slot *slots

Массив структур PyType_Slot. Заканчивается специальным значением слота {0, NULL}.

Каждый идентификатор слота должен быть указан не более одного раза.

type PyType_Slot
Часть Стабильный ABI (включая всех членов).

Структура, определяющая дополнительную функциональность типа, содержащая идентификатор слота и указатель значения.

int slot

Идентификатор слота.

Идентификаторы слотов называются так же, как имена полей структур PyTypeObject, PyNumberMethods, PySequenceMethods, PyMappingMethods и PyAsyncMethods с добавлением префикса Py_. Например, используйте:

Следующие поля «смещения» не могут быть установлены с помощью PyType_Slot:

Если невозможно перейти на флаг MANAGED (например, для vectorcall или для поддержки Python старше 3.12), укажите смещение в Py_tp_members. Подробности см. в разделе PyMemberDef documentation.

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

Установка Py_tp_bases или Py_tp_base может быть проблематичной на некоторых платформах. Чтобы избежать проблем, используйте вместо этого аргумент bases из PyType_FromSpecWithBases().

Изменено в версии 3.9: Слоты в PyBufferProcs могут быть установлены в неограниченном API.

Изменено в версии 3.11: bf_getbuffer и bf_releasebuffer теперь доступны под limited API.

void *pfunc

Желаемое значение слота. В большинстве случаев это указатель на функцию.

Слоты, отличные от Py_tp_doc, не могут быть NULL.