structures.md
1> **Источник:** https://python-all.ru/3.10/c-api/structures.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Структуры общих объектов89При определении типов объектов Python используется большое количество структур. В данном разделе описываются эти структуры и принципы их использования.1011## Базовые типы объектов и макросы1213Все объекты Python имеют в начале своего представления в памяти небольшое число общих полей. Эти поля описываются типами [`PyObject`](https://python-all.ru/3.10/c-api/structures.html#c.PyObject) и [`PyVarObject`](https://python-all.ru/3.10/c-api/structures.html#c.PyVarObject), которые, в свою очередь, определяются через раскрытие некоторых макросов, используемых (прямо или косвенно) при определении всех остальных объектов Python.1415#### `type PyObject`1617*Часть [Limited API](https://python-all.ru/3.10/c-api/stable.html#stable). (Только некоторые члены являются частью стабильного ABI.)*1819Все типы объектов являются расширениями этого типа. Это тип, который содержит информацию, необходимую Python для обработки указателя на объект как объекта. В обычной сборке «release» он содержит только счетчик ссылок объекта и указатель на соответствующий объект типа. Ничто на самом деле не объявляется как [`PyObject`](https://python-all.ru/3.10/c-api/structures.html#c.PyObject), но любой указатель на объект Python может быть приведен к `PyObject*`. Доступ к членам должен осуществляться с помощью макросов [`Py_REFCNT`](https://python-all.ru/3.10/c-api/structures.html#c.Py_REFCNT) и [`Py_TYPE`](https://python-all.ru/3.10/c-api/structures.html#c.Py_TYPE).2021#### `type PyVarObject`2223*Часть [Limited API](https://python-all.ru/3.10/c-api/stable.html#stable). (Только некоторые члены являются частью стабильного ABI.)*2425Это расширение [`PyObject`](https://python-all.ru/3.10/c-api/structures.html#c.PyObject), добавляющее поле `ob_size`. Он используется только для объектов, которые имеют некоторое понятие *длины*. Этот тип не часто встречается в Python/C API. Доступ к членам должен осуществляться с помощью макросов [`Py_REFCNT`](https://python-all.ru/3.10/c-api/structures.html#c.Py_REFCNT), [`Py_TYPE`](https://python-all.ru/3.10/c-api/structures.html#c.Py_TYPE) и [`Py_SIZE`](https://python-all.ru/3.10/c-api/structures.html#c.Py_SIZE).2627#### `PyObject_HEAD`2829Это макрос, используемый при объявлении новых типов, представляющих объекты без изменяемой длины. Макрос PyObject\_HEAD раскрывается в:3031```c32PyObject ob_base;33```3435См. документацию [`PyObject`](https://python-all.ru/3.10/c-api/structures.html#c.PyObject) выше.3637#### `PyObject_VAR_HEAD`3839Это макрос, используемый при объявлении новых типов, представляющих объекты с длиной, которая меняется от экземпляра к экземпляру. Макрос PyObject\_VAR\_HEAD раскрывается в:4041```c42PyVarObject ob_base;43```4445См. документацию [`PyVarObject`](https://python-all.ru/3.10/c-api/structures.html#c.PyVarObject) выше.4647#### `int Py_Is(const PyObject *x, const PyObject *y)`4849*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable) начиная с версии 3.10.*5051Проверяет, является ли объект *x* тем же объектом, что и *y*, аналогично `x is y` в Python.5253Новое в версии 3.10.5455#### `int Py_IsNone(const PyObject *x)`5657*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable) начиная с версии 3.10.*5859Проверяет, является ли объект синглтоном `None`, аналогично `x is None` в Python.6061Новое в версии 3.10.6263#### `int Py_IsTrue(const PyObject *x)`6465*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable) начиная с версии 3.10.*6667Проверяет, является ли объект синглтоном `True`, аналогично `x is True` в Python.6869Новое в версии 3.10.7071#### `int Py_IsFalse(const PyObject *x)`7273*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable) начиная с версии 3.10.*7475Проверяет, является ли объект синглтоном `False`, аналогично `x is False` в Python.7677Новое в версии 3.10.7879#### `PyTypeObject *Py_TYPE(const PyObject *o)`8081Возвращает тип объекта Python *o*.8283Возвращает [заимствованную ссылку](https://python-all.ru/3.10/glossary.html#term-borrowed-reference).8485Для установки типа объекта используется функция [`Py_SET_TYPE()`](https://python-all.ru/3.10/c-api/structures.html#c.Py_SET_TYPE).8687#### `int Py_IS_TYPE(PyObject *o, PyTypeObject *type)`8889Возвращает ненулевое значение, если тип объекта *o* равен *type*. В противном случае возвращает нуль. Эквивалентно `Py_TYPE(o) == type`.9091Новое в версии 3.9.9293#### `void Py_SET_TYPE(PyObject *o, PyTypeObject *type)`9495Устанавливает тип объекта *o* в *type*.9697Новое в версии 3.9.9899#### `Py_ssize_t Py_REFCNT(const PyObject *o)`100101Возвращает счётчик ссылок объекта Python *o*.102103Изменено в версии 3.10: [`Py_REFCNT()`](https://python-all.ru/3.10/c-api/structures.html#c.Py_REFCNT) изменен на встраиваемую статическую функцию. Используйте [`Py_SET_REFCNT()`](https://python-all.ru/3.10/c-api/structures.html#c.Py_SET_REFCNT) для установки счетчика ссылок объекта.104105#### `void Py_SET_REFCNT(PyObject *o, Py_ssize_t refcnt)`106107Устанавливает счётчик ссылок объекта *o* в значение *refcnt*.108109Новое в версии 3.9.110111#### `Py_ssize_t Py_SIZE(const PyVarObject *o)`112113Возвращает размер объекта Python *o*.114115Для установки размера объекта используется функция [`Py_SET_SIZE()`](https://python-all.ru/3.10/c-api/structures.html#c.Py_SET_SIZE).116117#### `void Py_SET_SIZE(PyVarObject *o, Py_ssize_t size)`118119Устанавливает размер объекта *o* в *size*.120121Новое в версии 3.9.122123#### `PyObject_HEAD_INIT(type)`124125Это макрос, который раскрывается в значения инициализации для нового типа [`PyObject`](https://python-all.ru/3.10/c-api/structures.html#c.PyObject). Этот макрос раскрывается в:126127```c128_PyObject_EXTRA_INIT1291, type,130```131132#### `PyVarObject_HEAD_INIT(type, size)`133134Это макрос, который разворачивается в значения инициализации для нового типа [`PyVarObject`](https://python-all.ru/3.10/c-api/structures.html#c.PyVarObject), включая поле `ob_size`. Этот макрос разворачивается в:135136```c137_PyObject_EXTRA_INIT1381, type, size,139```140141## Реализация функций и методов142143#### `type PyCFunction`144145*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*146147Тип функций, используемых для реализации большинства вызываемых объектов Python в C. Функции этого типа принимают два параметра `PyObject*` и возвращают одно такое значение. Если возвращаемое значение равно `NULL`, должно быть установлено исключение. Если не `NULL`, возвращаемое значение интерпретируется как возвращаемое значение функции, как она представлена в Python. Функция должна возвращать новую ссылку.148149Сигнатура функции:150151```c152PyObject *PyCFunction(PyObject *self,153 PyObject *args);154```155156#### `type PyCFunctionWithKeywords`157158*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*159160Тип функций, используемых для реализации вызываемых объектов Python на C с сигнатурой `METH_VARARGS | METH_KEYWORDS`. Сигнатура функции:161162```c163PyObject *PyCFunctionWithKeywords(PyObject *self,164 PyObject *args,165 PyObject *kwargs);166```167168#### `type _PyCFunctionFast`169170Тип функций, используемых для реализации вызываемых объектов Python на C с сигнатурой [`METH_FASTCALL`](https://python-all.ru/3.10/c-api/structures.html#METH_FASTCALL). Сигнатура функции:171172```c173PyObject *_PyCFunctionFast(PyObject *self,174 PyObject *const *args,175 Py_ssize_t nargs);176```177178#### `type _PyCFunctionFastWithKeywords`179180Тип функций, используемых для реализации вызываемых объектов Python на C с сигнатурой `METH_FASTCALL | METH_KEYWORDS`. Сигнатура функции:181182```c183PyObject *_PyCFunctionFastWithKeywords(PyObject *self,184 PyObject *const *args,185 Py_ssize_t nargs,186 PyObject *kwnames);187```188189#### `type PyCMethod`190191Тип функций, используемых для реализации вызываемых объектов Python на C с сигнатурой `METH_METHOD | METH_FASTCALL | METH_KEYWORDS`. Сигнатура функции:192193```c194PyObject *PyCMethod(PyObject *self,195 PyTypeObject *defining_class,196 PyObject *const *args,197 Py_ssize_t nargs,198 PyObject *kwnames)199```200201Новое в версии 3.9.202203#### `type PyMethodDef`204205*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable) (включая все члены).*206207Структура, используемая для описания метода типа-расширения. Эта структура имеет четыре поля:208209#### `const char *ml_name`210211имя метода212213#### `PyCFunction ml_meth`214215указатель на реализацию на C216217#### `int ml_flags`218219биты флагов, указывающие, как должен быть построен вызов220221#### `const char *ml_doc`222223указывает на содержимое строки документации224225`ml_meth` – это указатель на функцию C. Функции могут быть разных типов, но они всегда возвращают `PyObject*`. Если функция не является [`PyCFunction`](https://python-all.ru/3.10/c-api/structures.html#c.PyCFunction), компилятор потребует приведения в таблице методов. Хотя [`PyCFunction`](https://python-all.ru/3.10/c-api/structures.html#c.PyCFunction) определяет первый параметр как `PyObject*`, обычно реализация метода использует конкретный тип C объекта *self*.226227Поле `ml_flags` – это битовое поле, которое может содержать следующие флаги. Отдельные флаги указывают либо соглашение о вызове, либо соглашение о связывании.228229Существуют следующие соглашения о вызове:230231#### `METH_VARARGS`232233Это типичное соглашение о вызове, где методы имеют тип [`PyCFunction`](https://python-all.ru/3.10/c-api/structures.html#c.PyCFunction). Функция ожидает два значения `PyObject*`. Первое – это объект *self* для методов; для функций модуля – это объект модуля. Второй параметр (часто называемый *args*) – это кортеж, представляющий все аргументы. Этот параметр обычно обрабатывается с помощью [`PyArg_ParseTuple()`](https://python-all.ru/3.10/c-api/arg.html#c.PyArg_ParseTuple) или [`PyArg_UnpackTuple()`](https://python-all.ru/3.10/c-api/arg.html#c.PyArg_UnpackTuple).234235#### `METH_VARARGS | METH_KEYWORDS`236237Методы с этими флагами должны быть типа [`PyCFunctionWithKeywords`](https://python-all.ru/3.10/c-api/structures.html#c.PyCFunctionWithKeywords). Функция ожидает три параметра: *self*, *args*, *kwargs*, где *kwargs* – это словарь всех именованных аргументов или `NULL`, если именованных аргументов нет. Параметры обычно обрабатываются с помощью [`PyArg_ParseTupleAndKeywords()`](https://python-all.ru/3.10/c-api/arg.html#c.PyArg_ParseTupleAndKeywords).238239#### `METH_FASTCALL`240241Быстрое соглашение о вызове, поддерживающее только позиционные аргументы. Методы имеют тип [`_PyCFunctionFast`](https://python-all.ru/3.10/c-api/structures.html#c._PyCFunctionFast). Первый параметр – *self*, второй параметр – массив C из значений `PyObject*`, указывающих аргументы, а третий параметр – количество аргументов (длина массива).242243Добавлено в версии 3.7.244245Изменено в версии 3.10: `METH_FASTCALL` теперь является частью стабильного ABI.246247#### `METH_FASTCALL | METH_KEYWORDS`248249Расширение [`METH_FASTCALL`](https://python-all.ru/3.10/c-api/structures.html#METH_FASTCALL), поддерживающее также именованные аргументы, с методами типа [`_PyCFunctionFastWithKeywords`](https://python-all.ru/3.10/c-api/structures.html#c._PyCFunctionFastWithKeywords). Именованные аргументы передаются так же, как и в [протоколе vectorcall](https://python-all.ru/3.10/c-api/call.html#vectorcall): есть дополнительный четвертый параметр `PyObject*`, который является кортежем, представляющим имена именованных аргументов (гарантированно строки) или возможно `NULL`, если нет ключевых слов. Значения именованных аргументов хранятся в массиве *args* после позиционных аргументов.250251Добавлено в версии 3.7.252253#### `METH_METHOD | METH_FASTCALL | METH_KEYWORDS`254255Расширение `METH_FASTCALL | METH_KEYWORDS`, поддерживающее *определяющий класс*, то есть класс, содержащий данный метод. Определяющий класс может быть суперклассом `Py_TYPE(self)`.256257Метод должен быть типа [`PyCMethod`](https://python-all.ru/3.10/c-api/structures.html#c.PyCMethod), как и для `METH_FASTCALL | METH_KEYWORDS` с добавленным аргументом `defining_class` после `self`.258259Новое в версии 3.9.260261#### `METH_NOARGS`262263Методы без параметров не должны проверять, переданы ли аргументы, если они перечислены с флагом [`METH_NOARGS`](https://python-all.ru/3.10/c-api/structures.html#METH_NOARGS). Они должны быть типа [`PyCFunction`](https://python-all.ru/3.10/c-api/structures.html#c.PyCFunction). Первый параметр обычно называется *self* и будет содержать ссылку на модуль или экземпляр объекта. Во всех случаях второй параметр будет `NULL`.264265#### `METH_O`266267Методы с одним аргументом-объектом могут быть перечислены с помощью флага [`METH_O`](https://python-all.ru/3.10/c-api/structures.html#METH_O) вместо вызова [`PyArg_ParseTuple()`](https://python-all.ru/3.10/c-api/arg.html#c.PyArg_ParseTuple) с аргументом `"O"`. Они имеют тип [`PyCFunction`](https://python-all.ru/3.10/c-api/structures.html#c.PyCFunction), с параметром *self* и параметром `PyObject*`, представляющим единственный аргумент.268269Эти две константы не используются для указания соглашения о вызовах, а для привязки при использовании с методами классов. Они не могут использоваться для функций, определённых для модулей. Для любого данного метода может быть установлен не более чем один из этих флагов.270271#### `METH_CLASS`272273Метод получит объект типа в качестве первого параметра, а не экземпляр типа. Это используется для создания *методов класса*, аналогично тому, что создаётся при использовании [`classmethod()`](https://python-all.ru/3.10/library/functions.html#classmethod) встроенной функции.274275#### `METH_STATIC`276277Метод получит `NULL` в качестве первого параметра, а не экземпляр типа. Это используется для создания *статических методов*, аналогично тому, что создаётся при использовании встроенной функции [`staticmethod()`](https://python-all.ru/3.10/library/functions.html#staticmethod).278279Ещё одна константа управляет тем, загружается ли метод вместо другого определения с тем же именем метода.280281#### `METH_COEXIST`282283Метод будет загружен вместо существующих определений. Без *METH\_COEXIST* по умолчанию повторяющиеся определения пропускаются. Поскольку обёртки слотов загружаются до таблицы методов, наличие слота *sq\_contains*, например, приведёт к созданию обёрнутого метода с именем `__contains__()` и предотвратит загрузку соответствующего PyCFunction с тем же именем. При установленном флаге PyCFunction будет загружен вместо объекта-обёртки и будет сосуществовать со слотом. Это полезно, поскольку вызовы PyCFunctions оптимизированы лучше, чем вызовы объектов-обёрток.284285## Доступ к атрибутам типов расширений286287#### `type PyMemberDef`288289*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable) (включая все члены).*290291Структура, описывающая атрибут типа, который соответствует члену C-структуры. Её поля:292293| Поле | Тип C | Значение |294| --- | --- | --- |295| `name` | const char \* | имя члена |296| `type` | int | тип члена в C-структуре |297| `offset` | Py\_ssize\_t | смещение в байтах, по которому член расположен в объектной структуре типа |298| `flags` | int | биты флага, указывающие, должно ли поле быть только для чтения или доступным для записи |299| `doc` | const char \* | указывает на содержимое докстринга |300301`type` может быть одним из многих макросов `T_`, соответствующих различным C типам. При обращении к члену из Python он будет преобразован в эквивалентный тип Python.302303| Имя макроса | Тип C |304| --- | --- |305| T\_SHORT | short |306| T\_INT | int |307| T\_LONG | long |308| T\_FLOAT | float |309| T\_DOUBLE | double |310| T\_STRING | const char \* |311| T\_OBJECT | PyObject \* |312| T\_OBJECT\_EX | PyObject \* |313| T\_CHAR | char |314| T\_BYTE | char |315| T\_UBYTE | unsigned char |316| T\_UINT | unsigned int |317| T\_USHORT | unsigned short |318| T\_ULONG | unsigned long |319| T\_BOOL | char |320| T\_LONGLONG | long long |321| T\_ULONGLONG | unsigned long long |322| T\_PYSSIZET | Py\_ssize\_t |323324`T_OBJECT` и `T_OBJECT_EX` различаются тем, что `T_OBJECT` возвращает `None`, если член равен `NULL`, а `T_OBJECT_EX` возбуждает [`AttributeError`](https://python-all.ru/3.10/library/exceptions.html#AttributeError). Старайтесь использовать `T_OBJECT_EX` вместо `T_OBJECT`, потому что `T_OBJECT_EX` правильнее обрабатывает использование оператора [`del`](https://python-all.ru/3.10/reference/simple_stmts.html#del) для этого атрибута, чем `T_OBJECT`.325326`flags` может быть `0` для доступа на запись и чтение или `READONLY` для доступа только на чтение. Использование `T_STRING` для [`type`](https://python-all.ru/3.10/library/functions.html#type) подразумевает `READONLY`. Данные `T_STRING` интерпретируются как UTF-8. Удалять можно только члены `T_OBJECT` и `T_OBJECT_EX`. (Они устанавливаются в `NULL`).327328Heap allocated types (created using [`PyType_FromSpec()`](https://python-all.ru/3.10/c-api/type.html#c.PyType_FromSpec) or similar), `PyMemberDef` may contain definitions for the special members `__dictoffset__`, `__weaklistoffset__` and `__vectorcalloffset__`, corresponding to [`tp_dictoffset`](https://python-all.ru/3.10/c-api/typeobj.html#c.PyTypeObject.tp_dictoffset), [`tp_weaklistoffset`](https://python-all.ru/3.10/c-api/typeobj.html#c.PyTypeObject.tp_weaklistoffset) and [`tp_vectorcall_offset`](https://python-all.ru/3.10/c-api/typeobj.html#c.PyTypeObject.tp_vectorcall_offset) in type objects. These must be defined with `T_PYSSIZET` and `READONLY`, for example:329330```c331static PyMemberDef spam_type_members[] = {332 {"__dictoffset__", T_PYSSIZET, offsetof(Spam_object, dict), READONLY},333 {NULL} /* Страж */334};335```336337#### `PyObject *PyMember_GetOne(const char *obj_addr, struct PyMemberDef *m)`338339Получает атрибут, принадлежащий объекту по адресу *obj\_addr*. Атрибут описывается с помощью `PyMemberDef` *m*. Возвращает `NULL` при ошибке.340341#### `int PyMember_SetOne(char *obj_addr, struct PyMemberDef *m, PyObject *o)`342343Устанавливает атрибут, принадлежащий объекту по адресу *obj\_addr*, в значение объекта *o*. Устанавливаемый атрибут описывается с помощью `PyMemberDef` *m*. Возвращает `0` в случае успеха и отрицательное значение при ошибке.344345#### `type PyGetSetDef`346347*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable) (включая все члены).*348349Структура для определения доступа по типу свойства для типа. См. также описание слота [`PyTypeObject.tp_getset`](https://python-all.ru/3.10/c-api/typeobj.html#c.PyTypeObject.tp_getset).350351| Поле | Тип C | Значение |352| --- | --- | --- |353| имя | const char \* | имя атрибута |354| get | getter | C-функция для получения атрибута |355| множество | setter | необязательная C-функция для установки или удаления атрибута, если не указана, атрибут доступен только для чтения |356| doc | const char \* | необязательная строка документации |357| closure | void \* | необязательный указатель на функцию, предоставляющий дополнительные данные для геттера и сеттера |358359Функция `get` принимает один параметр `PyObject*` (экземпляр) и указатель на функцию (связанный `closure`):360361```c362typedef PyObject *(*getter)(PyObject *, void *);363```364365В случае успеха должна возвращать новую ссылку или `NULL` с установленным исключением в случае неудачи.366367Функции `set` принимают два параметра `PyObject*` (экземпляр и устанавливаемое значение) и указатель на функцию (связанный `closure`):368369```c370typedef int (*setter)(PyObject *, PyObject *, void *);371```372373Если атрибут должен быть удален, второй параметр равен `NULL`. В случае успеха должна возвращать `0` или `-1` с установленным исключением в случае неудачи.374