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

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

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

type PyObject¶

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

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

PyTypeObject PyBaseObject_Type¶

Часть Stable ABI.

Базовый класс всех остальных объектов, аналогичен object в Python.

int Py_Is(PyObject *x, PyObject *y)¶

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

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

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

int Py_IsNone(PyObject *x)¶

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

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

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

int Py_IsTrue(PyObject *x)¶

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

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

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

int Py_IsFalse(PyObject *x)¶

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

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

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

PyTypeObject *Py_TYPE(PyObject *o)¶

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

Возвращает тип объекта Python o.

Возвращает заимствованную ссылку.

Для установки типа объекта используется функция 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.

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

Реализация функций и методов¶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¶

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

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

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

type PyCFunctionFastWithKeywords¶

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

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

Часть Stable ABI.

Это типичное соглашение о вызове, при котором методы имеют тип 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¶

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

Быстрое соглашение о вызове, поддерживающее только позиционные аргументы. Методы имеют тип 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¶

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

Может использоваться только в комбинации с другими флагами: 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¶

Часть Stable ABI.

Методы без параметров не должны проверять, переданы ли аргументы, если они перечислены с флагом METH_NOARGS. Они должны быть типа PyCFunction. Первый параметр обычно называется self и будет содержать ссылку на модуль или экземпляр объекта. Во всех случаях второй параметр будет NULL.

Функция должна иметь 2 параметра. Поскольку второй параметр не используется, Py_UNUSED можно использовать для предотвращения предупреждения компилятора.

METH_O¶

Часть Stable ABI.

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

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

METH_CLASS¶

Часть Stable ABI.

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

METH_STATIC¶

Часть Stable ABI.

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

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

METH_COEXIST¶

Часть Stable ABI.

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

PyTypeObject PyCMethod_Type¶

Объект типа, соответствующий объектам методов C Python. Доступен как types.BuiltinMethodType в слое Python.

int PyCMethod_Check(PyObject *op)¶

Возвращает true, если op является экземпляром типа PyCMethod_Type или его подтипом. Эта функция всегда выполняется успешно.

int PyCMethod_CheckExact(PyObject *op)¶

То же, что и PyCMethod_Check(), но не учитывает подтипы.

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

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

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

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

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

См. также

function.__module__

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

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

PyTypeObject PyCFunction_Type¶

Часть Stable ABI.

Объект типа, соответствующий объектам C-функций Python. Доступен как types.BuiltinFunctionType на уровне Python.

int PyCFunction_Check(PyObject *op)¶

Возвращает true, если op является экземпляром типа PyCFunction_Type или его подтипом. Эта функция всегда выполняется успешно.

int PyCFunction_CheckExact(PyObject *op)¶

То же, что и PyCFunction_Check(), но не учитывает подтипы.

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

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

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

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

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

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

int PyCFunction_GetFlags(PyObject *func)¶

Часть Stable ABI.

Получает флаги функции для func, переданные в ml_flags.

Если func не является объектом C-функции, возникает исключение. func не должен быть NULL.

Эта функция возвращает флаги функции в случае успеха и -1 с установленным исключением в случае неудачи.

int PyCFunction_GET_FLAGS(PyObject *func)¶

То же, что и PyCFunction_GetFlags(), но без проверки ошибок или типа.

PyCFunction PyCFunction_GetFunction(PyObject *func)¶

Часть Stable ABI.

Получает указатель на функцию для func, переданный в ml_meth.

Если func не является объектом C-функции, возникает исключение. func не должен быть NULL.

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

int PyCFunction_GET_FUNCTION(PyObject *func)¶

То же, что и PyCFunction_GetFunction(), но без проверки ошибок или типа.

PyObject *PyCFunction_GetSelf(PyObject *func)¶

Часть Stable ABI.

Получает объект «self» для func. Это объект, который будет передан первым аргументом PyCFunction. Для объектов C-функций, созданных через PyMethodDef на PyModuleDef, это результирующий объект модуля.

Если func не является объектом C-функции, возникает исключение. func не должен быть NULL.

Эта функция возвращает заимствованную ссылку на объект «self» в случае успеха и NULL с установленным исключением в случае неудачи.

PyObject *PyCFunction_GET_SELF(PyObject *func)¶

То же, что и PyCFunction_GetSelf(), но без проверки ошибок или типа.

Доступ к атрибутам типов расширений¶Accessing attributes of extension types

type PyMemberDef¶

Часть Stable ABI (включая все члены).

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

Его поля, по порядку:

const char *name¶

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

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

int type¶

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

Py_ssize_t offset¶

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

int flags¶

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

const char *doc¶

Строка документации (docstring) или 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}  /* Страж */
};

(Возможно, потребуется #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)¶

Часть Stable ABI.

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

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

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

Часть Stable ABI.

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

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