Содержание страницы

Структуры общих объектов¶Common Object Structures

При определении типов объектов Python используется большое количество структур. В данном разделе описываются эти структуры и принципы их использования.

Базовые типы объектов и макросы¶Base object types and macros

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

type PyObject¶: Часть Limited API. (Только некоторые члены являются частью стабильного ABI.)
Все типы объектов являются расширениями этого типа. Это тип, который содержит информацию, необходимую Python для обработки указателя на объект как объекта. В обычной «релизной» сборке он содержит только счетчик ссылок объекта и указатель на соответствующий объект типа. Ничто не объявлено как PyObject, но любой указатель на объект Python может быть приведен к PyObject*. Доступ к членам должен осуществляться с помощью макросов Py_REFCNT и Py_TYPE.

type PyVarObject¶: Часть Limited 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)¶: Часть Stable ABI начиная с версии 3.10.
Проверяет, является ли объект x тем же объектом, что и y, аналогично x is y в Python.

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

int Py_IsNone(PyObject *x)¶: Часть Stable ABI начиная с версии 3.10.
Проверяет, является ли объект синглтоном None, аналогично x is None в Python.

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

int Py_IsTrue(PyObject *x)¶: Часть Stable ABI начиная с версии 3.10.
Проверяет, является ли объект синглтоном True, аналогично x is True в Python.

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

int Py_IsFalse(PyObject *x)¶: Часть Stable 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,

Реализация функций и методов¶Implementing functions and methods

type PyCFunction¶

Часть Stable ABI.

Тип функций, используемых для реализации большинства вызываемых объектов Python на C. Функции этого типа принимают два параметра PyObject* и возвращают одно такое значение. Если возвращаемое значение равно NULL, должно быть установлено исключение. Если не NULL, возвращаемое значение интерпретируется как возвращаемое значение функции, доступной в Python. Функция должна возвращать новую ссылку.

Сигнатура функции:

PyObject *PyCFunction(PyObject *self,
                      PyObject *args);

type PyCFunctionWithKeywords¶

Часть Stable 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¶

Часть Stable ABI (включая все члены).

Структура, используемая для описания метода типа-расширения. Эта структура имеет четыре поля:

const char *ml_name¶: Имя метода.

PyCFunction ml_meth¶: Указатель на реализацию на C.

int ml_flags¶: Битовые флаги, указывающие, как должен быть построен вызов.

const char *ml_doc¶: Указывает на содержимое строки документации.

ml_meth – это указатель на функцию C. Функции могут быть разных tипов, но они всегда возвращают 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 будет загружен вместо объекта-обёртки и будет сосуществовать со слотом. Это полезно, поскольку вызовы PyCFunctions оптимизированы лучше, чем вызовы объектов-обёрток.

PyObject *PyCMethod_New(PyMethodDef *ml, PyObject *self, PyObject *module, PyTypeObject *cls)¶

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

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

Параметр self будет передан как аргумент self в C-функцию из ml->ml_meth при вызове. self может быть NULL.

Атрибут __module__ объекта callable можно задать из аргумента 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)¶: Возвращаемое значение: новая ссылка. Часть Stable ABI.
Эквивалентно PyCMethod_New(ml, self, module, NULL).

PyObject *PyCFunction_New(PyMethodDef *ml, PyObject *self)¶: Возвращаемое значение: новая ссылка. Часть Stable ABI с версии 3.4.
Эквивалентно PyCMethod_New(ml, self, NULL, NULL).

Доступ к атрибутам типов расширений¶Accessing attributes of extension types

type PyMemberDef¶

Часть Stable 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).

Heap allocated types (created using PyType_FromSpec() or similar), PyMemberDef may contain definitions for the special members __dictoffset__, __weaklistoffset__ and __vectorcalloffset__, corresponding to tp_dictoffset, tp_weaklistoffset and tp_vectorcall_offset in type objects. These must be defined with T_PYSSIZET and READONLY, for example:

static PyMemberDef spam_type_members[] = {
    {"__dictoffset__", T_PYSSIZET, offsetof(Spam_object, dict), READONLY},
    {NULL}  /* Страж */
};

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¶

Часть Stable ABI (включая все члены).

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

Поле	Тип C	Значение
имя	const char *	имя атрибута
get	getter	C-функция для получения атрибута
множество	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 с установленным исключением в случае неудачи.