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

Базовые типы объектов и макросы¶

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

type PyObject¶

Part of the Ограниченный API. (Only some members are part of the stable ABI.)

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

type PyVarObject¶

Part of the Ограниченный API. (Only some members are part of the stable 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)¶

Part of the Стабильный ABI since version 3.10.

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

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

int Py_IsNone(PyObject *x)¶

Part of the Стабильный ABI since version 3.10.

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

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

int Py_IsTrue(PyObject *x)¶

Part of the Стабильный ABI since version 3.10.

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

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

int Py_IsFalse(PyObject *x)¶

Part of the Стабильный ABI since version 3.10.

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

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

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

void Py_SET_TYPE(PyObject *o, PyTypeObject *type)¶

Установите для объекта o type значение 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,

Функции и методы реализации¶

type PyCFunction¶

Part of the Стабильный ABI.

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

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

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

type PyCFunctionWithKeywords¶

Part of the Стабильный 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¶

Part of the Стабильный ABI (including all members).

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

const char *ml_name¶

Название метода.

PyCFunction ml_meth¶

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

int ml_flags¶

Помечает биты, указывающие на то, как должен быть сконструирован вызов.

const char *ml_doc¶

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

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

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

Существуют следующие соглашения о вызовах:

METH_VARARGS¶

Это типичное соглашение о вызове, в котором методы имеют тип PyCFunction. Функция ожидает два значения PyObject*. Первое из них - это объект self для методов; для модульных функций это объект module. Второй параметр (часто называемый 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 теперь является частью stable ABI.

METH_FASTCALL | METH_KEYWORDS

Расширение METH_FASTCALL, поддерживающее также аргументы ключевых слов, с методами типа _PyCFunctionFastWithKeywords. Аргументы ключевого слова передаются так же, как и в vectorcall protocol: существует дополнительный четвертый параметр 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¶

Методы с одним аргументом object могут быть перечислены с флагом METH_O вместо вызова PyArg_ParseTuple() с аргументом "O". Они имеют тип PyCFunction с параметром self и параметр PyObject*, представляющий единственный аргумент.

Эти две константы используются не для указания соглашения о вызове, а для привязки при использовании с методами классов. Они не могут использоваться для функций, определенных для модулей. Для любого данного метода может быть установлен не более одного из этих флагов.

METH_CLASS¶

Методу будет передан type object в качестве первого параметра, а не экземпляр типа. Это используется для создания методов класса, аналогично тому, что создается при использовании встроенной функции classmethod().

METH_STATIC¶

Методу будет передаваться NULL в качестве первого параметра, а не экземпляра типа. Это используется для создания статических методов, аналогичных тем, которые создаются при использовании встроенной функции staticmethod().

Еще одна константа определяет, будет ли метод загружен вместо другого определения с таким же именем метода.

METH_COEXIST¶

Метод будет загружен вместо существующих определений. Без METH_COEXIST по умолчанию повторяющиеся определения пропускаются. Поскольку обертки слотов загружаются перед таблицей методов, например, наличие слота sq_contains сгенерировало бы обернутый метод с именем __contains__() и исключило бы загрузку соответствующей функции PyCFunction с таким же именем. При установленном флаге функция PyCFunction будет загружена вместо объекта-оболочки и будет сосуществовать со слотом. Это полезно, поскольку вызовы функций Pc оптимизированы в большей степени, чем вызовы объектов-оболочек.

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

Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI since version 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 будет передан в качестве аргумента defining_class функции C. Должен быть установлен, если для параметра METH_METHOD установлено значение ml->ml_flags.

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

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

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

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

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

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

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

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

type PyMemberDef¶

Part of the Стабильный ABI (including all members).

Структура, описывающая атрибут типа, соответствующего элементу структуры языка Си. Ее полями являются:

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

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

Имя макроса	Тип C
T_ШОРТ	короткий
T_INT - ТОЧКА ОТСЧЕТА	инт
T_ДЛИННЫЙ	длинный
T_FLOAT (ПЛАВАЮЩИЙ)	плыть
T_ДВАБЛЬ	двойной
T_STRING (СТРОКА)	постоянный символ *
T_ОБЪЕКТ	PyObject (объект поиска) *
T_ОБЪЕКТ_EX	PyObject (объект поиска) *
T_CHAR (Т_ЧАР )	обуглить
T_БАЙТ	обуглить
Т_УБАЙТ	неподписанный символ
T_UINT (ВРЕМЯ )	неподписанный int
T_НАПАДЕНИЕ	короткий без знака
Т_УЛОНГ	неподписанный длинный
T_BOOL (Т_БУЛ )	обуглить
T_ДЛИННЫЙ	долго, долго
T_ДОЛГИЙ	неподписанный длинный длинный
Т_ПИССИЗЕТ	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).

Типы, выделенные в куче (созданные с использованием PyType_FromSpec() или аналогичные), PyMemberDef могут содержать определения для специальных элементов __dictoffset__, __weaklistoffset__ и __vectorcalloffset__, соответствующие tp_dictoffset, tp_weaklistoffset и tp_vectorcall_offset в объектах типа. Они должны быть определены с помощью T_PYSSIZET и READONLY, например:

static PyMemberDef spam_type_members[] = {
    {"__dictoffset__", T_PYSSIZET, offsetof(Spam_object, dict), READONLY},
    {NULL}  /* Sentinel */
};

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, значение object o. Устанавливаемый атрибут описывается как PyMemberDef m. Возвращает 0 в случае успеха и отрицательное значение в случае неудачи.

type PyGetSetDef¶

Part of the Стабильный ABI (including all members).

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

Поле	Тип C	Значение
имя	постоянный символ *	имя атрибута
получить	добытчик	Функция C для получения атрибута
набор	сеттер	необязательная функция C для установки или удаления атрибута, если она опущена, то атрибут доступен только для чтения
док	постоянный символ *	необязательная строка документации
закрытие	пустота *	дополнительный указатель пользовательских данных, предоставляющий дополнительные данные для получателя и установщика

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

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

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

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

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

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