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

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

Все объекты 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

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