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

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

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

type PyObject

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

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

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

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