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

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

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

type PyObject

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

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

type PyVarObject

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

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

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)

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

Получает тип объекта 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 будет передан функции 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".