Структуры объектов типа¶Type Object Structures

Краткий справочник¶Quick Reference

Определение PyTypeObject¶PyTypeObject Definition

Определение структуры для PyTypeObject можно найти в Include/cpython/object.h. Для удобства здесь повторяется определение, приведённое там:

typedef struct _typeobject {
    PyObject_VAR_HEAD
    const char *tp_name; /* Для вывода в формате "<module>.<name>" */
    Py_ssize_t tp_basicsize, tp_itemsize; /* Для выделения памяти */

    /* Методы для реализации стандартных операций */

    destructor tp_dealloc;
    Py_ssize_t tp_vectorcall_offset;
    getattrfunc tp_getattr;
    setattrfunc tp_setattr;
    PyAsyncMethods *tp_as_async; /* ранее известный как tp_compare (Python 2)
                                    или tp_reserved (Python 3) */
    reprfunc tp_repr;

    /* Наборы методов для стандартных классов */

    PyNumberMethods *tp_as_number;
    PySequenceMethods *tp_as_sequence;
    PyMappingMethods *tp_as_mapping;

    /* Дополнительные стандартные операции (здесь для двоичной совместимости) */

    hashfunc tp_hash;
    ternaryfunc tp_call;
    reprfunc tp_str;
    getattrofunc tp_getattro;
    setattrofunc tp_setattro;

    /* Функции для доступа к объекту как к буферу ввода/вывода */
    PyBufferProcs *tp_as_buffer;

    /* Флаги для определения наличия опциональных/расширенных возможностей */
    unsigned long tp_flags;

    const char *tp_doc; /* Строка документации */

    /* Назначенное значение в версии 2.0 */
    /* вызов функции для всех доступных объектов */
    traverseproc tp_traverse;

    /* удаление ссылок на содержащиеся объекты */
    inquiry tp_clear;

    /* Назначенное значение в версии 2.1 */
    /* расширенные сравнения */
    richcmpfunc tp_richcompare;

    /* включение слабых ссылок */
    Py_ssize_t tp_weaklistoffset;

    /* Итераторы */
    getiterfunc tp_iter;
    iternextfunc tp_iternext;

    /* Дескриптор атрибутов и механизмы подклассов */
    PyMethodDef *tp_methods;
    PyMemberDef *tp_members;
    PyGetSetDef *tp_getset;
    // Сильная ссылка на тип в куче, заимствованная ссылка на статический тип
    PyTypeObject *tp_base;
    PyObject *tp_dict;
    descrgetfunc tp_descr_get;
    descrsetfunc tp_descr_set;
    Py_ssize_t tp_dictoffset;
    initproc tp_init;
    allocfunc tp_alloc;
    newfunc tp_new;
    freefunc tp_free; /* Низкоуровневая процедура освобождения памяти */
    inquiry tp_is_gc; /* Для PyObject_IS_GC */
    PyObject *tp_bases;
    PyObject *tp_mro; /* порядок разрешения методов */
    PyObject *tp_cache; /* больше не используется */
    void *tp_subclasses;  /* для статических встроенных типов это индекс */
    PyObject *tp_weaklist; /* не используется для статических встроенных типов */
    destructor tp_del;

    /* Тег версии кэша атрибутов типа. Добавлено в версии 2.6.
     * Если ноль, кэш недействителен и должен быть инициализирован.
     */
    unsigned int tp_version_tag;

    destructor tp_finalize;
    vectorcallfunc tp_vectorcall;

    /* битовый набор, указывающий, какие наблюдатели типов следят за этим типом */
    unsigned char tp_watched;

    /* Количество используемых значений tp_version_tag.
     * Устанавливается в _Py_ATTR_CACHE_UNUSED, если кэш атрибутов
     * отключен для этого типа (например, из-за пользовательских записей MRO).
     * В противном случае ограничено MAX_VERSIONS_PER_CLASS (определено в другом месте).
     */
    uint16_t tp_versions_used;
} PyTypeObject;

Слоты PyObject¶PyObject Slots

Структура объекта типа расширяет структуру PyVarObject. Поле ob_size используется для динамических типов (создаваемых с помощью type_new(), обычно вызываемого из инструкции class). Обратите внимание, что PyType_Type (метатип) инициализирует tp_itemsize, что означает, что его экземпляры (т.е. объекты типов) должны иметь поле ob_size.

PyObject.ob_refcnt

Счётчик ссылок объекта типа инициализируется значением 1 макросом PyObject_HEAD_INIT. Обратите внимание, что для статически выделенных объектов типов, экземпляры типа (объекты, чей ob_type указывает обратно на тип) не считаются ссылками. Но для динамически выделенных объектов типов экземпляры считаются ссылками.

Наследование:

Это поле не наследуется подтипами.

PyObject.ob_type

Это тип типа, иными словами, его метатип. Он инициализируется аргументом макроса PyObject_HEAD_INIT, и его значением обычно должно быть &PyType_Type. Однако для динамически загружаемых модулей расширения, которые должны работать на Windows (по крайней мере), компилятор сообщает, что это недопустимый инициализатор. Поэтому принято передавать NULL макросу PyObject_HEAD_INIT и явно инициализировать это поле в начале функции инициализации модуля, перед любыми другими действиями. Обычно это делается так:

Foo_Type.ob_type = &PyType_Type;

Это должно быть сделано до создания любых экземпляров типа. PyType_Ready() проверяет, равен ли ob_type значению NULL, и если да, инициализирует его значением поля ob_type базового класса. PyType_Ready() не будет изменять это поле, если оно ненулевое.

Наследование:

Это поле наследуется подтипами.

Слоты PyVarObject¶PyVarObject Slots

PyVarObject.ob_size

Для статически выделенных объектов типов это поле должно быть инициализировано нулём. Для динамически выделенных объектов типов это поле имеет особый внутренний смысл.

К этому полю следует обращаться с помощью макроса Py_SIZE().

Наследование:

Это поле не наследуется подтипами.

Слоты PyTypeObject¶PyTypeObject Slots

Каждый слот имеет раздел, описывающий наследование. Если PyType_Ready() может устанавливать значение, когда поле установлено в NULL, то также будет раздел «Default» (значение по умолчанию). (Обратите внимание, что многие поля, заданные в PyBaseObject_Type и PyType_Type, фактически действуют как значения по умолчанию.)

const char *PyTypeObject.tp_name¶

Указатель на строку, завершающуюся NUL, содержащую имя типа. Для типов, доступных как глобальные переменные модуля, строка должна содержать полное имя модуля, за которым следует точка, а затем имя типа; для встроенных типов это должно быть просто имя типа. Если модуль является подмодулем пакета, полное имя пакета является частью полного имени модуля. Например, тип с именем T, определённый в модуле M в подпакете Q пакета P, должен иметь инициализатор tp_name со значением "P.Q.M.T".

Для динамически выделенных объектов типов это должно быть просто имя типа, а имя модуля должно быть явно сохранено в словаре типа как значение для ключа '__module__'.

Для статически размещённых объектов типов, поле tp_name должно содержать точку. Всё до последней точки становится доступно как атрибут __module__, а всё после последней точки – как атрибут __name__.

Если точка отсутствует, всё поле tp_name становится доступным как атрибут __name__, а атрибут __module__ не определён (если только не задан явно в словаре, как описано выше). Это означает, что ваш тип невозможно будет сериализовать с помощью pickle. Кроме того, он не будет отображаться в документации модуля, создаваемой pydoc.

Это поле не должно быть NULL. Это единственное обязательное поле в PyTypeObject() (кроме потенциально tp_itemsize).

Наследование:

Это поле не наследуется подтипами.

Py_ssize_t PyTypeObject.tp_basicsize¶

Py_ssize_t PyTypeObject.tp_itemsize¶

Эти поля позволяют вычислить размер экземпляров типа в байтах.

Существует два вида типов: типы с экземплярами фиксированной длины имеют нулевое поле tp_itemsize, типы с экземплярами переменной длины имеют ненулевое поле tp_itemsize. Для типа с экземплярами фиксированной длины все экземпляры имеют одинаковый размер, заданный в tp_basicsize. (Исключения из этого правила могут быть сделаны с помощью PyUnstable_Object_GC_NewWithExtraData().)

Для типа с экземплярами переменной длины экземпляры должны иметь поле ob_size, а размер экземпляра равен tp_basicsize плюс N раз tp_itemsize, где N – это «длина» объекта.

Такие функции, как PyObject_NewVar(), принимают значение N в качестве аргумента и сохраняют его в поле ob_size экземпляра. Обратите внимание, что поле ob_size впоследствии может использоваться для других целей. Например, экземпляры int используют биты ob_size способом, определяемым реализацией; для доступа к базовому хранилищу и его размеру следует использовать PyLong_Export().

Примечание

К полю ob_size следует обращаться с помощью макросов Py_SIZE() и Py_SET_SIZE().

Кроме того, наличие поля ob_size в структуре экземпляра не означает, что структура экземпляра имеет переменную длину. Например, тип list имеет экземпляры фиксированной длины, но эти экземпляры содержат поле ob_size. (Как и в случае с int, избегайте прямого чтения ob_size списков. Вместо этого вызывайте PyList_Size().)

Поле tp_basicsize включает размер, необходимый для данных tp_base типа, а также любые дополнительные данные, необходимые каждому экземпляру.

Правильный способ установки tp_basicsize – использовать оператор sizeof для структуры, используемой для объявления структуры экземпляра. Эта структура должна включать структуру, используемую для объявления базового типа. Другими словами, tp_basicsize должно быть больше или равно tp_basicsize базового типа.

Поскольку каждый тип является подтипом object, эта структура должна включать PyObject или PyVarObject (в зависимости от того, должен ли быть включён ob_size). Обычно они определяются макросом PyObject_HEAD или PyObject_VAR_HEAD соответственно.

Базовый размер не включает размер заголовка GC, поскольку этот заголовок не является частью PyObject_HEAD.

Для случаев, когда структура, используемая для объявления базового типа, неизвестна, см. PyType_Spec.basicsize и PyType_FromMetaclass().

Примечания о выравнивании:

• tp_basicsize должно быть кратно _Alignof(PyObject). При использовании sizeof в struct, включающем PyObject_HEAD, как рекомендуется, компилятор обеспечивает это. При отказе от C-структуры struct или при использовании расширений компилятора, таких как __attribute__((packed)), ответственность ложится на вас.

• Если элементы переменной части требуют определённого выравнивания, tp_basicsize и tp_itemsize должны быть кратны этому выравниванию. Например, если переменная часть типа хранит double, вы обязаны убедиться, что оба поля кратны _Alignof(double).

Наследование:

Эти поля наследуются подтипами по отдельности. (То есть, если поле установлено в ноль, PyType_Ready() скопирует значение из базового типа, указывая, что экземпляры не нуждаются в дополнительном хранилище.)

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

destructor PyTypeObject.tp_dealloc¶

Соответствующий идентификатор слота Py_tp_dealloc является частью Stable ABI.

Указатель на функцию-деструктор экземпляра. Сигнатура функции:

void tp_dealloc(PyObject *self);

Функция-деструктор должна удалить все ссылки, которыми владеет экземпляр (например, вызвать Py_CLEAR()), освободить все буферы памяти, принадлежащие экземпляру, и вызвать функцию tp_free типа для освобождения самого объекта.

Если могут вызываться функции, которые устанавливают индикатор ошибки, необходимо использовать PyErr_GetRaisedException() и PyErr_SetRaisedException(), чтобы гарантировать, что предсуществующий индикатор ошибки не будет испорчен (освобождение могло произойти при обработке другой ошибки):

static void
foo_dealloc(foo_object *self)
{
    PyObject *et, *ev, *etb;
    PyObject *exc = PyErr_GetRaisedException();
    ...
    PyErr_SetRaisedException(exc);
}

Сам обработчик освобождения не должен вызывать исключение; если он наталкивается на ошибочную ситуацию, он должен вызвать PyErr_FormatUnraisable() для регистрации (и очистки) невыбрасываемого исключения.

Не даётся никаких гарантий относительно того, когда объект уничтожается, за исключением:

• Python уничтожает объект сразу или через некоторое время после удаления последней ссылки на него, если только его финализатор (tp_finalize) впоследствии не воскресит объект.

• Объект не будет уничтожен, пока он автоматически финализируется (tp_finalize) или автоматически очищается (tp_clear).

В CPython объект в настоящее время уничтожается сразу из Py_DECREF() когда счётчик ссылок становится равным нулю, но в будущих версиях это может измениться.

Рекомендуется вызывать PyObject_CallFinalizerFromDealloc() в начале tp_dealloc, чтобы гарантировать, что объект всегда финализируется перед уничтожением.

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

Допускается вызывать tp_clear из tp_dealloc, чтобы уменьшить дублирование кода и гарантировать, что объект всегда очищается перед уничтожением. Учтите, что tp_clear мог быть уже вызван.

Если тип размещается в куче (Py_TPFLAGS_HEAPTYPE), деаллокатор должен освободить принадлежащую ему ссылку на объект типа (через Py_DECREF()) после вызова деаллокатора типа. См. пример кода ниже:

static void
foo_dealloc(PyObject *op)
{
   foo_object *self = (foo_object *) op;
   PyObject_GC_UnTrack(self);
   Py_CLEAR(self->ref);
   Py_TYPE(self)->tp_free(self);
}

tp_dealloc должен оставлять состояние исключения неизменным. Если ему нужно вызвать что-то, что может возбудить исключение, состояние исключения необходимо сначала сохранить, а затем восстановить (после регистрации любых исключений с помощью PyErr_WriteUnraisable()).

Пример:

static void
foo_dealloc(PyObject *self)
{
    PyObject *exc = PyErr_GetRaisedException();

    if (PyObject_CallFinalizerFromDealloc(self) < 0) {
        // self был воскрешен.
        goto done;
    }

    PyTypeObject *tp = Py_TYPE(self);

    if (tp->tp_flags & Py_TPFLAGS_HAVE_GC) {
        PyObject_GC_UnTrack(self);
    }

    // Необязательно, но удобно для избежания дублирования кода.
    if (tp->tp_clear && tp->tp_clear(self) < 0) {
        PyErr_WriteUnraisable(self);
    }

    // Любое дополнительное уничтожение размещается здесь.

    tp->tp_free(self);
    self = NULL;  // На случай, если ниже вызывается PyErr_WriteUnraisable().

    if (tp->tp_flags & Py_TPFLAGS_HEAPTYPE) {
        Py_CLEAR(tp);
    }

done:
    // Необязательно, если было вызвано что-то, что могло вызвать
    // исключение.
    if (PyErr_Occurred()) {
        PyErr_WriteUnraisable(self);
    }
    PyErr_SetRaisedException(exc);
}

tp_dealloc может быть вызван из любого потока Python, не обязательно из того, который создал объект (если объект становится частью цикла ссылок, этот цикл может быть собран сборщиком мусора в любом потоке). Это не проблема для вызовов Python API, поскольку поток, в котором вызывается tp_dealloc, имеет присоединённое состояние потока. Однако если уничтожаемый объект в свою очередь уничтожает объекты из какой-то другой библиотеки на C, следует соблюдать осторожность, чтобы уничтожение этих объектов в потоке, вызвавшем tp_dealloc, не нарушило никаких предположений этой библиотеки.

Наследование:

Это поле наследуется подтипами.

См. также

Жизненный цикл объекта – подробнее о том, как этот слот связан с другими слотами.

Py_ssize_t PyTypeObject.tp_vectorcall_offset¶

Необязательное смещение к поинстансной функции, реализующей вызов объекта с помощью протокола vectorcall, более эффективная альтернатива более простому tp_call.

Это поле используется только в том случае, если установлен флаг Py_TPFLAGS_HAVE_VECTORCALL . В этом случае оно должно быть положительным целым числом, содержащим смещение в экземпляре указателя vectorcallfunc.

Указатель vectorcallfunc может быть NULL, и в этом случае экземпляр ведёт себя так, как если бы Py_TPFLAGS_HAVE_VECTORCALL не был установлен: вызов экземпляра сводится к tp_call.

Любой класс, устанавливающий Py_TPFLAGS_HAVE_VECTORCALL, должен также установить tp_call и убедиться, что его поведение согласуется с функцией vectorcallfunc. Это можно сделать, установив tp_call в PyVectorcall_Call().

Изменено в версии 3.8: До версии 3.8 этот слот назывался tp_print. В Python 2.x он использовался для вывода в файл. В Python 3.0–3.7 он не использовался.

Изменено в версии 3.12: До версии 3.12 не рекомендовалось для изменяемых типов, размещаемых в куче реализовывать протокол vectorcall. Когда пользователь устанавливает __call__ в коде Python, обновляется только tp_call, что, вероятно, делает его несовместимым с функцией vectorcall. Начиная с версии 3.12, установка __call__ отключает оптимизацию vectorcall путём сброса флага Py_TPFLAGS_HAVE_VECTORCALL.

Наследование:

Это поле всегда наследуется. Однако флаг Py_TPFLAGS_HAVE_VECTORCALL наследуется не всегда. Если он не установлен, то подкласс не будет использовать vectorcall, за исключением случаев, когда PyVectorcall_Call() вызывается явно.

getattrfunc PyTypeObject.tp_getattr¶

Соответствующий идентификатор слота Py_tp_getattr является частью Stable ABI.

Необязательный указатель на функцию получения строки атрибута.

Это поле устарело. Если оно определено, оно должно указывать на функцию, которая действует так же, как функция tp_getattro, но принимает C-строку вместо строкового объекта Python для указания имени атрибута.

Наследование:

Группа: tp_getattr, tp_getattro

Это поле наследуется подтипами вместе с tp_getattro: подтип наследует и tp_getattr, и tp_getattro от своего базового типа, когда tp_getattr и tp_getattro подтипа оба равны NULL.

setattrfunc PyTypeObject.tp_setattr¶

Соответствующий идентификатор слота Py_tp_setattr является частью Stable ABI.

Необязательный указатель на функцию для установки и удаления атрибутов.

Это поле устарело. Если оно определено, оно должно указывать на функцию, которая действует так же, как функция tp_setattro, но принимает C-строку вместо строкового объекта Python для указания имени атрибута.

Наследование:

Группа: tp_setattr, tp_setattro

Это поле наследуется подтипами вместе с tp_setattro: подтип наследует и tp_setattr, и tp_setattro от своего базового типа, когда tp_setattr и tp_setattro подтипа оба равны NULL.

PyAsyncMethods *PyTypeObject.tp_as_async¶

Указатель на дополнительную структуру, содержащую поля, значимые только для объектов, реализующих протоколы ожидаемого объекта и асинхронного итератора на уровне C. Подробнее см. в Структуры асинхронных объектов.

Добавлено в версии 3.5: Ранее было известно как tp_compare и tp_reserved.

Наследование:

Поле tp_as_async не наследуется, но содержащиеся в нем поля наследуются по отдельности.

reprfunc PyTypeObject.tp_repr¶

Соответствующий идентификатор слота Py_tp_repr является частью Stable ABI.

Необязательный указатель на функцию, реализующую встроенную функцию repr().

Сигнатура такая же, как для PyObject_Repr():

PyObject *tp_repr(PyObject *self);

Функция должна возвращать строку или объект Unicode. В идеале она должна возвращать строку, которая при передаче в eval() в подходящем окружении возвращает объект с тем же значением. Если это невозможно, она должна возвращать строку, начинающуюся с '<' и заканчивающуюся '>', из которой можно вывести как тип, так и значение объекта.

Наследование:

Это поле наследуется подтипами.

По умолчанию:

Если это поле не задано, возвращается строка вида <%s object at %p>, где %s заменяется именем типа, а %p – адресом памяти объекта.

PyNumberMethods *PyTypeObject.tp_as_number¶

Указатель на дополнительную структуру, содержащую поля, значимые только для объектов, реализующих числовой протокол. Эти поля описаны в Структуры числовых объектов.

Наследование:

Поле tp_as_number не наследуется, но содержащиеся в нём поля наследуются по отдельности.

PySequenceMethods *PyTypeObject.tp_as_sequence¶

Указатель на дополнительную структуру, содержащую поля, значимые только для объектов, реализующих протокол последовательности. Эти поля описаны в Структуры объектов-последовательностей.

Наследование:

Поле tp_as_sequence не наследуется, но содержащиеся в нём поля наследуются по отдельности.

PyMappingMethods *PyTypeObject.tp_as_mapping¶

Указатель на дополнительную структуру, содержащую поля, значимые только для объектов, реализующих протокол отображения. Эти поля описаны в Структуры объектов-отображений.

Наследование:

Поле tp_as_mapping не наследуется, но содержащиеся в нём поля наследуются по отдельности.

hashfunc PyTypeObject.tp_hash¶

Соответствующий идентификатор слота Py_tp_hash является частью Stable ABI.

Необязательный указатель на функцию, реализующую встроенную функцию hash().

Сигнатура такая же, как для PyObject_Hash():

Py_hash_t tp_hash(PyObject *);

Значение -1 не должно возвращаться как обычное возвращаемое значение; при возникновении ошибки во время вычисления хеш-значения функция должна установить исключение и вернуть -1.

Если это поле не задано (и tp_richcompare не задано), то попытка получить хеш объекта вызывает TypeError. Это то же самое, что установить его в PyObject_HashNotImplemented().

Это поле можно явно установить в PyObject_HashNotImplemented(), чтобы заблокировать наследование хеш-метода от родительского типа. Это интерпретируется как эквивалент __hash__ = None на уровне Python, в результате чего isinstance(o, collections.Hashable) корректно возвращает False. Обратите внимание, что верно и обратное: установка __hash__ = None в классе на уровне Python приведет к тому, что слот tp_hash будет установлен в PyObject_HashNotImplemented().

Наследование:

Группа: tp_hash, tp_richcompare

Это поле наследуется подтипами вместе с tp_richcompare: подтип наследует как tp_richcompare, так и tp_hash, если tp_richcompare и tp_hash подтипа равны NULL.

По умолчанию:

PyBaseObject_Type использует PyObject_GenericHash().

ternaryfunc PyTypeObject.tp_call¶

Соответствующий идентификатор слота Py_tp_call является частью Stable ABI.

Необязательный указатель на функцию, реализующую вызов объекта. Это значение должно быть NULL, если объект не является вызываемым. Сигнатура такая же, как у PyObject_Call():

PyObject *tp_call(PyObject *self, PyObject *args, PyObject *kwargs);

Наследование:

Это поле наследуется подтипами.

reprfunc PyTypeObject.tp_str¶

Соответствующий идентификатор слота Py_tp_str является частью Stable ABI.

Необязательный указатель на функцию, реализующую встроенную операцию str(). (Обратите внимание, что str теперь является типом, а str() вызывает конструктор этого типа. Этот конструктор вызывает PyObject_Str() для выполнения фактической работы, и PyObject_Str() будет вызывать этот обработчик.)

Сигнатура такая же, как для PyObject_Str():

PyObject *tp_str(PyObject *self);

Функция должна возвращать строку или объект Unicode. Это должно быть «дружественное» строковое представление объекта, так как это представление будет использоваться, в частности, функцией print().

Наследование:

Это поле наследуется подтипами.

По умолчанию:

Если это поле не задано, вызывается PyObject_Repr() для возврата строкового представления.

getattrofunc PyTypeObject.tp_getattro¶

Соответствующий идентификатор слота Py_tp_getattro является частью Stable ABI.

Необязательный указатель на функцию получения атрибута.

Сигнатура такая же, как для PyObject_GetAttr():

PyObject *tp_getattro(PyObject *self, PyObject *attr);

Обычно удобно установить это поле в PyObject_GenericGetAttr(), которое реализует обычный способ поиска атрибутов объекта.

Наследование:

Группа: tp_getattr, tp_getattro

Это поле наследуется подтипами вместе с tp_getattr: подтип наследует и tp_getattr, и tp_getattro от своего базового типа, когда tp_getattr и tp_getattro подтипа оба равны NULL.

По умолчанию:

PyBaseObject_Type использует PyObject_GenericGetAttr().

setattrofunc PyTypeObject.tp_setattro¶

Соответствующий идентификатор слота Py_tp_setattro является частью Stable ABI.

Необязательный указатель на функцию для установки и удаления атрибутов.

Сигнатура такая же, как для PyObject_SetAttr():

int tp_setattro(PyObject *self, PyObject *attr, PyObject *value);

Кроме того, установка value в NULL для удаления атрибута должна поддерживаться. Обычно удобно устанавливать это поле в PyObject_GenericSetAttr(), которое реализует обычный способ установки атрибутов объекта.

Наследование:

Группа: tp_setattr, tp_setattro

Это поле наследуется подтипами вместе с tp_setattr: подтип наследует и tp_setattr, и tp_setattro от своего базового типа, когда tp_setattr и tp_setattro подтипа оба равны NULL.

По умолчанию:

PyBaseObject_Type использует PyObject_GenericSetAttr().

PyBufferProcs *PyTypeObject.tp_as_buffer¶

Указатель на дополнительную структуру, содержащую поля, значимые только для объектов, реализующих буферный интерфейс. Эти поля описаны в Buffer Object Structures.

Наследование:

Поле tp_as_buffer не наследуется, но содержащиеся в нем поля наследуются по отдельности.

unsigned long PyTypeObject.tp_flags¶

Это поле представляет собой битовую маску различных флагов. Некоторые флаги указывают на изменённую семантику для определённых ситуаций; другие используются для указания того, что определённые поля в объекте типа (или в расширяющих структурах, на которые ссылаются через tp_as_number, tp_as_sequence, tp_as_mapping и tp_as_buffer), которые исторически не всегда присутствовали, теперь действительны; если такой бит флага сброшен, то поля типа, которые он защищает, не должны использоваться и должны считаться имеющими значение ноль или NULL.

Наследование:

Наследование этого поля сложное. Большинство битов флагов наследуются индивидуально, т.е. если у базового типа установлен бит флага, подтип наследует этот бит флага. Биты флагов, относящиеся к расширяющим структурам, строго наследуются, если наследуется расширяющая структура, т.е. значение бита флага базового типа копируется в подтип вместе с указателем на расширяющую структуру. Бит флага Py_TPFLAGS_HAVE_GC наследуется вместе с полями tp_traverse и tp_clear, т.е. если бит флага Py_TPFLAGS_HAVE_GC сброшен в подтипе, а поля tp_traverse и tp_clear в подтипе существуют и имеют значения NULL.

По умолчанию:

PyBaseObject_Type использует Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE.

Битовые маски:

В настоящее время определены следующие битовые маски; их можно объединять с помощью оператора | для получения значения поля tp_flags. Макрос PyType_HasFeature() принимает тип и значение флагов, tp и f, и проверяет, является ли tp->tp_flags & f ненулевым.

Py_TPFLAGS_HEAPTYPE¶

Этот бит устанавливается, когда сам объект типа выделяется в куче, например, типы, созданные динамически с помощью PyType_FromSpec(). В этом случае поле ob_type его экземпляров считается ссылкой на тип, и объект типа инкрементируется (INCREF) при создании нового экземпляра, и декрементируется (DECREF) при уничтожении экземпляра (это не относится к экземплярам подтипов; только тип, на который ссылается ob_type экземпляра, инкрементируется или декрементируется). Типы в куче также должны поддерживать сборку мусора так как они могут образовывать циклические ссылки с собственным объектом модуля.

Наследование:

???

Py_TPFLAGS_BASETYPE¶

Часть Stable ABI.

Этот бит устанавливается, когда тип может использоваться как базовый тип другого типа. Если этот бит сброшен, тип не может быть унаследован (аналогично «финальному» классу в Java).

Наследование:

???

Py_TPFLAGS_READY¶

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

Наследование:

???

Py_TPFLAGS_READYING¶

Этот бит устанавливается, пока PyType_Ready() находится в процессе инициализации объекта типа.

Наследование:

???

Py_TPFLAGS_HAVE_GC¶

Часть Stable ABI.

Этот бит устанавливается, если объект поддерживает сборку мусора. Если этот бит установлен, память для новых экземпляров (см. tp_alloc) должна выделяться с помощью PyObject_GC_New или PyType_GenericAlloc(), а освобождаться (см. tp_free) с помощью PyObject_GC_Del(). Дополнительная информация в разделе Поддержка циклической сборки мусора.

Наследование:

Группа: Py_TPFLAGS_HAVE_GC, tp_traverse, tp_clear

Бит флага Py_TPFLAGS_HAVE_GC наследуется вместе с полями tp_traverse и tp_clear, то есть если бит флага Py_TPFLAGS_HAVE_GC сброшен в подтипе, а поля tp_traverse и tp_clear в подтипе существуют и имеют значения NULL.

Py_TPFLAGS_DEFAULT¶

Часть Stable ABI.

Это битовая маска всех битов, относящихся к наличию определённых полей в объекте типа и его структурах расширения. В настоящее время она включает следующие биты: Py_TPFLAGS_HAVE_STACKLESS_EXTENSION.

Наследование:

???

Py_TPFLAGS_METHOD_DESCRIPTOR¶

Часть Stable ABI с версии 3.8.

Этот бит указывает, что объекты ведут себя как несвязанные методы.

Если этот флаг установлен для type(meth), то:

• meth.__get__(obj, cls)(*args, **kwds) (при obj не None) должен быть эквивалентен meth(obj, *args, **kwds).

• meth.__get__(None, cls)(*args, **kwds) должен быть эквивалентен meth(*args, **kwds).

Этот флаг включает оптимизацию для типичных вызовов методов, таких как obj.meth(): он позволяет избежать создания временного объекта «связанный метод» для obj.meth.

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

Наследование:

Этот флаг никогда не наследуется типами, у которых не установлен флаг Py_TPFLAGS_IMMUTABLETYPE. Для типов расширения он наследуется всякий раз, когда наследуется tp_descr_get.

Py_TPFLAGS_MANAGED_DICT¶

Этот бит указывает, что экземпляры класса имеют атрибут __dict__, и что память для словаря управляется виртуальной машиной.

Если этот флаг установлен, Py_TPFLAGS_HAVE_GC также должен быть установлен.

Функция обхода типа должна вызывать PyObject_VisitManagedDict(), а функция очистки должна вызывать PyObject_ClearManagedDict().

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

Наследование:

Этот флаг наследуется, если только поле tp_dictoffset не установлено в суперклассе.

Py_TPFLAGS_MANAGED_WEAKREF¶

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

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

Наследование:

Этот флаг наследуется, если только поле tp_weaklistoffset не установлено в суперклассе.

Py_TPFLAGS_ITEMS_AT_END¶

Часть Stable ABI начиная с версии 3.12.

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

Указывает, что часть переменного размера экземпляра этого типа находится в конце области памяти экземпляра, со смещением Py_TYPE(obj)->tp_basicsize (которое может отличаться в каждом подклассе).

При установке этого флага убедитесь, что все суперклассы либо используют такое же расположение в памяти, либо не являются типами переменного размера. Python не проверяет это условие.

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

Наследование:

Этот флаг наследуется.

Py_TPFLAGS_LONG_SUBCLASS¶

Py_TPFLAGS_LIST_SUBCLASS¶

Py_TPFLAGS_TUPLE_SUBCLASS¶

Py_TPFLAGS_BYTES_SUBCLASS¶

Py_TPFLAGS_UNICODE_SUBCLASS¶

Py_TPFLAGS_DICT_SUBCLASS¶

Py_TPFLAGS_BASE_EXC_SUBCLASS¶

Py_TPFLAGS_TYPE_SUBCLASS¶

Такие функции, как PyLong_Check(), вызывают PyType_FastSubclass() с одним из этих флагов, чтобы быстро определить, является ли тип подклассом встроенного типа; такие конкретные проверки выполняются быстрее, чем общая проверка, например PyObject_IsInstance(). Пользовательские типы, наследуемые от встроенных, должны иметь соответствующим образом установленный tp_flags, иначе код, взаимодействующий с такими типами, будет вести себя по-разному в зависимости от того, какая проверка используется.

Py_TPFLAGS_HAVE_FINALIZE¶

Этот бит устанавливается, когда слот tp_finalize присутствует в структуре типа.

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

Устарело с версии 3.8: Этот флаг больше не нужен, так как интерпретатор предполагает, что слот tp_finalize всегда присутствует в структуре типа.

Py_TPFLAGS_HAVE_VECTORCALL¶

Часть Stable ABI начиная с версии 3.12.

Этот бит устанавливается, когда класс реализует протокол vectorcall. Подробнее см. tp_vectorcall_offset.

Наследование:

Этот бит наследуется, если tp_call также наследуется.

Добавлено в версии 3.8: как _Py_TPFLAGS_HAVE_VECTORCALL

Изменено в версии 3.9: Переименовано в текущее имя без ведущего подчёркивания. Старое временное имя мягко устарело.

Изменено в версии 3.12: Теперь этот флаг удаляется из класса, когда __call__() методу класса присваивается новое значение.

Теперь этот флаг может наследоваться изменяемыми классами.

Py_TPFLAGS_IMMUTABLETYPE¶

Этот бит устанавливается для объектов типа, которые являются неизменяемыми: атрибуты типа нельзя ни установить, ни удалить.

PyType_Ready() автоматически применяет этот флаг к статическим типам.

Наследование:

Этот флаг не наследуется.

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

Py_TPFLAGS_DISALLOW_INSTANTIATION¶

Запретить создание экземпляров типа: установить tp_new в NULL и не создавать ключ __new__ в словаре типа.

Флаг должен быть установлен до создания типа, а не после. Например, его нужно установить до вызова PyType_Ready() для этого типа.

Флаг устанавливается автоматически для статических типов, если tp_base равен NULL или &PyBaseObject_Type, и tp_new равен NULL.

Наследование:

Этот флаг не наследуется. Однако подклассы нельзя будет инстанцировать, если они не предоставят ненулевой tp_new (что возможно только через C API).

Примечание

Чтобы запретить прямое создание экземпляров класса, но разрешить создание его подклассов (например, для абстрактного базового класса), не используйте этот флаг. Вместо этого добейтесь, чтобы tp_new завершался успешно только для подклассов.

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

Py_TPFLAGS_MAPPING¶

Этот бит указывает, что экземпляры класса могут сопоставляться с шаблонами отображений при использовании в качестве объекта оператора match. Он автоматически устанавливается при регистрации или наследовании collections.abc.Mapping и сбрасывается при регистрации collections.abc.Sequence.

Примечание

Py_TPFLAGS_MAPPING и Py_TPFLAGS_SEQUENCE взаимоисключающие; одновременная активация обоих флагов является ошибкой.

Наследование:

Этот флаг наследуется типами, которые ещё не установили Py_TPFLAGS_SEQUENCE.

См. также

PEP 634 – Структурное сопоставление с образцом: спецификация

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

Py_TPFLAGS_SEQUENCE¶

Этот бит указывает, что экземпляры класса могут сопоставляться с шаблонами последовательностей при использовании в качестве объекта оператора match. Он автоматически устанавливается при регистрации или наследовании collections.abc.Sequence и сбрасывается при регистрации collections.abc.Mapping.

Примечание

Py_TPFLAGS_MAPPING и Py_TPFLAGS_SEQUENCE взаимоисключающие; одновременная активация обоих флагов является ошибкой.

Наследование:

Этот флаг наследуется типами, которые ещё не установили Py_TPFLAGS_MAPPING.

См. также

PEP 634 – Структурное сопоставление с образцом: спецификация

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

Py_TPFLAGS_VALID_VERSION_TAG¶

Внутренний флаг. Не устанавливайте и не сбрасывайте этот флаг. Чтобы указать, что класс изменился, вызовите PyType_Modified()

Предупреждение

Этот флаг присутствует в заголовочных файлах, но не используется. Он будет удалён в будущей версии CPython.

Py_TPFLAGS_HAVE_VERSION_TAG¶

Этот макрос ничего не делает. Исторически он указывал, что поле tp_version_tag доступно и инициализировано.

Мягкое устаревание начиная с версии 3.13.

Py_TPFLAGS_INLINE_VALUES¶

Этот бит указывает, что экземпляры этого типа будут иметь массив «встроенных значений», содержащий атрибуты объекта, размещённый сразу после конца объекта.

Для этого необходимо, чтобы был установлен Py_TPFLAGS_HAVE_GC.

Наследование:

Этот флаг не наследуется.

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

Py_TPFLAGS_IS_ABSTRACT¶

Этот бит указывает, что это абстрактный тип и поэтому не может быть инстанцирован.

Наследование:

Этот флаг не наследуется.

См. также

abc

Py_TPFLAGS_HAVE_STACKLESS_EXTENSION¶

Внутренний. Не устанавливайте и не снимайте этот флаг. Исторически это был зарезервированный флаг для использования в Stackless Python.

Предупреждение

Этот флаг присутствует в заголовочных файлах, но не используется. Он может быть удалён в будущей версии CPython.

const char *PyTypeObject.tp_doc¶

Соответствующий идентификатор слота Py_tp_doc является частью Stable ABI.

Необязательный указатель на C-строку, завершающуюся символом NUL, содержащую строку документации для данного объекта типа. Он доступен как атрибут __doc__ у типа и его экземпляров.

Наследование:

Это поле не наследуется подтипами.

traverseproc PyTypeObject.tp_traverse¶

Соответствующий идентификатор слота Py_tp_traverse является частью Stable ABI.

Необязательный указатель на функцию обхода для сборщика мусора. Используется только если установлен бит флага Py_TPFLAGS_HAVE_GC. Сигнатура:

int tp_traverse(PyObject *self, visitproc visit, void *arg);

Дополнительная информация о схеме сборки мусора в Python доступна в разделе Поддержка циклической сборки мусора.

Указатель tp_traverse используется сборщиком мусора для обнаружения циклических ссылок. Типичная реализация функции tp_traverse просто вызывает Py_VISIT() для каждого элемента экземпляра, являющегося объектом Python, которым владеет экземпляр. Например, это функция local_traverse() из модуля расширения _thread:

static int
local_traverse(PyObject *op, visitproc visit, void *arg)
{
    localobject *self = (localobject *) op;
    Py_VISIT(self->args);
    Py_VISIT(self->kw);
    Py_VISIT(self->dict);
    return 0;
}

Обратите внимание, что Py_VISIT() вызывается только для тех членов, которые могут участвовать в циклических ссылках. Хотя есть также член self->key, он может быть только NULL или строкой Python и поэтому не может быть частью циклической ссылки.

С другой стороны, даже если известно, что член никогда не может быть частью цикла, в качестве средства отладки его всё равно можно обойти, чтобы функция get_referents() модуля gc включила его.

Кучевые типы (Py_TPFLAGS_HEAPTYPE) должны обходить свой тип с помощью:

Py_VISIT(Py_TYPE(self));

Это требуется только начиная с Python 3.9. Для поддержки Python 3.8 и старше эта строка должна быть условной:

#if PY_VERSION_HEX >= 0x03090000
    Py_VISIT(Py_TYPE(self));
#endif

Если бит Py_TPFLAGS_MANAGED_DICT установлен в поле tp_flags, функция обхода должна вызвать PyObject_VisitManagedDict() следующим образом:

PyObject_VisitManagedDict((PyObject*)self, visit, arg);

Предупреждение

При реализации tp_traverse должны обходиться только те члены, которыми экземпляр владеет (имея на них сильные ссылки). Например, если объект поддерживает слабые ссылки через слот tp_weaklist, указатель, поддерживающий связанный список (то, на что указывает tp_weaklist), не должен обходиться, поскольку экземпляр не владеет напрямую слабыми ссылками на себя (список слабых ссылок существует для поддержки механизма слабых ссылок, но у экземпляра нет сильной ссылки на элементы внутри него, так как они могут быть удалены, даже если экземпляр всё ещё жив).

Предупреждение

Функция обхода не должна иметь побочных эффектов. Она не должна изменять счётчики ссылок каких-либо объектов Python, а также создавать или уничтожать какие-либо объекты Python.

Обратите внимание, что Py_VISIT() требует, чтобы параметры visit и arg для local_traverse() имели именно такие имена; не следует называть их как попало.

Экземпляры кучевых типов содержат ссылку на свой тип. Поэтому их функция обхода должна либо обходить Py_TYPE(self), либо делегировать эту ответственность путём вызова tp_traverse другого кучевого типа (например, кучевого суперкласса). Если этого не сделать, объект типа может не быть собран сборщиком мусора.

Примечание

Функцию tp_traverse можно вызывать из любого потока.

Изменено в версии 3.9: Ожидается, что типы, выделяемые в куче, будут посещать Py_TYPE(self) в tp_traverse. В более ранних версиях Python из-за ошибки 40217 это могло приводить к сбоям в подклассах.

Наследование:

Группа: Py_TPFLAGS_HAVE_GC, tp_traverse, tp_clear

Это поле наследуется подтипами вместе с tp_clear и флагом Py_TPFLAGS_HAVE_GC: флаг, tp_traverse и tp_clear наследуются от базового типа, если они равны нулю в подтипе.

inquiry PyTypeObject.tp_clear¶

Соответствующий идентификатор слота Py_tp_clear является частью Stable ABI.

Необязательный указатель на функцию очистки. Сигнатура:

int tp_clear(PyObject *);

Назначение этой функции – разрывать циклические ссылки, которые приводят к образованию циклического изолята, чтобы объекты можно было безопасно уничтожить. Очищенный объект является частично уничтоженным; такой объект не обязан удовлетворять инвариантам проектирования, соблюдаемым при нормальном использовании.

tp_clear не нужно удалять ссылки на объекты, которые не могут участвовать в циклических ссылках, такие как строки Python или целые числа Python. Однако может быть удобно очищать все ссылки и написать функцию tp_dealloc типа так, чтобы она вызывала tp_clear во избежание дублирования кода. (Имейте в виду, что tp_clear могла уже быть вызвана. Предпочтительнее вызывать идемпотентные функции, такие как Py_CLEAR().)

Любую нетривиальную очистку следует выполнять в tp_finalize, а не в tp_clear.

Примечание

Если tp_clear не удаётся разорвать циклическую ссылку, то объекты в циклическом изоляте могут остаться не собираемыми на неопределённый срок («утечка»). См. gc.garbage.

Примечание

Референты (прямые и косвенные) могли уже быть очищены; нет гарантии, что они находятся в согласованном состоянии.

Примечание

Функцию tp_clear можно вызывать из любого потока.

Примечание

Нет гарантии, что объект будет автоматически очищен до вызова его деструктора (tp_dealloc).

Эта функция отличается от деструктора (tp_dealloc) следующим образом:

• Цель очистки объекта – удалить ссылки на другие объекты, которые могут участвовать в циклической ссылке. Цель деструктора, напротив, шире: он должен освободить все ресурсы, которыми владеет, включая ссылки на объекты, не участвующие в циклических ссылках (например, целые числа), а также собственную память объекта (путём вызова tp_free).

• Когда вызывается tp_clear, другие объекты могут всё ещё содержать ссылки на очищаемый объект. Из-за этого tp_clear не должна освобождать собственную память объекта (tp_free). Деструктор, напротив, вызывается только тогда, когда нет (сильных) ссылок, и поэтому он должен безопасно уничтожить сам объект, освободив его память.

• tp_clear может никогда не быть вызвана автоматически. Деструктор объекта, напротив, будет автоматически вызван через некоторое время после того, как объект станет недостижимым (т.е. либо на объект нет ссылок, либо объект является членом циклического изолята).

Не даётся никаких гарантий относительно того, когда, если и как часто Python автоматически очищает объект, за исключением:

• Python не будет автоматически очищать объект, если он достижим, то есть на него есть ссылка и он не является членом циклического изолята.

• Python не будет автоматически очищать объект, если он не был автоматически финализирован (см. tp_finalize). (Если финализатор возродил объект, объект может быть или не быть снова автоматически финализирован перед очисткой.)

• Если объект является членом циклического изолята, Python не будет автоматически очищать его, если какой-либо член циклического изолята ещё не был автоматически финализирован (tp_finalize).

• Python не уничтожит объект до тех пор, пока не завершатся все автоматические вызовы его функции tp_clear. Это гарантирует, что разрыв цикла ссылок не сделает недействительным указатель self, пока tp_clear ещё выполняется.

• Python не будет автоматически вызывать tp_clear несколько раз одновременно.

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

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

Реализации tp_clear должны удалять ссылки экземпляра на те его члены, которые могут являться объектами Python, и устанавливать указатели на эти члены в NULL, как показано в следующем примере:

static int
local_clear(PyObject *op)
{
    localobject *self = (localobject *) op;
    Py_CLEAR(self->key);
    Py_CLEAR(self->args);
    Py_CLEAR(self->kw);
    Py_CLEAR(self->dict);
    return 0;
}

Следует использовать макрос Py_CLEAR(), потому что очистка ссылок – это деликатная операция: ссылка на содержащийся объект не должна освобождаться (через Py_DECREF()) до тех пор, пока указатель на содержащийся объект не будет установлен в NULL. Это связано с тем, что освобождение ссылки может привести к тому, что содержащийся объект станет мусором, что вызовет цепочку действий по его утилизации, которая может включать выполнение произвольного кода Python (из-за финализаторов или колбэков слабых ссылок, связанных с содержащимся объектом). Если такой код может снова сослаться на self, важно, чтобы указатель на содержащийся объект в этот момент был NULL, чтобы self знал, что содержащийся объект больше нельзя использовать. Макрос Py_CLEAR() выполняет операции в безопасном порядке.

Если бит Py_TPFLAGS_MANAGED_DICT установлен в поле tp_flags, функция очистки должна вызвать PyObject_ClearManagedDict() следующим образом:

PyObject_ClearManagedDict((PyObject*)self);

Дополнительную информацию о схеме сборки мусора Python можно найти в разделе Поддержка циклической сборки мусора.

Наследование:

Группа: Py_TPFLAGS_HAVE_GC, tp_traverse, tp_clear

Это поле наследуется подтипами вместе с tp_traverse и флагом Py_TPFLAGS_HAVE_GC: флаг, tp_traverse и tp_clear наследуются от базового типа, если они равны нулю в подтипе.

См. также

Жизненный цикл объекта – подробнее о том, как этот слот связан с другими слотами.

richcmpfunc PyTypeObject.tp_richcompare¶

Соответствующий идентификатор слота Py_tp_richcompare является частью Stable ABI.

Необязательный указатель на функцию расширенного сравнения, сигнатура которой:

PyObject *tp_richcompare(PyObject *self, PyObject *other, int op);

Первый параметр гарантированно является экземпляром типа, определяемого через PyTypeObject.

Функция должна возвращать результат сравнения (обычно Py_True или Py_False). Если сравнение не определено, она должна вернуть Py_NotImplemented; если произошла другая ошибка, она должна вернуть NULL и установить условие исключения.

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

Константа	Сравнение
Py_LT¶	<
Py_LE¶	<=
Py_EQ¶	==
Py_NE¶	!=
Py_GT¶	>
Py_GE¶	>=

Для упрощения написания функций расширенного сравнения определён следующий макрос:

Py_RETURN_RICHCOMPARE(VAL_A, VAL_B, op)¶

Возвращает Py_True или Py_False из функции в зависимости от результата сравнения. VAL_A и VAL_B должны быть упорядочиваемыми с помощью операторов сравнения языка C (например, это могут быть значения типа int или float). Третий аргумент задаёт требуемую операцию, как и для PyObject_RichCompare().

Возвращаемое значение – это новая сильная ссылка.

В случае ошибки устанавливает исключение и возвращает NULL из функции.

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

Наследование:

Группа: tp_hash, tp_richcompare

Это поле наследуется подтипами вместе с tp_hash: подтип наследует tp_richcompare и tp_hash, когда tp_richcompare и tp_hash подтипа оба NULL.

По умолчанию:

PyBaseObject_Type предоставляет реализацию tp_richcompare, которая может быть унаследована. Однако, если определено только tp_hash, унаследованная функция не используется, и экземпляры типа не смогут участвовать в сравнениях.

Py_ssize_t PyTypeObject.tp_weaklistoffset¶

Хотя это поле всё ещё поддерживается, Py_TPFLAGS_MANAGED_WEAKREF следует использовать вместо него, если это возможно.

Если экземпляры этого типа поддерживают слабые ссылки, это поле больше нуля и содержит смещение в структуре экземпляра до головы списка слабых ссылок (игнорируя заголовок GC, если он присутствует); это смещение используется функциями PyObject_ClearWeakRefs() и PyWeakref_*. Структура экземпляра должна содержать поле типа PyObject*, которое инициализируется NULL.

Не путайте это поле с tp_weaklist; это голова списка для слабых ссылок на сам объект типа.

Установка обоих битов Py_TPFLAGS_MANAGED_WEAKREF и tp_weaklistoffset является ошибкой.

Наследование:

Это поле наследуется подтипами, но см. правила ниже. Подтип может переопределить это смещение; это означает, что подтип использует другую голову списка слабых ссылок, нежели базовый тип. Поскольку голова списка всегда находится через tp_weaklistoffset, это не должно быть проблемой.

По умолчанию:

Если бит Py_TPFLAGS_MANAGED_WEAKREF установлен в поле tp_flags, то tp_weaklistoffset будет установлено в отрицательное значение, чтобы указать, что использовать это поле небезопасно.

getiterfunc PyTypeObject.tp_iter¶

Соответствующий идентификатор слота Py_tp_iter является частью Stable ABI.

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

Эта функция имеет ту же сигнатуру, что и PyObject_GetIter():

PyObject *tp_iter(PyObject *self);

Наследование:

Это поле наследуется подтипами.

iternextfunc PyTypeObject.tp_iternext¶

Соответствующий идентификатор слота Py_tp_iternext является частью Stable ABI.

Необязательный указатель на функцию, возвращающую следующий элемент итератора. Сигнатура:

PyObject *tp_iternext(PyObject *self);

Когда итератор исчерпан, он должен возвращать NULL; исключение StopIteration может быть установлено или нет. При другой ошибке он также должен возвращать NULL. Его наличие означает, что экземпляры этого типа являются итераторами.

Типы-итераторы также должны определять функцию tp_iter, и эта функция должна возвращать сам экземпляр итератора (не новый экземпляр итератора).

Эта функция имеет ту же сигнатуру, что и PyIter_Next().

Наследование:

Это поле наследуется подтипами.

struct PyMethodDef *PyTypeObject.tp_methods¶

Соответствующий идентификатор слота Py_tp_methods является частью Stable ABI.

Необязательный указатель на статический массив структур PyMethodDef, завершающийся NULL, объявляющий обычные методы этого типа.

Для каждой записи в массиве в словарь типа добавляется запись (см. tp_dict ниже), содержащая дескриптор метода.

Наследование:

Это поле не наследуется подтипами (методы наследуются через другой механизм).

struct PyMemberDef *PyTypeObject.tp_members¶

Соответствующий идентификатор слота Py_tp_members является частью Stable ABI.

Необязательный указатель на статический массив PyMemberDef структур, завершающийся NULL, объявляющий обычные элементы данных (поля или слоты) экземпляров этого типа.

Для каждой записи в массиве в словарь типа добавляется запись, содержащая дескриптор члена (см. tp_dict ниже).

Наследование:

Это поле не наследуется подтипами (члены наследуются через другой механизм).

struct PyGetSetDef *PyTypeObject.tp_getset¶

Соответствующий идентификатор слота Py_tp_getset является частью Stable ABI.

Необязательный указатель на статический массив PyGetSetDef структур, завершающийся NULL, объявляющий вычисляемые атрибуты экземпляров этого типа.

Для каждой записи в массиве в словарь типа добавляется запись, содержащая дескриптор getset (см. tp_dict ниже).

Наследование:

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

PyTypeObject *PyTypeObject.tp_base¶

Соответствующий идентификатор слота Py_tp_base является частью Stable ABI.

Необязательный указатель на базовый тип, от которого наследуются свойства типа. На этом уровне поддерживается только одиночное наследование; множественное наследование требует динамического создания объекта типа вызовом метатипа.

Примечание

Инициализация слотов подчиняется правилам инициализации глобальных переменных. C99 требует, чтобы инициализаторы были «адресными константами». Обозначения функций, такие как PyType_GenericNew(), с неявным преобразованием в указатель, являются допустимыми адресными константами C99.

Однако унарный оператор '&', применённый к нестатической переменной, такой как PyBaseObject_Type, не обязан давать адресную константу. Компиляторы могут это поддерживать (gcc поддерживает), MSVC – нет. Оба компилятора в этом конкретном поведении строго соответствуют стандарту.

Следовательно, tp_base должно устанавливаться в функции инициализации модуля расширения.

Наследование:

Это поле не наследуется подтипами (очевидно).

По умолчанию:

По умолчанию это поле равно &PyBaseObject_Type (которое программистам Python известно как тип object).

PyObject *PyTypeObject.tp_dict¶

Словарь типа сохраняется здесь с помощью PyType_Ready().

Обычно это поле должно быть инициализировано значением NULL перед вызовом PyType_Ready; оно также может быть инициализировано словарём, содержащим начальные атрибуты типа. После того как PyType_Ready() инициализировал тип, в этот словарь можно добавлять дополнительные атрибуты только в том случае, если они не соответствуют перегруженным операциям (например, __add__()). После завершения инициализации типа это поле должно считаться доступным только для чтения.

Некоторые типы могут не хранить свой словарь в этом слоте. Используйте PyType_GetDict() для получения словаря для произвольного типа.

Изменено в версии 3.12: Детали реализации: для статических встроенных типов это всегда NULL. Вместо этого словарь для таких типов хранится в PyInterpreterState. Используйте PyType_GetDict() для получения словаря для произвольного типа.

Наследование:

Это поле не наследуется подтипами (хотя определённые здесь атрибуты наследуются через другой механизм).

По умолчанию:

Если это поле равно NULL, PyType_Ready() назначит ему новый словарь.

Предупреждение

Небезопасно использовать PyDict_SetItem() на или иным образом изменять tp_dict с помощью C-API словаря.

descrgetfunc PyTypeObject.tp_descr_get¶

Соответствующий идентификатор слота Py_tp_descr_get является частью Stable ABI.

Необязательный указатель на функцию «descriptor get».

Сигнатура функции:

PyObject * tp_descr_get(PyObject *self, PyObject *obj, PyObject *type);

Наследование:

Это поле наследуется подтипами.

descrsetfunc PyTypeObject.tp_descr_set¶

Соответствующий идентификатор слота Py_tp_descr_set является частью Stable ABI.

Необязательный указатель на функцию для установки и удаления значения дескриптора.

Сигнатура функции:

int tp_descr_set(PyObject *self, PyObject *obj, PyObject *value);

Аргумент value устанавливается в NULL для удаления значения.

Наследование:

Это поле наследуется подтипами.

Py_ssize_t PyTypeObject.tp_dictoffset¶

Хотя это поле всё ещё поддерживается, следует использовать Py_TPFLAGS_MANAGED_DICT вместо него, если это возможно.

Если экземпляры этого типа имеют словарь, содержащий переменные экземпляра, это поле не равно нулю и содержит смещение в структуре экземпляра для словаря переменных экземпляра; это смещение используется PyObject_GenericGetAttr().

Не путайте это поле с tp_dict; это словарь для атрибутов самого объекта типа.

Значение задаёт смещение словаря относительно начала структуры экземпляра.

tp_dictoffset следует рассматривать как доступный только для записи. Чтобы получить указатель на словарь, вызовите PyObject_GenericGetDict(). Вызов PyObject_GenericGetDict() может потребовать выделения памяти для словаря, поэтому может быть эффективнее вызвать PyObject_GetAttr() при доступе к атрибуту объекта.

Установка обоих битов Py_TPFLAGS_MANAGED_DICT и tp_dictoffset является ошибкой.

Наследование:

Это поле наследуется подтипами. Подтип не должен переопределять это смещение; это может быть небезопасно, если код C попытается получить доступ к словарю по предыдущему смещению. Для корректной поддержки наследования используйте Py_TPFLAGS_MANAGED_DICT.

По умолчанию:

Этот слот не имеет значения по умолчанию. Для статических типов, если поле равно NULL, то для экземпляров не создаётся __dict__.

Если в поле tp_flags установлен бит Py_TPFLAGS_MANAGED_DICT, то tp_dictoffset будет установлено в -1, чтобы указать, что использовать это поле небезопасно.

initproc PyTypeObject.tp_init¶

Соответствующий идентификатор слота Py_tp_init является частью Stable ABI.

Необязательный указатель на функцию инициализации экземпляра.

Эта функция соответствует методу __init__() классов. Как и __init__(), можно создать экземпляр без вызова __init__(), и можно переинициализировать экземпляр, вызвав его метод __init__() ещё раз.

Сигнатура функции:

int tp_init(PyObject *self, PyObject *args, PyObject *kwds);

Аргумент self – это инициализируемый экземпляр; аргументы args и kwds представляют позиционные и именованные аргументы вызова __init__().

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

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

Наследование:

Это поле наследуется подтипами.

По умолчанию:

Для статических типов это поле не имеет значения по умолчанию.

allocfunc PyTypeObject.tp_alloc¶

Соответствующий идентификатор слота Py_tp_alloc является частью Stable ABI.

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

Сигнатура функции:

PyObject *tp_alloc(PyTypeObject *self, Py_ssize_t nitems);

Наследование:

Статические подтипы наследуют этот слот, который будет PyType_GenericAlloc(), если унаследован от object.

Подтипы кучи не наследуют этот слот.

По умолчанию:

Для динамических подтипов это поле всегда установлено в PyType_GenericAlloc().

Для статических подтипов этот слот наследуется (см. выше).

newfunc PyTypeObject.tp_new¶

Соответствующий идентификатор слота Py_tp_new является частью Stable ABI.

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

Сигнатура функции:

PyObject *tp_new(PyTypeObject *subtype, PyObject *args, PyObject *kwds);

Аргумент subtype – это тип создаваемого объекта; аргументы args и kwds представляют позиционные и ключевые аргументы вызова типа. Обратите внимание, что subtype не обязан совпадать с типом, чья функция tp_new вызывается; это может быть подтип этого типа (но не произвольный тип).

Функция tp_new должна вызывать subtype->tp_alloc(subtype, nitems) для выделения памяти под объект, а затем выполнять лишь минимально необходимую инициализацию. Инициализацию, которую можно безопасно пропустить или повторить, следует помещать в обработчик tp_init. Хорошее эмпирическое правило: для неизменяемых типов вся инициализация должна выполняться в tp_new, а для изменяемых типов большую часть инициализации лучше отложить до tp_init.

Флаг Py_TPFLAGS_DISALLOW_INSTANTIATION используется для запрета создания экземпляров типа в Python.

Наследование:

Это поле наследуется подтипами, за исключением статических типов, у которых tp_base равно NULL или &PyBaseObject_Type.

По умолчанию:

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

freefunc PyTypeObject.tp_free¶

Соответствующий идентификатор слота Py_tp_free является частью Stable ABI.

Необязательный указатель на функцию освобождения экземпляра. Её сигнатура:

void tp_free(void *self);

Эта функция должна освобождать память, выделенную tp_alloc.

Наследование:

Статические подтипы наследуют этот слот, который будет равен PyObject_Free(), если унаследован от object. Исключение: если тип поддерживает сборку мусора (т.е. флаг Py_TPFLAGS_HAVE_GC установлен в tp_flags) и он бы унаследовал PyObject_Free(), то этот слот не наследуется, а по умолчанию принимает значение PyObject_GC_Del().

Подтипы кучи не наследуют этот слот.

По умолчанию:

Для подтипов кучи этот слот по умолчанию использует деаллокатор, подходящий под PyType_GenericAlloc() и значение флага Py_TPFLAGS_HAVE_GC.

Для статических подтипов этот слот наследуется (см. выше).

inquiry PyTypeObject.tp_is_gc¶

Соответствующий идентификатор слота Py_tp_is_gc является частью Stable ABI.

Необязательный указатель на функцию, вызываемую сборщиком мусора.

Сборщику мусора необходимо знать, можно ли собрать конкретный объект или нет. Обычно достаточно посмотреть на поле tp_flags типа объекта и проверить бит флага Py_TPFLAGS_HAVE_GC. Но некоторые типы содержат как статически, так и динамически выделенные экземпляры, и статически выделенные экземпляры не подлежат сборке. Такие типы должны определять эту функцию; она должна возвращать 1 для собираемого экземпляра и 0 для несобираемого. Сигнатура:

int tp_is_gc(PyObject *self);

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

Наследование:

Это поле наследуется подтипами.

По умолчанию:

У этого слота нет значения по умолчанию. Если это поле равно NULL, то в качестве функционального эквивалента используется Py_TPFLAGS_HAVE_GC.

PyObject *PyTypeObject.tp_bases¶

Соответствующий идентификатор слота Py_tp_bases является частью Stable ABI.

Кортеж базовых типов.

Это поле должно быть установлено в NULL и считаться доступным только для чтения. Python заполнит его, когда тип будет initialized.

Для динамически создаваемых классов вместо аргумента bases из PyType_FromSpecWithBases() можно использовать Py_tp_bases slot. Предпочтительна форма с аргументом.

Предупреждение

Множественное наследование плохо работает для статически определённых типов. Если установить tp_bases в кортеж, Python не вызовет ошибку, но некоторые слоты будут унаследованы только от первого базового класса.

Наследование:

Это поле не наследуется.

PyObject *PyTypeObject.tp_mro¶

Кортеж, содержащий расширенный набор базовых типов, начиная с самого типа и заканчивая object, в порядке разрешения методов (MRO).

Это поле должно быть установлено в NULL и считаться доступным только для чтения. Python заполнит его, когда тип будет initialized.

Наследование:

Это поле не наследуется; оно вычисляется заново с помощью PyType_Ready().

PyObject *PyTypeObject.tp_cache¶

Не используется. Только для внутреннего использования.

Наследование:

Это поле не наследуется.

void *PyTypeObject.tp_subclasses¶

Коллекция подклассов. Только для внутреннего использования. Может быть недопустимым указателем.

Чтобы получить список подклассов, вызовите метод Python __subclasses__().

Изменено в версии 3.12: Для некоторых типов это поле не содержит допустимый PyObject*. Тип был изменён на void*, чтобы указать на это.

Наследование:

Это поле не наследуется.

PyObject *PyTypeObject.tp_weaklist¶

Голова списка слабых ссылок для слабых ссылок на этот объект типа. Не наследуется. Только для внутреннего использования.

Изменено в версии 3.12: Деталь внутренней реализации: для статических встроенных типов это всегда NULL, даже если добавлены слабые ссылки. Вместо этого слабые ссылки для каждого хранятся в PyInterpreterState. Используйте публичный C-API или внутренний макрос _PyObject_GET_WEAKREFS_LISTPTR(), чтобы избежать этого различия.

Наследование:

Это поле не наследуется.

destructor PyTypeObject.tp_del¶

Соответствующий идентификатор слота Py_tp_del является частью Stable ABI.

Это поле устарело. Используйте tp_finalize вместо него.

unsigned int PyTypeObject.tp_version_tag¶

Используется для индексации кэша методов. Только для внутреннего использования.

Наследование:

Это поле не наследуется.

destructor PyTypeObject.tp_finalize¶

Соответствующий идентификатор слота Py_tp_finalize является частью Stable ABI начиная с версии 3.5.

Необязательный указатель на функцию финализации экземпляра. Это C-реализация специального метода __del__(). Его сигнатура:

void tp_finalize(PyObject *self);

Основная цель финализации – выполнить любую нетривиальную очистку, которая должна быть выполнена перед уничтожением объекта, пока объект и любые другие объекты, на которые он прямо или косвенно ссылается, всё ещё находятся в согласованном состоянии. Финализатору разрешено выполнять произвольный код Python.

Перед тем как Python автоматически финализирует объект, некоторые из его прямых или косвенных референтов могли уже быть автоматически финализированы. Однако ни один из референтов ещё не будет автоматически очищен (tp_clear).

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

Примечание

После того как Python автоматически финализирует объект, Python может начать автоматически очищать (tp_clear) объект и его референты (прямые и косвенные). Очищенные объекты не гарантированно находятся в согласованном состоянии; финализированный объект должен уметь переносить очищенные референты.

Примечание

Объект не гарантированно будет автоматически финализирован до вызова его деструктора (tp_dealloc). Рекомендуется вызывать PyObject_CallFinalizerFromDealloc() в начале tp_dealloc, чтобы гарантировать, что объект всегда финализируется перед уничтожением.

Примечание

Функцию tp_finalize можно вызывать из любого потока, хотя GIL будет удерживаться.

Примечание

Функцию tp_finalize можно вызывать во время завершения работы, после удаления некоторых глобальных переменных. Подробнее см. документацию метода __del__().

Когда Python финализирует объект, он ведёт себя как следующий алгоритм:

1. Python может пометить объект как финализированный. В настоящее время Python всегда помечает объекты, чей тип поддерживает сборку мусора (т.е. флаг Py_TPFLAGS_HAVE_GC установлен в tp_flags), и никогда не помечает объекты других типов; это может измениться в будущей версии.

2. Если объект не помечен как финализированный и его функция финализатора tp_finalize не равна NULL, то функция финализатора вызывается.

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

4. Если финализатор воскресил объект, ожидаемое уничтожение объекта отменяется, и пометка финализированный объекта может быть удалена, если она присутствует. В настоящее время Python никогда не удаляет пометку финализированный; это может измениться в будущей версии.

Автоматическая финализация относится к любой финализации, выполняемой Python, кроме случаев вызова PyObject_CallFinalizer() или PyObject_CallFinalizerFromDealloc(). Не даётся никаких гарантий относительно того, когда, если вообще, или как часто объект автоматически финализируется, за исключением:

• Python не будет автоматически финализировать объект, если он достижим, то есть на него есть ссылка и он не является членом циклического изолята.

• Python не будет автоматически финализировать объект, если финализация не пометит объект как финализированный. В настоящее время это относится к объектам, тип которых не поддерживает сборку мусора, то есть флаг Py_TPFLAGS_HAVE_GC не установлен. Такие объекты можно вручную финализировать, вызвав PyObject_CallFinalizer() или PyObject_CallFinalizerFromDealloc().

• Python не будет автоматически финализировать одновременно любые два члена циклического изолята.

• Python не будет автоматически финализировать объект после его автоматической очистки (tp_clear).

• Если объект является членом циклического изолята, Python не будет автоматически финализировать его после автоматической очистки (см. tp_clear) любого другого члена.

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

• Если Python собирается автоматически очистить объект (tp_clear), он сначала автоматически финализирует объект.

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

Чтобы финализировать объект вручную, не вызывайте эту функцию напрямую; вместо этого вызывайте PyObject_CallFinalizer() или PyObject_CallFinalizerFromDealloc().

tp_finalize должен оставлять текущее состояние исключения неизменным. Рекомендуемый способ написания нетривиального финализатора – сохранить исключение в начале, вызвав PyErr_GetRaisedException(), и восстановить исключение в конце, вызвав PyErr_SetRaisedException(). Если в середине финализатора возникло исключение, запишите его в журнал и очистите с помощью PyErr_WriteUnraisable() или PyErr_FormatUnraisable(). Например:

static void
foo_finalize(PyObject *self)
{
    // Сохранить текущее исключение, если оно есть.
    PyObject *exc = PyErr_GetRaisedException();

    // ...

    if (do_something_that_might_raise() != success_indicator) {
        PyErr_WriteUnraisable(self);
        goto done;
    }

done:
    // Восстановить сохраненное исключение. При этом молча отбрасывается любое исключение,
    // вызванное выше, поэтому обязательно вызовите PyErr_WriteUnraisable сначала, если
    // необходимо.
    PyErr_SetRaisedException(exc);
}

Наследование:

Это поле наследуется подтипами.

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

Изменено в версии 3.8: До версии 3.8 необходимо было установить бит флагов Py_TPFLAGS_HAVE_FINALIZE, чтобы это поле можно было использовать. Теперь это не требуется.

См. также

• PEP 442: «Безопасная финализация объектов»

• Жизненный цикл объекта для получения подробной информации о том, как этот слот соотносится с другими слотами.

• PyObject_CallFinalizer()

• PyObject_CallFinalizerFromDealloc()

vectorcallfunc PyTypeObject.tp_vectorcall¶

Соответствующий идентификатор слота Py_tp_vectorcall является частью стабильного ABI начиная с версии 3.14.

Функция vectorcall для вызова этого объекта типа (а не экземпляров). Другими словами, tp_vectorcall можно использовать для оптимизации type.__call__, которая обычно возвращает новый экземпляр типа.

Как и в случае с любой функцией vectorcall, если tp_vectorcall равно NULL, вместо него используется протокол tp_call (Py_TYPE(type)->tp_call).

Примечание

Протокол vectorcall требует, чтобы функция vectorcall имела то же поведение, что и соответствующая tp_call. Это означает, что type->tp_vectorcall должно соответствовать поведению Py_TYPE(type)->tp_call.

В частности, если type использует метакласс по умолчанию, type->tp_vectorcall должен вести себя так же, как PyType_Type->tp_call, который:

• вызывает type->tp_new,

• если результат является подклассом type, вызывает type->tp_init для результата tp_new, и

• возвращает результат tp_new.

Обычно tp_vectorcall переопределяется для оптимизации этого процесса для конкретных tp_new и tp_init. При выполнении этого для типов, допускающих создание подклассов пользователем, обратите внимание, что оба могут быть переопределены (с использованием __new__() и __init__() соответственно).

Наследование:

Это поле никогда не наследуется.

Добавлено в версии 3.9: (поле существует с версии 3.8, но используется только с версии 3.9)

unsigned char PyTypeObject.tp_watched¶

Внутреннее. Не использовать.

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

Статические типы¶Static Types

Традиционно типы, определяемые в коде C, являются статическими, то есть статическая структура PyTypeObject определяется непосредственно в коде и инициализируется с помощью PyType_Ready().

В результате получаются типы, которые ограничены по сравнению с типами, определёнными в Python.

• Статические типы ограничены одним базовым классом, то есть не могут использовать множественное наследование.

• Объекты статических типов (но не обязательно их экземпляры) неизменяемы. Из Python невозможно добавить или изменить атрибуты объекта типа.

• Объекты статических типов разделяются между под-интерпретаторами, поэтому они не должны содержать состояние, специфичное для под-интерпретатора.

Кроме того, поскольку PyTypeObject является лишь частью Limited API в виде непрозрачной структуры, любые модули расширения, использующие статические типы, должны быть скомпилированы для конкретной минорной версии Python.

Кучные типы¶Heap Types

Альтернативой статическим типам являются кучные типы (heap-allocated types), или кучные типы (heap types) для краткости. Они очень похожи на классы, создаваемые с помощью оператора class. У кучных типов установлен флаг Py_TPFLAGS_HEAPTYPE.

Для этого заполняется структура PyType_Spec и вызывается PyType_FromSpec(), PyType_FromSpecWithBases(), PyType_FromModuleAndSpec() или PyType_FromMetaclass().

Структуры числовых объектов¶Number Object Structures

type PyNumberMethods¶

Эта структура содержит указатели на функции, которые объект использует для реализации числового протокола. Каждая функция используется одноимённой функцией, описанной в разделе Числовой протокол.

Вот определение структуры:

typedef struct {
     binaryfunc nb_add;
     binaryfunc nb_subtract;
     binaryfunc nb_multiply;
     binaryfunc nb_remainder;
     binaryfunc nb_divmod;
     ternaryfunc nb_power;
     unaryfunc nb_negative;
     unaryfunc nb_positive;
     unaryfunc nb_absolute;
     inquiry nb_bool;
     unaryfunc nb_invert;
     binaryfunc nb_lshift;
     binaryfunc nb_rshift;
     binaryfunc nb_and;
     binaryfunc nb_xor;
     binaryfunc nb_or;
     unaryfunc nb_int;
     void *nb_reserved;
     unaryfunc nb_float;

     binaryfunc nb_inplace_add;
     binaryfunc nb_inplace_subtract;
     binaryfunc nb_inplace_multiply;
     binaryfunc nb_inplace_remainder;
     ternaryfunc nb_inplace_power;
     binaryfunc nb_inplace_lshift;
     binaryfunc nb_inplace_rshift;
     binaryfunc nb_inplace_and;
     binaryfunc nb_inplace_xor;
     binaryfunc nb_inplace_or;

     binaryfunc nb_floor_divide;
     binaryfunc nb_true_divide;
     binaryfunc nb_inplace_floor_divide;
     binaryfunc nb_inplace_true_divide;

     unaryfunc nb_index;

     binaryfunc nb_matrix_multiply;
     binaryfunc nb_inplace_matrix_multiply;
} PyNumberMethods;

Примечание

Бинарные и тернарные функции должны проверять тип всех своих операндов и выполнять необходимые преобразования (хотя бы один из операндов должен быть экземпляром определяемого типа). Если операция не определена для данных операндов, бинарные и тернарные функции должны вернуть Py_NotImplemented; если произошла другая ошибка, они должны вернуть NULL и установить исключение.

Примечание

Поле nb_reserved всегда должно быть NULL. Ранее оно называлось nb_long и было переименовано в Python 3.0.1.

binaryfunc PyNumberMethods.nb_add¶

Соответствующий идентификатор слота Py_nb_add является частью Stable ABI.

binaryfunc PyNumberMethods.nb_subtract¶

Соответствующий идентификатор слота Py_nb_subtract является частью Stable ABI.

binaryfunc PyNumberMethods.nb_multiply¶

Соответствующий идентификатор слота Py_nb_multiply является частью Stable ABI.

binaryfunc PyNumberMethods.nb_remainder¶

Соответствующий идентификатор слота Py_nb_remainder является частью Stable ABI.

binaryfunc PyNumberMethods.nb_divmod¶

Соответствующий идентификатор слота Py_nb_divmod является частью Stable ABI.

ternaryfunc PyNumberMethods.nb_power¶

Соответствующий идентификатор слота Py_nb_power является частью Stable ABI.

unaryfunc PyNumberMethods.nb_negative¶

Соответствующий идентификатор слота Py_nb_negative является частью Stable ABI.

unaryfunc PyNumberMethods.nb_positive¶

Соответствующий идентификатор слота Py_nb_positive является частью Stable ABI.