Типовые объекты¶
-
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
. При использовании пользовательских базовых типов или метаклассов отдавайте предпочтение callingtype
(или метаклассу), а не функциям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}
.Каждый идентификатор слота должен быть указан не более одного раза.
-
const char *name¶
-
type PyType_Slot¶
- Часть Стабильный ABI (включая всех членов).
Структура, определяющая дополнительную функциональность типа, содержащая идентификатор слота и указатель значения.
-
int slot¶
Идентификатор слота.
Идентификаторы слотов называются так же, как имена полей структур
PyTypeObject
,PyNumberMethods
,PySequenceMethods
,PyMappingMethods
иPyAsyncMethods
с добавлением префиксаPy_
. Например, используйте:Py_tp_dealloc
для установкиPyTypeObject.tp_dealloc
Py_nb_add
для установкиPyNumberMethods.nb_add
Py_sq_length
для установкиPySequenceMethods.sq_length
Следующие поля «смещения» не могут быть установлены с помощью
PyType_Slot
:tp_weaklistoffset
(по возможности используйте вместо негоPy_TPFLAGS_MANAGED_WEAKREF
)tp_dictoffset
(по возможности используйте вместо негоPy_TPFLAGS_MANAGED_DICT
)tp_vectorcall_offset
(используйте"__vectorcalloffset__"
в PyMemberDef)
Если невозможно перейти на флаг
MANAGED
(например, для vectorcall или для поддержки Python старше 3.12), укажите смещение вPy_tp_members
. Подробности см. в разделе PyMemberDef documentation.Следующие поля вообще не могут быть заданы при создании типа кучи:
tp_vectorcall
(используйтеtp_new
и/илиtp_init
)Внутренние поля:
tp_dict
,tp_mro
,tp_cache
,tp_subclasses
иtp_weaklist
.
Установка
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
.
-
int slot¶