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

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

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

Py_REFCNT(o)¶

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

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

Py_SIZE(o)¶

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

(((PyVarObject*)(o))->ob_size)

PyObject_HEAD_INIT(type)¶

Это макрос, который раскрывается в значения инициализации для нового типа PyObject. Этот макрос раскрывается в:

_PyObject_EXTRA_INIT
1, type,

PyVarObject_HEAD_INIT(type, size)¶

Это макрос, который разворачивается в значения инициализации для нового типа PyVarObject, включая поле ob_size. Этот макрос разворачивается в:

_PyObject_EXTRA_INIT
1, type, size,

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

PyCFunctionWithKeywords¶: Тип функций, используемых для реализации вызываемых объектов Python в C, которые принимают именованные аргументы: они принимают три параметра PyObject* и возвращают одно такое значение. См. PyCFunction выше для описания возвращаемого значения.

PyMethodDef¶

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

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

ml_meth – это указатель на функцию C. Функции могут быть разных типов, но они всегда возвращают PyObject*. Если функция не является PyCFunction, компилятор потребует приведения в таблице методов. Хотя PyCFunction определяет первый параметр как PyObject*, обычно реализация метода использует конкретный тип C объекта self.

Поле ml_flags является битовым полем, которое может содержать следующие флаги. Отдельные флаги указывают либо на соглашение о вызове, либо на соглашение о привязке. Из флагов соглашения о вызове можно комбинировать только METH_VARARGS и METH_KEYWORDS. Любой из флагов соглашения о вызове можно комбинировать с флагом привязки.

METH_VARARGS¶: Это типичное соглашение о вызове, где методы имеют тип PyCFunction. Функция ожидает два значения PyObject*. Первое – это объект self для методов; для функций модуля – это объект модуля. Второй параметр (часто называемый args) – это кортеж, представляющий все аргументы. Этот параметр обычно обрабатывается с помощью PyArg_ParseTuple() или PyArg_UnpackTuple().

METH_KEYWORDS¶: Методы с этими флагами должны быть типа PyCFunctionWithKeywords. Функция ожидает три параметра: self, args и словарь всех именованных аргументов. Флаг должен быть объединён с METH_VARARGS, а параметры обычно обрабатываются с помощью PyArg_ParseTupleAndKeywords().

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

PyMemberDef¶

Структура, описывающая атрибут типа, который соответствует члену C-структуры. Её поля:

Поле	Тип C	Значение
`name`	char *	имя члена
`type`	int	тип члена в C-структуре
`offset`	Py_ssize_t	смещение в байтах, по которому член расположен в объектной структуре типа
`flags`	int	биты флага, указывающие, должно ли поле быть только для чтения или доступным для записи
`doc`	char *	указывает на содержимое докстринга

type может быть одним из многих макросов T_, соответствующих различным C типам. При обращении к члену из Python он будет преобразован в эквивалентный тип Python.

Имя макроса	Тип C
T_SHORT	short
T_INT	int
T_LONG	long
T_FLOAT	float
T_DOUBLE	double
T_STRING	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).

PyGetSetDef¶

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

Поле	Тип C	Значение
имя	char *	имя атрибута
get	getter	C-функция для получения атрибута
множество	setter	необязательная C-функция для установки или удаления атрибута, если не указана, атрибут доступен только для чтения
doc	char *	необязательная строка документации
closure	void *	необязательный указатель на функцию, предоставляющий дополнительные данные для геттера и сеттера

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

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

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

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

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

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