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

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

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

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

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.

Added in version 3.10.

int Py_IsNone(PyObject *x)

Часть Стабильный ABI с версии 3.10.

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

Added in version 3.10.

int Py_IsTrue(PyObject *x)

Часть Стабильный ABI с версии 3.10.

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

Added in version 3.10.

int Py_IsFalse(PyObject *x)

Часть Стабильный ABI с версии 3.10.

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

Added in version 3.10.

PyTypeObject *Py_TYPE(PyObject *o)

Возвращаемое значение: Заимствованная ссылка.

Получение типа объекта Python o.

Возвращает borrowed reference.

Используйте функцию Py_SET_TYPE(), чтобы задать тип объекта.

Изменено в версии 3.11: Py_TYPE() заменена на встроенную статическую функцию. Тип параметра больше не является const PyObject*.

int Py_IS_TYPE(PyObject *o, PyTypeObject *type)

Возвращает ненулевое значение, если тип объекта o равен type. В противном случае возвращается ноль. Эквивалентно: Py_TYPE(o) == type.

Added in version 3.9.

void Py_SET_TYPE(PyObject *o, PyTypeObject *type)

Установите тип объекта o в type.

Added in version 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.

Added in version 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

Часть Стабильный ABI с версии 3.13.

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

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

type PyCFunctionFastWithKeywords

Часть Стабильный ABI с версии 3.13.

Тип функции, используемой для реализации вызываемых файлов 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)

Added in version 3.9.

type PyMethodDef

Часть Стабильный ABI (включая всех членов).

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

const char *ml_name

Имя метода.

PyCFunction ml_meth

Указатель на реализацию на языке C.

int ml_flags

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

const char *ml_doc

Указывает на содержимое строки docstring.

ml_meth - это указатель функции языка Си. Функции могут быть разных типов, но они всегда возвращают 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*, обозначающих аргументы, а третьим - количество аргументов (длина массива).

Added in version 3.7.

Изменено в версии 3.10: METH_FASTCALL теперь является частью stable ABI.

METH_FASTCALL | METH_KEYWORDS

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

Added in version 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.

Added in version 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)

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

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

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

Атрибут callable объекта __module__ может быть установлен из заданного аргумента module. module должен быть строкой Python, которая будет использоваться в качестве имени модуля, в котором определена функция. Если он недоступен, его можно установить в значение None или NULL.

См.также

function.__module__

Параметр cls будет передан в качестве аргумента определяющий_класс в функцию C. Должен быть установлен, если METH_METHOD установлен на ml->ml_flags.

Added in version 3.9.

PyObject *PyCFunction_NewEx(PyMethodDef *ml, PyObject *self, PyObject *module)

Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.

Эквивалент PyCMethod_New(ml, self, module, NULL).

PyObject *PyCFunction_New(PyMethodDef *ml, PyObject *self)

Возвращаемое значение: Новая ссылка. Часть Стабильный ABI с версии 3.4.

Эквивалент PyCMethod_New(ml, self, NULL, NULL).

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

type PyMemberDef

Часть Стабильный ABI (включая всех членов).

Структура, описывающая атрибут типа, который соответствует члену C struct. При определении класса поместите NULL-терминированный массив этих структур в слот tp_members.

Его полями являются, в порядке убывания:

const char *name

Имя члена. Значение NULL обозначает конец массива PyMemberDef[].

Строка должна быть статичной, ее копия не создается.

int type

Тип члена в структуре C. Возможные значения см. в разделе Типы участников.

Py_ssize_t offset

Смещение в байтах, по которому член находится в объектной структуре типа.

int flags

Ноль или более из Флаги членов, объединенных с помощью побитового ИЛИ.

const char *doc

Строка документа, или NULL. Строка должна быть статической, ее копия не создается. Обычно она определяется с помощью PyDoc_STR.

По умолчанию (когда flags равен 0) члены разрешают доступ как для чтения, так и для записи. Для доступа только на чтение используйте флаг Py_READONLY. Некоторые типы, например Py_T_STRING, подразумевают Py_READONLY. Удалять можно только члены Py_T_OBJECT_EX (и унаследованные T_OBJECT).

Для типов, выделенных из кучи (созданных с помощью PyType_FromSpec() или аналогичных), PyMemberDef может содержать определение специального члена "__vectorcalloffset__", соответствующего tp_vectorcall_offset в объектах типа. Они должны быть определены с помощью Py_T_PYSSIZET и Py_READONLY, например:

static PyMemberDef spam_type_members[] = {
    {"__vectorcalloffset__", Py_T_PYSSIZET,
     offsetof(Spam_object, vectorcall), Py_READONLY},
    {NULL}  /* Sentinel */
};

(Возможно, вам понадобится #include <stddef.h> для offsetof()).

Унаследованные смещения tp_dictoffset и tp_weaklistoffset можно определить аналогичным образом, используя члены "__dictoffset__" и "__weaklistoffset__", но расширениям настоятельно рекомендуется использовать вместо них Py_TPFLAGS_MANAGED_DICT и Py_TPFLAGS_MANAGED_WEAKREF.

Изменено в версии 3.12: PyMemberDef доступен всегда. Ранее для этого требовалось включить "structmember.h".

PyObject *PyMember_GetOne(const char *obj_addr, struct PyMemberDef *m)

Часть Стабильный ABI.

Получить атрибут, принадлежащий объекту по адресу obj_addr. Атрибут описывается PyMemberDef m. При ошибке возвращает NULL.

Изменено в версии 3.12: PyMember_GetOne доступен всегда. Ранее для этого требовалось включить "structmember.h".

int PyMember_SetOne(char *obj_addr, struct PyMemberDef *m, PyObject *o)

Часть Стабильный ABI.

Установить атрибут, принадлежащий объекту по адресу obj_addr, на объект o. Устанавливаемый атрибут описывается PyMemberDef m. Возвращает 0 в случае успеха и отрицательное значение в случае неудачи.

Изменено в версии 3.12: PyMember_SetOne доступен всегда. Ранее для этого требовалось включить "structmember.h".

Флаги членов

Следующие флаги могут использоваться с PyMemberDef.flags:

Py_READONLY

Не подлежит записи.

Py_AUDIT_READ

Выдайте object.__getattr__ audit event перед чтением.

Py_RELATIVE_OFFSET

Указывает, что offset этой записи PyMemberDef указывает на смещение от данных, специфичных для подкласса, а не от PyObject.

Может использоваться только как часть Py_tp_members slot при создании класса с использованием отрицательного basicsize. В этом случае он является обязательным.

Этот флаг используется только в PyType_Slot. При установке tp_members во время создания класса Python очищает его и устанавливает PyMemberDef.offset на смещение из структуры PyObject.

Изменено в версии 3.10: Макросы RESTRICTED, READ_RESTRICTED и WRITE_RESTRICTED, доступные при использовании #include "structmember.h", устарели. READ_RESTRICTED и RESTRICTED эквивалентны Py_AUDIT_READ; WRITE_RESTRICTED ничего не делает.

Изменено в версии 3.12: Макрос READONLY был переименован в Py_READONLY. Макрос PY_AUDIT_READ был переименован с префиксом Py_. Новые имена теперь всегда доступны. Ранее для них требовалось #include "structmember.h". Заголовок по-прежнему доступен и предоставляет старые имена.

Типы участников

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

Если не отмечено (D), атрибуты, определенные таким образом, не могут быть удалены, например, с помощью del или delattr().

Имя макроса	Тип C	Тип Python
Py_T_BYTE	char	int
Py_T_SHORT	short	int
Py_T_INT	int	int
Py_T_LONG	long	int
Py_T_LONGLONG	long long	int
Py_T_UBYTE	unsigned char	int
Py_T_UINT	unsigned int	int
Py_T_USHORT	unsigned short	int
Py_T_ULONG	unsigned long	int
Py_T_ULONGLONG	unsigned long long	int
Py_T_PYSSIZET	Py_ssize_t	int
Py_T_FLOAT	float	float
Py_T_DOUBLE	double	float
Py_T_BOOL	char (записывается как 0 или 1)	bool
Py_T_STRING	const char* (*)	str (RO)
Py_T_STRING_INPLACE	const char[] (*)	str (RO)
Py_T_CHAR	char (0-127)	str (**)
Py_T_OBJECT_EX	PyObject*	object (D)

(*): Нуль-терминированная, закодированная в UTF8 строка на языке C. При значении Py_T_STRING C-представление является указателем; при значении Py_T_STRING_INPLACE строка хранится непосредственно в структуре.

(**): Строка длиной 1. Принимается только ASCII.

(RO): Подразумевает Py_READONLY.

(D): может быть удален, в этом случае указатель устанавливается в NULL. Чтение указателя NULL вызывает AttributeError.

Added in version 3.12: В предыдущих версиях макросы были доступны только с #include "structmember.h" и назывались без префикса Py_ (например, как T_INT). Заголовок по-прежнему доступен и содержит старые имена, а также следующие устаревшие типы:

T_OBJECT

Как и Py_T_OBJECT_EX, но NULL преобразуется в None. Это приводит к удивительному поведению в Python: удаление атрибута эффективно устанавливает его в None.

T_NONE

Всегда None. Должно использоваться с Py_READONLY.

Определение геттеров и сеттеров

type PyGetSetDef

Часть Стабильный ABI (включая всех членов).

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

const char *name

имя атрибута

getter get

Функция C для получения атрибута.

setter set

Необязательная C-функция для установки или удаления атрибута. Если NULL, атрибут доступен только для чтения.

const char *doc

необязательная строка документа

void *closure

Необязательный указатель пользовательских данных, предоставляющий дополнительные данные для getter и setter.

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

Часть Стабильный ABI.

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

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

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

Часть Стабильный ABI.

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

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