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

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

Все объекты 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; в 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_REFCNT(PyObject *o)

Возвращает счётчик ссылок объекта Python o.

Для установки счётчика ссылок объекта используйте функцию Py_SET_REFCNT().

Изменено в версии 3.11: Тип параметра больше не является const PyObject*.

Изменено в версии 3.10: Py_REFCNT() преобразована во встроенную статическую функцию.

void Py_SET_REFCNT(PyObject *o, Py_ssize_t refcnt)

Устанавливает счётчик ссылок объекта o в значение refcnt.

Новое в версии 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 вызываемого объекта. Вызывающий код должен обеспечить, чтобы 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. Её поля:

Поле	Тип C	Значение
name	const char *	имя члена
type	int	тип члена в структуре C
offset	Py_ssize_t	смещение в байтах, по которому член расположен в структуре объекта типа
flags	int	биты флагов, указывающие, должно ли поле быть доступно только для чтения или для записи
doc	const char *	указывает на содержимое строки документации

type может быть одним из множества макросов T_, соответствующих различным типам C. При обращении к члену из Python он будет преобразован в эквивалентный тип Python.

Имя макроса	Тип C
T_SHORT	short
T_INT	int
T_LONG	long
T_FLOAT	float
T_DOUBLE	double
T_STRING	const char *
T_OBJECT	PyObject *
T_OBJECT_EX	PyObject *
T_CHAR	char
T_BYTE	char
T_UBYTE	unsigned char
T_UINT	unsigned int
T_USHORT	unsigned short
T_ULONG	unsigned long
T_BOOL	char
T_LONGLONG	long long
T_ULONGLONG	unsigned long long
T_PYSSIZET	Py_ssize_t

T_OBJECT и T_OBJECT_EX различаются тем, что T_OBJECT возвращает None, если член NULL, а T_OBJECT_EX вызывает AttributeError. Старайтесь использовать T_OBJECT_EX вместо T_OBJECT, так как T_OBJECT_EX корректнее обрабатывает применение оператора del к этому атрибуту, чем T_OBJECT.

flags может иметь значение 0 для доступа на чтение и запись или READONLY для доступа только на чтение. Использование T_STRING для type подразумевает READONLY. Данные T_STRING интерпретируются как UTF-8. Удалять можно только члены T_OBJECT и T_OBJECT_EX. (Им присваивается значение NULL).

Типы, размещённые в куче (созданные с помощью PyType_FromSpec() или аналогичного средства), PyMemberDef могут содержать определения специальных членов __dictoffset__, __weaklistoffset__ и __vectorcalloffset__, соответствующих tp_dictoffset, tp_weaklistoffset и tp_vectorcall_offset в объектах типов. Их необходимо определять с помощью T_PYSSIZET и READONLY, например:

static PyMemberDef spam_type_members[] = {
    {"__dictoffset__", T_PYSSIZET, offsetof(Spam_object, dict), READONLY},
    {NULL}  /* Sentinel */
};

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

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

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

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

type PyGetSetDef

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

Структура для определения доступа к типу в стиле свойств. См. также описание слота PyTypeObject.tp_getset.

Поле	Тип C	Значение
name	const char *	имя атрибута
get	getter	функция C для получения атрибута
set	setter	необязательная функция C для задания или удаления атрибута; если она не указана, атрибут доступен только для чтения
doc	const char *	необязательная строка документации
closure	void *	необязательный указатель на пользовательские данные, предоставляющий дополнительные данные для getter и setter

Функция get принимает один параметр типа PyObject* (экземпляр) и указатель на пользовательские данные (соответствующий closure):

typedef PyObject *(*getter)(PyObject *, void *);

В случае успеха она должна возвращать новую ссылку, а в случае ошибки — NULL с установленным исключением.

Функции set принимают два параметра типа PyObject* (экземпляр и задаваемое значение) и указатель на пользовательские данные (соответствующий closure):

typedef int (*setter)(PyObject *, PyObject *, void *);

Если атрибут нужно удалить, второй параметр равен NULL. В случае успеха функция должна возвращать 0, а в случае ошибки — -1 с установленным исключением.