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

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 не входит в ограниченный API.

Добавлено в версии 3.2.

Изменено в версии 3.4: Теперь тип возвращаемого значения — unsigned long вместо long.

PyObject *PyType_GetDict(PyTypeObject *type)

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

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

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

Добавлено в версии 3.12.

void PyType_Modified(PyTypeObject *type)

Часть стабильного ABI.

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

int PyType_AddWatcher(PyType_WatchCallback callback)

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

В сборках без глобальной блокировки интерпретатора функция PyType_AddWatcher() не является потокобезопасной, поэтому её необходимо вызывать при запуске (до создания первого потока).

Добавлено в версии 3.12.

int PyType_ClearWatcher(int watcher_id)

Удаляет наблюдателя с идентификатором watcher_id (ранее возвращённым функцией PyType_AddWatcher()). При успехе возвращает 0, при ошибке — -1 (например, если watcher_id никогда не регистрировался).

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

Добавлено в версии 3.12.

int PyType_Watch(int watcher_id, PyObject *type)

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

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

Добавлено в версии 3.12.

int PyType_Unwatch(int watcher_id, PyObject *type)

Помечает type как неотслеживаемый. Отменяет предшествующий вызов PyType_Watch(). type не должен быть NULL.

Модуль расширения ни в коем случае не должен вызывать эту функцию с идентификатором watcher_id, который не был возвращён ему предыдущим вызовом PyType_AddWatcher().

При успехе функция возвращает 0. При ошибке функция возвращает -1 и устанавливает исключение.

Добавлено в версии 3.12.

typedef int (*PyType_WatchCallback)(PyObject *type)

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

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

Добавлено в версии 3.12.

int PyType_HasFeature(PyTypeObject *o, int feature)

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

int PyType_FastSubclass(PyTypeObject *type, int flag)

Возвращает ненулевое значение, если объект типа type задаёт флаг подтипа flag. Флаги подтипов обозначаются с помощью Py_TPFLAGS_*_SUBCLASS. Эта функция используется многими функциями _Check для распространённых типов.

См. также

PyObject_TypeCheck(), которая используется как более медленная альтернатива в функциях _Check для типов, не имеющих флагов подтипов.

int PyType_IS_GC(PyTypeObject *o)

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

int PyType_IsSubtype(PyTypeObject *a, PyTypeObject *b)

Часть стабильного ABI.

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

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

PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)

Возвращаемое значение: новая ссылка. Часть стабильного ABI.

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

Не вызывайте эту функцию напрямую для выделения памяти под объект; вместо этого вызовите слот tp_alloc типа.

Для типов, поддерживающих сборку мусора (то есть с установленным флагом Py_TPFLAGS_HAVE_GC), эта функция работает как PyObject_GC_New или PyObject_GC_NewVar (за исключением того, что память гарантированно обнуляется перед инициализацией), и её следует сочетать с PyObject_GC_Del() в tp_free. В противном случае она работает как PyObject_New или PyObject_NewVar (за исключением того, что память гарантированно обнуляется перед инициализацией), и её следует сочетать с PyObject_Free() в tp_free.

PyObject *PyType_GenericNew(PyTypeObject *type, PyObject *args, PyObject *kwds)

Возвращаемое значение: новая ссылка. Часть стабильного ABI.

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

int PyType_Ready(PyTypeObject *type)

Часть стабильного ABI.

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

Примечание

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

PyObject *PyType_GetName(PyTypeObject *type)

Возвращаемое значение: новая ссылка. Часть стабильного ABI начиная с версии 3.11.

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

Добавлено в версии 3.11.

PyObject *PyType_GetQualName(PyTypeObject *type)

Возвращаемое значение: новая ссылка. Часть стабильного ABI начиная с версии 3.11.

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

Добавлено в версии 3.11.

PyObject *PyType_GetFullyQualifiedName(PyTypeObject *type)

Часть стабильного ABI начиная с версии 3.13.

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

Добавлено в версии 3.13.

PyObject *PyType_GetModuleName(PyTypeObject *type)

Часть стабильного ABI начиная с версии 3.13.

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

Добавлено в версии 3.13.

void *PyType_GetSlot(PyTypeObject *type, int slot)

Часть стабильного ABI начиная с версии 3.4.

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

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

Добавлено в версии 3.4.

Изменено в версии 3.10: Функция PyType_GetSlot() теперь может принимать любые типы. Ранее она поддерживала только типы в куче.

PyObject *PyType_GetModule(PyTypeObject *type)

Возвращаемое значение: заимствованная ссылка. Часть стабильного ABI начиная с версии 3.10.

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

Возвращённая ссылка заимствована у type и действительна, пока у вас есть ссылка на type. Не освобождайте её с помощью Py_DECREF() или аналогичной функции.

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

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

Добавлено в версии 3.9.

void *PyType_GetModuleState(PyTypeObject *type)

Часть стабильного ABI начиная с версии 3.10.

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

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

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

Добавлено в версии 3.9.

PyObject *PyType_GetModuleByDef(PyTypeObject *type, struct PyModuleDef *def)

Возвращаемое значение: заимствованная ссылка. Часть стабильного ABI начиная с версии 3.13.

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

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

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

Возвращённая ссылка заимствована у type и действительна, пока у вас есть ссылка на type. Не освобождайте её с помощью Py_DECREF() или аналогичной функции.

Добавлено в версии 3.11.

int PyType_GetBaseByToken(PyTypeObject *type, void *token, PyTypeObject **result)

Часть стабильного ABI начиная с версии 3.14.

Находит первый суперкласс в порядке разрешения методов типа type, у которого токен Py_tp_token совпадает с указанным.

• Если суперкласс найден, присваивает *result новую сильную ссылку на него и возвращает 1.
• Если суперкласс не найден, присваивает *result значение NULL и возвращает 0.
• При ошибке присваивает *result значение NULL и возвращает -1, установив исключение.

Аргумент result может быть равен NULL; в этом случае значение *result не устанавливается. Используйте этот вариант, если вам нужно только возвращаемое значение.

Аргумент token не может быть равен NULL.

Добавлено в версии 3.14.

int PyUnstable_Type_AssignVersionTag(PyTypeObject *type)

Это нестабильный API. Он может изменяться без предупреждения в промежуточных выпусках.

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

Возвращает 1, если тип уже имел допустимую метку версии или ему была присвоена новая, и 0, если новую метку присвоить не удалось.

Добавлено в версии 3.12.

int PyType_SUPPORTS_WEAKREFS(PyTypeObject *type)

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

См. также

• Объекты слабых ссылок
• weakref