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

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

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

type PyObject

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

Все типы объектов являются расширениями этого типа. Это тип, содержащий информацию, необходимую Python для обработки указателя на объект как объекта. В обычном «выпуске» он содержит только счётчик ссылок объекта и указатель на соответствующий объект типа. Ничего фактически не объявляется как 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

Часть Стабильного 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

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

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

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

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

См. также

function.__module__

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

Добавлен в версии 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-структуры. При определении класса поместите массив из этих структур с нулевым завершением в слот 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, например:

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