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

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

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

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

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

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

PyVarObject¶: Это расширение 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 выше.

Py_TYPE(o)¶

Этот макрос используется для доступа к полю ob_type объекта Python. Он раскрывается в:

(((PyObject*)(o))->ob_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_REFCNT(o)¶

Этот макрос используется для доступа к полю ob_refcnt объекта Python. Он раскрывается в:

(((PyObject*)(o))->ob_refcnt)

void Py_SET_REFCNT(PyObject *o, Py_ssize_t refcnt)¶: Устанавливает счётчик ссылок объекта o в значение refcnt.

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

Py_SIZE(o)¶

Этот макрос используется для доступа к полю ob_size объекта Python. Он раскрывается в:

(((PyVarObject*)(o))->ob_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

PyCFunction¶

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

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

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

PyCFunctionWithKeywords¶

Тип функций, используемых для реализации вызываемых объектов Python на C с сигнатурой METH_VARARGS | METH_KEYWORDS. Сигнатура функции:

PyObject *PyCFunctionWithKeywords(PyObject *self,
                                  PyObject *args,
                                  PyObject *kwargs);

_PyCFunctionFast¶

Тип функций, используемых для реализации вызываемых объектов Python на C с сигнатурой METH_FASTCALL. Сигнатура функции:

PyObject *_PyCFunctionFast(PyObject *self,
                           PyObject *const *args,
                           Py_ssize_t nargs);

_PyCFunctionFastWithKeywords¶

Тип функций, используемых для реализации вызываемых объектов Python на C с сигнатурой METH_FASTCALL | METH_KEYWORDS. Сигнатура функции:

PyObject *_PyCFunctionFastWithKeywords(PyObject *self,
                                       PyObject *const *args,
                                       Py_ssize_t nargs,
                                       PyObject *kwnames);

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.

PyMethodDef¶

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

Поле	Тип C	Значение
`ml_name`	const char *	имя метода
`ml_meth`	PyCFunction	указатель на реализацию на C
`ml_flags`	int	биты флагов, указывающие, как должен быть построен вызов
`ml_doc`	const char *	указывает на содержимое докстринга

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*, указывающих аргументы, а третий параметр – количество аргументов (длина массива).

Это не является частью ограниченного API.

Добавлено в версии 3.7.

METH_FASTCALL | METH_KEYWORDS

Расширение METH_FASTCALL, поддерживающее также именованные аргументы, с методами типа _PyCFunctionFastWithKeywords. Именованные аргументы передаются так же, как и в протоколе vectorcall: есть дополнительный четвертый параметр PyObject*, который является кортежем, представляющим имена именованных аргументов (гарантированно строки) или возможно NULL, если нет ключевых слов. Значения именованных аргументов хранятся в массиве args после позиционных аргументов.

Это не является частью ограниченного API.

Добавлено в версии 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

PyMemberDef¶

Структура, описывающая атрибут типа, который соответствует члену 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 в случае успеха и отрицательное значение при ошибке.

PyGetSetDef¶

Структура для определения доступа по типу свойства для типа. См. также описание слота 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 с установленным исключением в случае неудачи.