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

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

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

type PyObject¶

Часть Stable ABI (см. ниже).

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

К элементам нельзя обращаться напрямую; вместо этого используйте макросы, такие как Py_REFCNT и Py_TYPE.

В стабильном ABI для сборок со свободной многопоточностью (abi3t) эта структура непрозрачна; её размер и расположение могут меняться между версиями Python. В стабильном ABI для сборок без свободной многопоточности (abi3) поля ob_refcnt и ob_type доступны, но их прямое использование не рекомендуется.

Py_ssize_t ob_refcnt¶

Часть Stable ABI.

Счётчик ссылок объекта, возвращаемый Py_REFCNT. Не используйте это поле напрямую; вместо этого используйте функции и макросы, такие как Py_REFCNT, Py_INCREF() и Py_DecRef().

Тип поля может отличаться от Py_ssize_t в зависимости от конфигурации сборки и платформы.

PyTypeObject *ob_type¶

Часть Stable ABI.

Тип объекта. Не используйте это поле напрямую; вместо этого используйте Py_TYPE и Py_SET_TYPE().

PyMutex ob_mutex¶

Блокировка для каждого объекта, присутствующая только в сборке со свободной многопоточностью (когда определён Py_GIL_DISABLED).

Это поле зарезервировано для использования API критической секции (Py_BEGIN_CRITICAL_SECTION / Py_END_CRITICAL_SECTION). Не блокируйте его напрямую с помощью PyMutex_Lock; это может привести к взаимоблокировкам. Если вам нужна собственная блокировка, добавьте отдельное поле PyMutex в структуру вашего объекта.

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

type PyVarObject¶

Часть Stable ABI (см. ниже).

Расширение PyObject, добавляющее поле ob_size. Предназначено для объектов, имеющих некоторое понятие длины.

Как и в случае с PyObject, к элементам нельзя обращаться напрямую; вместо этого используйте макросы, такие как Py_SIZE, Py_REFCNT и Py_TYPE.

В стабильном ABI для сборок со свободной многопоточностью (abi3t) эта структура непрозрачна; её размер и расположение могут меняться между версиями Python. В стабильном ABI для сборок без свободной многопоточности (abi3) поля ob_base и ob_size доступны, но их прямое использование не рекомендуется.

PyObject ob_base¶

Часть Stable ABI.

Общий заголовок объекта. Обычно к этому полю не обращаются напрямую; вместо этого PyVarObject может быть приведён к PyObject.

Py_ssize_t ob_size¶

Часть Stable ABI.

Поле размера, содержимое которого следует считать внутренней деталью реализации объекта.

Не используйте это поле напрямую; вместо этого используйте Py_SIZE.

Функции создания объектов, такие как PyObject_NewVar(), обычно устанавливают это поле в запрошенный размер (количество элементов). После создания в ob_size можно сохранять произвольные значения с помощью Py_SET_SIZE.

Чтобы получить публично доступную длину объекта, возвращаемую функцией Python len(), используйте PyObject_Length().

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)¶

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

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

Возвращаемая ссылка является заёмной из o. Не освобождайте её с помощью Py_DECREF() или аналогичных средств.

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

int Py_IS_TYPE(PyObject *o, PyTypeObject *type)¶

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

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

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

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

Устанавливает тип объекта o в type без какой-либо проверки или подсчёта ссылок.

Это операция очень низкого уровня. Вместо этого рекомендуется устанавливать атрибут Python __class__ с помощью PyObject_SetAttrString() или аналогичного.

Обратите внимание, что присвоение несовместимого типа может привести к неопределённому поведению.

Если type является кучным типом (heap type), вызывающий должен создать новую ссылку на него. Аналогично, если старый тип o является кучным типом, вызывающий должен освободить ссылку на этот тип.

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

Py_ssize_t Py_SIZE(PyVarObject *o)¶

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

Возвращает поле ob_size объекта o.

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

void Py_SET_SIZE(PyVarObject *o, Py_ssize_t size)¶

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

Устанавливает поле ob_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¶

Имя метода.

NULL ml_name обозначает конец массива PyMethodDef.

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, либо Py_READONLY | Py_RELATIVE_OFFSET. Например:

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".

Изменено в версии 3.14: Py_RELATIVE_OFFSET теперь разрешён для "__vectorcalloffset__", "__dictoffset__" и "__weaklistoffset__".

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".