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

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

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

type PyObject¶

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

Все типы объектов являются расширениями этого типа. Это тип, который содержит информацию, необходимую Python для обработки указателя на объект как объекта. В обычной сборке «release» он содержит только счетчик ссылок объекта и указатель на соответствующий объект типа. Ничто на самом деле не объявляется как 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(const PyObject *x, const PyObject *y)¶

Часть Stable ABI начиная с версии 3.10.

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

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

int Py_IsNone(const PyObject *x)¶

Часть Stable ABI начиная с версии 3.10.

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

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

int Py_IsTrue(const PyObject *x)¶

Часть Stable ABI начиная с версии 3.10.

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

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

int Py_IsFalse(const PyObject *x)¶

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

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

Доступ к атрибутам типов расширений¶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 *	необязательный указатель на функцию, предоставляющий дополнительные данные для геттера и сеттера

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

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

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

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

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

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