Общие структуры объектов

Базовые типы объектов и макросы

В начале представления в памяти все объекты Python имеют небольшое количество общих полей. Они представлены типами PyObject и PyVarObject, которые, в свою очередь, определяются раскрытием некоторых макросов, используемых прямо или косвенно при определении всех остальных объектов Python. Дополнительные макросы см. в разделе подсчёт ссылок.

type PyObject

Часть Ограниченного API. (Только некоторые члены входят в стабильный ABI.)

Все типы объектов являются расширениями этого типа. Этот тип содержит информацию, необходимую Python, чтобы рассматривать указатель на объект как объект. В обычной сборке «release» он содержит только счётчик ссылок объекта и указатель на соответствующий объект типа. Ничто фактически не объявляется как PyObject, но любой указатель на объект Python можно привести к типу PyObject*.

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

Py_ssize_t ob_refcnt

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

Счётчик ссылок объекта, возвращаемый Py_REFCNT. Не используйте это поле напрямую; вместо этого используйте функции и макросы, такие как Py_REFCNT, Py_INCREF() и Py_DecRef().

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

PyTypeObject *ob_type

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

Тип объекта. Не используйте это поле напрямую; вместо этого используйте Py_TYPE и Py_SET_TYPE().

type PyVarObject

Часть Ограниченного API. (Только некоторые члены входят в стабильный ABI.)

Расширение PyObject, добавляющее поле ob_size. Этот тип предназначен для объектов, имеющих понятие длины.

Как и в случае с PyObject, нельзя обращаться к членам напрямую; вместо этого используйте макросы, такие как Py_SIZE, Py_REFCNT и Py_TYPE.

Py_ssize_t ob_size

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

Поле размера, содержимое которого следует считать внутренней деталью реализации объекта.

Не используйте это поле напрямую; вместо этого используйте Py_SIZE.

Функции создания объектов, такие как PyObject_NewVar(), обычно устанавливают в этом поле запрошенный размер (количество элементов). После создания произвольные значения можно записать в ob_size с помощью Py_SET_SIZE.

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

PyObject_HEAD

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

PyObject ob_base;

См. приведённую выше документацию для PyObject.

PyObject_VAR_HEAD

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

PyVarObject ob_base;

См. приведённую выше документацию для PyVarObject.

PyTypeObject PyBaseObject_Type

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

Базовый класс всех остальных объектов, соответствующий object в Python.

int Py_Is(PyObject *x, PyObject *y)

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

Проверяет, является ли объект x тем же объектом, что и y; в Python этому соответствует x is y.

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

int Py_IsNone(PyObject *x)

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

Проверяет, является ли объект синглтоном None; в Python этому соответствует x is None.

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

int Py_IsTrue(PyObject *x)

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

Проверяет, является ли объект синглтоном True; в Python этому соответствует x is True.

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

int Py_IsFalse(PyObject *x)

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

Проверяет, является ли объект синглтоном False; в Python этому соответствует x is False.

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

PyTypeObject *Py_TYPE(PyObject *o)

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

Возвращает тип объекта Python o.

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

Изменено в версии 3.11: Py_TYPE() преобразована во встроенную статическую функцию. Тип параметра больше не является const PyObject*.

int Py_IS_TYPE(PyObject *o, PyTypeObject *type)

Возвращает ненулевое значение, если тип объекта o — type. В противном случае возвращает ноль. Эквивалентно: Py_TYPE(o) == type.

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

void Py_SET_TYPE(PyObject *o, PyTypeObject *type)

Устанавливает тип объекта o в type без каких-либо проверок и изменения счётчика ссылок.

Это низкоуровневая операция. Вместо неё рассмотрите возможность установить атрибут Python __class__ с помощью PyObject_SetAttrString() или аналогичного средства.

Учтите, что присваивание несовместимого типа может привести к неопределённому поведению.

Если type — это тип в куче, вызывающий код должен создать на него новую ссылку. Аналогично, если старый тип o является типом в куче, вызывающий код должен освободить ссылку на этот тип.

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

Py_ssize_t Py_SIZE(PyVarObject *o)

Возвращает поле ob_size объекта o.

Изменено в версии 3.11: Py_SIZE() преобразована во встроенную статическую функцию. Тип параметра больше не является const PyVarObject*.

void Py_SET_SIZE(PyVarObject *o, Py_ssize_t size)

Устанавливает поле ob_size объекта o в значение size.

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

PyObject_HEAD_INIT(type)

Этот макрос раскрывается в значения инициализации для нового типа PyObject. Макрос раскрывается в:

_PyObject_EXTRA_INIT
1, type,

PyVarObject_HEAD_INIT(type, size)

Этот макрос раскрывается в значения инициализации для нового типа PyVarObject, включая поле ob_size. Макрос раскрывается в:

_PyObject_EXTRA_INIT
1, type, size,

Реализация функций и методов

type PyCFunction

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

Тип функций, используемых для реализации большинства вызываемых объектов Python на C. Функции этого типа принимают два параметра PyObject* и возвращают одно значение такого типа. Если возвращаемое значение равно NULL, должно быть установлено исключение. Если нет NULL, возвращаемое значение интерпретируется как результат функции, представленной в Python. Функция должна возвращать новую ссылку.

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

PyObject *PyCFunction(PyObject *self,
                      PyObject *args);

type PyCFunctionWithKeywords

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

Тип функций, используемых для реализации вызываемых объектов Python на C с сигнатурой METH_VARARGS | METH_KEYWORDS. Сигнатура функции:

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

type PyCFunctionFast

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

Тип функций, используемых для реализации вызываемых объектов Python на C с сигнатурой METH_FASTCALL. Сигнатура функции:

PyObject *PyCFunctionFast(PyObject *self,
                          PyObject *const *args,
                          Py_ssize_t nargs);

type PyCFunctionFastWithKeywords

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

Тип функций, используемых для реализации вызываемых объектов Python на C с сигнатурой METH_FASTCALL | METH_KEYWORDS. Сигнатура функции:

PyObject *PyCFunctionFastWithKeywords(PyObject *self,
                                      PyObject *const *args,
                                      Py_ssize_t nargs,
                                      PyObject *kwnames);

type PyCMethod

Тип функций, используемых для реализации вызываемых объектов Python на C с сигнатурой METH_METHOD | METH_FASTCALL | METH_KEYWORDS. Сигнатура функции:

PyObject *PyCMethod(PyObject *self,
                    PyTypeObject *defining_class,
                    PyObject *const *args,
                    Py_ssize_t nargs,
                    PyObject *kwnames)

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

type PyMethodDef

Часть стабильного ABI (включая все члены структуры).

Структура, используемая для описания метода типа расширения. Эта структура содержит четыре поля:

const char *ml_name

Имя метода.

PyCFunction ml_meth

Указатель на реализацию на C.

int ml_flags

Биты флагов, указывающие, как следует сформировать вызов.

const char *ml_doc

Указывает на содержимое строки документации.

ml_meth — это указатель на функцию C. Функции могут иметь разные типы, но всегда возвращают PyObject*. Если функция не имеет тип PyCFunction, компилятору потребуется приведение типа в таблице методов. Хотя PyCFunction определяет первый параметр как PyObject*, реализация метода часто использует конкретный тип C объекта self.

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

Доступны следующие соглашения о вызове:

METH_VARARGS

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

Это типичное соглашение о вызове, при котором методы имеют тип PyCFunction. Функция ожидает два значения PyObject*. Первое — объект self для методов; для функций модуля это объект модуля. Второй параметр (часто называемый args) — объект-кортеж, представляющий все аргументы. Обычно этот параметр обрабатывается с помощью PyArg_ParseTuple() или PyArg_UnpackTuple().

METH_KEYWORDS

Можно использовать только в определённых сочетаниях с другими флагами: METH_VARARGS | METH_KEYWORDS, METH_FASTCALL | METH_KEYWORDS и METH_METHOD | METH_FASTCALL | METH_KEYWORDS.

METH_VARARGS | METH_KEYWORDS

Методы с этими флагами должны иметь тип PyCFunctionWithKeywords. Функция ожидает три параметра: self, args, kwargs, где kwargs — словарь всех именованных аргументов либо NULL, если именованных аргументов нет. Обычно параметры обрабатываются с помощью PyArg_ParseTupleAndKeywords().

METH_FASTCALL

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

Быстрое соглашение о вызове, поддерживающее только позиционные аргументы. Методы имеют тип PyCFunctionFast. Первый параметр — self, второй параметр — массив C значений PyObject*, представляющих аргументы, а третий параметр — количество аргументов (длина массива).

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

Изменено в версии 3.10: METH_FASTCALL теперь является частью стабильного ABI.

METH_FASTCALL | METH_KEYWORDS

Расширение METH_FASTCALL, которое также поддерживает именованные аргументы; используется с методами типа PyCFunctionFastWithKeywords. Именованные аргументы передаются так же, как в протоколе vectorcall: имеется дополнительный четвёртый параметр PyObject* — кортеж, представляющий имена именованных аргументов (которые гарантированно являются строками), либо NULL, если именованных аргументов нет. Значения именованных аргументов хранятся в массиве args после позиционных аргументов.

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

METH_METHOD

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

Можно использовать только в сочетании с другими флагами: METH_METHOD | METH_FASTCALL | METH_KEYWORDS.

METH_METHOD | METH_FASTCALL | METH_KEYWORDS

Расширение METH_FASTCALL | METH_KEYWORDS, поддерживающее определяющий класс, то есть класс, содержащий рассматриваемый метод. Определяющий класс может быть суперклассом Py_TYPE(self).

Метод должен иметь тип PyCMethod, как и в случае METH_FASTCALL | METH_KEYWORDS, с добавлением аргумента defining_class после self.

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

METH_NOARGS

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

Методам без параметров не нужно проверять, переданы ли аргументы, если они перечислены с флагом METH_NOARGS. Они должны иметь тип PyCFunction. Первый параметр обычно называется self и содержит ссылку на модуль или экземпляр объекта. Во всех случаях вторым параметром будет NULL.

Функция должна иметь 2 параметра. Поскольку второй параметр не используется, можно применить Py_UNUSED, чтобы предотвратить предупреждение компилятора.

METH_O

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

Методы с одним объектным аргументом можно перечислить с флагом METH_O вместо вызова PyArg_ParseTuple() с аргументом "O". Они имеют тип PyCFunction, с параметром self и параметром PyObject*, представляющим единственный аргумент.

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

METH_CLASS

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

В качестве первого параметра методу будет передан объект типа, а не экземпляр типа. Это используется для создания методов класса, аналогичных создаваемым встроенным декоратором @classmethod.

METH_STATIC

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

В качестве первого параметра методу будет передан NULL, а не экземпляр типа. Это используется для создания статических методов, аналогичных создаваемым встроенным декоратором @staticmethod.

Ещё одна константа управляет тем, загружается ли метод вместо другого определения с тем же именем.

METH_COEXIST

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

Метод будет загружен вместо существующих определений. Без METH_COEXIST по умолчанию повторные определения пропускаются. Поскольку обёртки слотов загружаются до таблицы методов, наличие, например, слота sq_contains создаст обёрнутый метод с именем __contains__() и не позволит загрузить соответствующий PyCFunction с тем же именем. Если флаг установлен, PyCFunction будет загружен вместо объекта-обёртки и будет сосуществовать со слотом. Это полезно, поскольку вызовы PyCFunction оптимизированы лучше, чем вызовы объектов-обёрток.

PyTypeObject PyCMethod_Type

Объект типа, соответствующий объектам методов Python на C. На уровне Python он доступен как types.BuiltinMethodType.

int PyCMethod_Check(PyObject *op)

Возвращает true, если op является экземпляром типа PyCMethod_Type или его подтипа. Эта функция всегда завершается успешно.

int PyCMethod_CheckExact(PyObject *op)

То же, что и PyCMethod_Check(), но без учёта подтипов.

PyObject *PyCMethod_New(PyMethodDef *ml, PyObject *self, PyObject *module, PyTypeObject *cls)

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

Преобразует ml в вызываемый объект Python callable. Вызывающий код должен обеспечить, чтобы ml существовал дольше, чем вызываемый объект. Обычно ml определяется как статическая переменная.

При вызове параметр self будет передан как аргумент self функции C в ml->ml_meth. Значение self может быть NULL.

Атрибут __module__ вызываемого объекта callable можно задать с помощью переданного аргумента module. module должен быть строкой Python, которая будет использоваться как имя модуля, в котором определена функция. Если это значение недоступно, ему можно присвоить None или NULL.

См. также

function.__module__

Параметр cls будет передан функции C как аргумент defining_class. Он должен быть задан, если для ml->ml_flags установлен флаг METH_METHOD.

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

PyTypeObject PyCFunction_Type

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

Объект типа, соответствующий объектам функций Python на C. На уровне Python он доступен как types.BuiltinFunctionType.

int PyCFunction_Check(PyObject *op)

Возвращает true, если op является экземпляром типа PyCFunction_Type или его подтипа. Эта функция всегда завершается успешно.

int PyCFunction_CheckExact(PyObject *op)

То же, что и PyCFunction_Check(), но без учёта подтипов.

PyObject *PyCFunction_NewEx(PyMethodDef *ml, PyObject *self, PyObject *module)

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

Эквивалентно PyCMethod_New(ml, self, module, NULL).

PyObject *PyCFunction_New(PyMethodDef *ml, PyObject *self)

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

Эквивалентно PyCMethod_New(ml, self, NULL, NULL).

int PyCFunction_GetFlags(PyObject *func)

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

Получает флаги функции func в том виде, в каком они были переданы в ml_flags.

Если func не является объектом функции C, возникает исключение. func не должен быть NULL.

При успешном выполнении функция возвращает флаги функции, а при ошибке — -1 с установленным исключением.

int PyCFunction_GET_FLAGS(PyObject *func)

То же, что и PyCFunction_GetFlags(), но без проверки ошибок и типа.

PyCFunction PyCFunction_GetFunction(PyObject *func)

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

Получает указатель на функцию для func в том виде, в каком он был передан в ml_meth.

Если func не является объектом функции C, возникает исключение. func не должен быть NULL.

При успешном выполнении функция возвращает указатель на функцию, а при ошибке — NULL с установленным исключением.

int PyCFunction_GET_FUNCTION(PyObject *func)

То же, что и PyCFunction_GetFunction(), но без проверки ошибок и типа.

PyObject *PyCFunction_GetSelf(PyObject *func)

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

Получает объект «self» для func. Это объект, который был бы передан первым аргументом функции типа PyCFunction. Для объектов функций C, созданных через PyMethodDef в PyModuleDef, это результирующий объект модуля.

Если func не является объектом функции C, возникает исключение. func не должен быть NULL.

При успешном выполнении эта функция возвращает заимствованную ссылку на объект «self», а при ошибке — NULL с установленным исключением.

PyObject *PyCFunction_GET_SELF(PyObject *func)

То же, что и PyCFunction_GetSelf(), но без проверки ошибок и типа.

Доступ к атрибутам типов расширений

type PyMemberDef

Часть стабильного ABI (включая все элементы).

Структура, описывающая атрибут типа, соответствующий члену структуры C. При определении класса поместите массив таких структур, завершённый NULL, в слот tp_members.

Её поля перечислены по порядку:

const char *name

Имя члена. Значение NULL обозначает конец массива PyMemberDef[].

Строка должна быть статической; её копия не создаётся.

int type

Тип члена в структуре C. Возможные значения см. в разделе Типы членов.

Py_ssize_t offset

Смещение в байтах, по которому член находится в структуре объекта типа.

int flags

Ноль или несколько флагов членов, объединённых побитовым ИЛИ.

const char *doc

Строка документации или NULL. Строка должна быть статической; её копия не создаётся. Обычно она задаётся с помощью PyDoc_STR.

По умолчанию (если flags равен 0) члены допускают чтение и запись. Для доступа только на чтение используйте флаг Py_READONLY. Некоторые типы, например Py_T_STRING, подразумевают Py_READONLY. Удалять можно только члены Py_T_OBJECT_EX (и устаревшие T_OBJECT).

Для типов, выделяемых в куче (созданных с помощью PyType_FromSpec() или аналогичного средства), PyMemberDef может содержать определение специального члена "__vectorcalloffset__", соответствующего tp_vectorcall_offset в объектах типов. Этот член необходимо определить с помощью Py_T_PYSSIZET и либо Py_READONLY, либо Py_READONLY | Py_RELATIVE_OFFSET. Например:

static PyMemberDef spam_type_members[] = {
    {"__vectorcalloffset__", Py_T_PYSSIZET,
     offsetof(Spam_object, vectorcall), Py_READONLY},
    {NULL}  /* Sentinel */
};

(Возможно, потребуется #include <stddef.h> для offsetof().)

Устаревшие смещения tp_dictoffset и tp_weaklistoffset можно определить аналогичным образом с помощью членов "__dictoffset__" и "__weaklistoffset__", однако настоятельно рекомендуется вместо этого использовать расширения Py_TPFLAGS_MANAGED_DICT и Py_TPFLAGS_MANAGED_WEAKREF.

Изменено в версии 3.12: PyMemberDef теперь доступен всегда. Ранее для его использования требовалось включить "structmember.h".

Изменено в версии 3.14: Py_RELATIVE_OFFSET теперь допускается для "__vectorcalloffset__", "__dictoffset__" и "__weaklistoffset__".

PyObject *PyMember_GetOne(const char *obj_addr, struct PyMemberDef *m)

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

Получает атрибут объекта по адресу obj_addr. Атрибут описывается PyMemberDef m. В случае ошибки возвращает NULL.

Изменено в версии 3.12: PyMember_GetOne теперь доступен всегда. Ранее для его использования требовалось включить "structmember.h".

int PyMember_SetOne(char *obj_addr, struct PyMemberDef *m, PyObject *o)

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

Устанавливает атрибут объекта по адресу obj_addr в значение объекта o. Устанавливаемый атрибут описывается PyMemberDef m. В случае успеха возвращает 0, а в случае ошибки — отрицательное значение.

Изменено в версии 3.12: PyMember_SetOne теперь доступен всегда. Ранее для его использования требовалось включить "structmember.h".