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

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

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

int Py_Is(const PyObject *x, const PyObject *y)

Часть Стабильной ABI с версии 3.10.

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

Новое в версии 3.10.

int Py_IsNone(const PyObject *x)

Часть Стабильной ABI с версии 3.10.

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

Новое в версии 3.10.

int Py_IsTrue(const PyObject *x)

Часть Стабильной ABI с версии 3.10.

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

Новое в версии 3.10.

int Py_IsFalse(const PyObject *x)

Часть Стабильной ABI с версии 3.10.

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

Новое в версии 3.10.

PyTypeObject *Py_TYPE(const PyObject *o)

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

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

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

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(const PyObject *o)

Получить счетчик ссылок объекта Python o.

Изменено в версии 3.10: Py_REFCNT() изменено на встроенную статическую функцию. Используйте Py_SET_REFCNT() для установки счетчика ссылок объекта.

void Py_SET_REFCNT(PyObject *o, Py_ssize_t refcnt)

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

Новое в версии 3.9.

Py_ssize_t Py_SIZE(const PyVarObject *o)

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

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

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

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 оптимизированы больше, чем вызовы объектов обёртки.

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

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 с установленной ошибкой при неудаче.