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

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

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

type PyObject

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

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

type PyVarObject

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

Это расширение типа PyObject, добавляющее поле ob_size. Оно используется только для объектов, имеющих понятие длины. Этот тип нечасто встречается в Python/C API. Доступ к членам следует осуществлять с помощью макросов Py_REFCNT, Py_TYPE и Py_SIZE.

PyObject_HEAD

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

PyObject ob_base;

См. описание PyObject выше.

PyObject_VAR_HEAD

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

PyVarObject ob_base;

См. описание PyVarObject выше.

int Py_Is(PyObject *x, PyObject *y)

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

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

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

int Py_IsNone(PyObject *x)

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

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

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

int Py_IsTrue(PyObject *x)

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

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

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

int Py_IsFalse(PyObject *x)

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

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

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

PyTypeObject *Py_TYPE(PyObject *o)

Получает тип объекта Python o.

Возвращает заимствованную ссылку.

Чтобы задать тип объекта, используйте функцию Py_SET_TYPE().

Изменено в версии 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.

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

Py_ssize_t Py_SIZE(PyVarObject *o)

Получает размер объекта Python o.

Чтобы задать размер объекта, используйте функцию Py_SET_SIZE().

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

void Py_SET_SIZE(PyVarObject *o, Py_ssize_t 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

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

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

type _PyCFunctionFastWithKeywords

Тип функций, используемых для реализации вызываемых объектов 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

Это стандартное соглашение о вызове, при котором методы имеют тип 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

Быстрое соглашение о вызове, поддерживающее только позиционные аргументы. Методы имеют тип _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

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

METH_METHOD | METH_FASTCALL | METH_KEYWORDS

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

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

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

METH_NOARGS

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

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

METH_O

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

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

METH_CLASS

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

METH_STATIC

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

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

METH_COEXIST

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

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

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

Преобразует ml в вызываемый объект Python callable. Вызывающий код должен обеспечить, чтобы ml существовал дольше, чем вызываемый объект callable. Обычно 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.

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).

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

type PyMemberDef

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

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

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

const char *name

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

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

int type

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

Py_ssize_t offset

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

int flags

Один или несколько флагов членов, объединённых побитовой операцией OR.

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, например:

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".

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".