structures.md

1> **Источник:** https://python-all.ru/3.7/c-api/structures.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Структуры общих объектов89При определении типов объектов Python используется большое количество структур. В данном разделе описываются эти структуры и принципы их использования.1011Все объекты Python имеют в начале своего представления в памяти небольшое число общих полей. Эти поля описываются типами [`PyObject`](https://python-all.ru/3.7/c-api/structures.html#c.PyObject) и [`PyVarObject`](https://python-all.ru/3.7/c-api/structures.html#c.PyVarObject), которые, в свою очередь, определяются через раскрытие некоторых макросов, используемых (прямо или косвенно) при определении всех остальных объектов Python.1213**`PyObject`**1415Все типы объектов являются расширениями этого типа. Это тип, который содержит информацию, необходимую Python для обработки указателя на объект как объекта. В обычной сборке «release» он содержит только счетчик ссылок объекта и указатель на соответствующий объект типа. Ничто на самом деле не объявляется как [`PyObject`](https://python-all.ru/3.7/c-api/structures.html#c.PyObject), но любой указатель на объект Python может быть приведен к [`PyObject*`](https://python-all.ru/3.7/c-api/structures.html#c.PyObject). Доступ к членам должен осуществляться с помощью макросов [`Py_REFCNT`](https://python-all.ru/3.7/c-api/structures.html#c.Py_REFCNT) и [`Py_TYPE`](https://python-all.ru/3.7/c-api/structures.html#c.Py_TYPE).1617**`PyVarObject`**1819Это расширение [`PyObject`](https://python-all.ru/3.7/c-api/structures.html#c.PyObject), добавляющее поле `ob_size`. Он используется только для объектов, которые имеют некоторое понятие *длины*. Этот тип не часто встречается в Python/C API. Доступ к членам должен осуществляться с помощью макросов [`Py_REFCNT`](https://python-all.ru/3.7/c-api/structures.html#c.Py_REFCNT), [`Py_TYPE`](https://python-all.ru/3.7/c-api/structures.html#c.Py_TYPE) и [`Py_SIZE`](https://python-all.ru/3.7/c-api/structures.html#c.Py_SIZE).2021**`PyObject_HEAD`**2223Это макрос, используемый при объявлении новых типов, представляющих объекты без изменяемой длины. Макрос PyObject\_HEAD раскрывается в:2425```c26PyObject ob_base;27```2829См. документацию [`PyObject`](https://python-all.ru/3.7/c-api/structures.html#c.PyObject) выше.3031**`PyObject_VAR_HEAD`**3233Это макрос, используемый при объявлении новых типов, представляющих объекты с длиной, которая меняется от экземпляра к экземпляру. Макрос PyObject\_VAR\_HEAD раскрывается в:3435```c36PyVarObject ob_base;37```3839См. документацию [`PyVarObject`](https://python-all.ru/3.7/c-api/structures.html#c.PyVarObject) выше.4041**`Py_TYPE`(o)**4243Этот макрос используется для доступа к полю `ob_type` объекта Python. Он раскрывается в:4445```c46(((PyObject*)(o))->ob_type)47```4849**`Py_REFCNT`(o)**5051Этот макрос используется для доступа к полю `ob_refcnt` объекта Python. Он раскрывается в:5253```c54(((PyObject*)(o))->ob_refcnt)55```5657**`Py_SIZE`(o)**5859Этот макрос используется для доступа к полю `ob_size` объекта Python. Он раскрывается в:6061```c62(((PyVarObject*)(o))->ob_size)63```6465**`PyObject_HEAD_INIT`(type)**6667Это макрос, который раскрывается в значения инициализации для нового типа [`PyObject`](https://python-all.ru/3.7/c-api/structures.html#c.PyObject). Этот макрос раскрывается в:6869```c70_PyObject_EXTRA_INIT711, type,72```7374**`PyVarObject_HEAD_INIT`(type, size)**7576Это макрос, который разворачивается в значения инициализации для нового типа [`PyVarObject`](https://python-all.ru/3.7/c-api/structures.html#c.PyVarObject), включая поле `ob_size`. Этот макрос разворачивается в:7778```c79_PyObject_EXTRA_INIT801, type, size,81```8283**`PyCFunction`**8485Тип функций, используемых для реализации большинства вызываемых объектов Python в C. Функции этого типа принимают два параметра [`PyObject*`](https://python-all.ru/3.7/c-api/structures.html#c.PyObject) и возвращают одно такое значение. Если возвращаемое значение равно `NULL`, должно быть установлено исключение. Если не `NULL`, возвращаемое значение интерпретируется как возвращаемое значение функции, как она представлена в Python. Функция должна возвращать новую ссылку.8687**`PyCFunctionWithKeywords`**8889Тип функций, используемых для реализации вызываемых объектов Python в C с сигнатурой `METH_VARARGS | METH_KEYWORDS`.9091**`_PyCFunctionFast`**9293Тип функций, используемых для реализации вызываемых объектов Python в C с сигнатурой [`METH_FASTCALL`](https://python-all.ru/3.7/c-api/structures.html#METH_FASTCALL).9495**`_PyCFunctionFastWithKeywords`**9697Тип функций, используемых для реализации вызываемых объектов Python в C с сигнатурой `METH_FASTCALL | METH_KEYWORDS`.9899**`PyMethodDef`**100101Структура, используемая для описания метода типа-расширения. Эта структура имеет четыре поля:102103| Поле | Тип C | Значение |104| --- | --- | --- |105| `ml_name` | const char \* | имя метода |106| `ml_meth` | PyCFunction | указатель на реализацию на C |107| `ml_flags` | int | биты флагов, указывающие, как должен быть построен вызов |108| `ml_doc` | const char \* | указывает на содержимое докстринга |109110`ml_meth` – это указатель на функцию C. Функции могут быть разных типов, но они всегда возвращают [`PyObject*`](https://python-all.ru/3.7/c-api/structures.html#c.PyObject). Если функция не является [`PyCFunction`](https://python-all.ru/3.7/c-api/structures.html#c.PyCFunction), компилятор потребует приведения в таблице методов. Хотя [`PyCFunction`](https://python-all.ru/3.7/c-api/structures.html#c.PyCFunction) определяет первый параметр как [`PyObject*`](https://python-all.ru/3.7/c-api/structures.html#c.PyObject), обычно реализация метода использует конкретный тип C объекта *self*.111112Поле `ml_flags` – это битовое поле, которое может содержать следующие флаги. Отдельные флаги указывают либо соглашение о вызове, либо соглашение о связывании.113114Существует четыре базовых соглашения о вызове для позиционных аргументов, и два из них могут быть объединены с `METH_KEYWORDS` для поддержки также именованных аргументов. Таким образом, всего имеется 6 соглашений о вызове:115116#### `METH_VARARGS`117118Это типичное соглашение о вызове, где методы имеют тип [`PyCFunction`](https://python-all.ru/3.7/c-api/structures.html#c.PyCFunction). Функция ожидает два значения [`PyObject*`](https://python-all.ru/3.7/c-api/structures.html#c.PyObject). Первое – это объект *self* для методов; для функций модуля – это объект модуля. Второй параметр (часто называемый *args*) – это кортеж, представляющий все аргументы. Этот параметр обычно обрабатывается с помощью [`PyArg_ParseTuple()`](https://python-all.ru/3.7/c-api/arg.html#c.PyArg_ParseTuple) или [`PyArg_UnpackTuple()`](https://python-all.ru/3.7/c-api/arg.html#c.PyArg_UnpackTuple).119120#### `METH_VARARGS | METH_KEYWORDS`121122Методы с этими флагами должны быть типа [`PyCFunctionWithKeywords`](https://python-all.ru/3.7/c-api/structures.html#c.PyCFunctionWithKeywords). Функция ожидает три параметра: *self*, *args*, *kwargs*, где *kwargs* – это словарь всех именованных аргументов или `NULL`, если именованных аргументов нет. Параметры обычно обрабатываются с помощью [`PyArg_ParseTupleAndKeywords()`](https://python-all.ru/3.7/c-api/arg.html#c.PyArg_ParseTupleAndKeywords).123124#### `METH_FASTCALL`125126Быстрое соглашение о вызове, поддерживающее только позиционные аргументы. Методы имеют тип [`_PyCFunctionFast`](https://python-all.ru/3.7/c-api/structures.html#c._PyCFunctionFast). Первый параметр – *self*, второй параметр – массив C из значений [`PyObject*`](https://python-all.ru/3.7/c-api/structures.html#c.PyObject), указывающих аргументы, а третий параметр – количество аргументов (длина массива).127128Это не является частью [ограниченного API](https://python-all.ru/3.7/c-api/stable.html#stable).129130Добавлено в версии 3.7.131132#### `METH_FASTCALL | METH_KEYWORDS`133134Расширение [`METH_FASTCALL`](https://python-all.ru/3.7/c-api/structures.html#METH_FASTCALL), поддерживающее также именованные аргументы, с методами типа [`_PyCFunctionFastWithKeywords`](https://python-all.ru/3.7/c-api/structures.html#c._PyCFunctionFastWithKeywords). Именованные аргументы передаются так же, как в протоколе vectorcall: добавляется четвёртый параметр [`PyObject*`](https://python-all.ru/3.7/c-api/structures.html#c.PyObject), который представляет собой кортеж с именами именованных аргументов или, возможно, `NULL`, если ключевых слов нет. Значения именованных аргументов хранятся в массиве *args* после позиционных аргументов.135136Это не является частью [ограниченного API](https://python-all.ru/3.7/c-api/stable.html#stable).137138Добавлено в версии 3.7.139140#### `METH_NOARGS`141142Методы без параметров не должны проверять, переданы ли аргументы, если они перечислены с флагом [`METH_NOARGS`](https://python-all.ru/3.7/c-api/structures.html#METH_NOARGS). Они должны быть типа [`PyCFunction`](https://python-all.ru/3.7/c-api/structures.html#c.PyCFunction). Первый параметр обычно называется *self* и будет содержать ссылку на модуль или экземпляр объекта. Во всех случаях второй параметр будет `NULL`.143144#### `METH_O`145146Методы с одним аргументом-объектом могут быть перечислены с помощью флага [`METH_O`](https://python-all.ru/3.7/c-api/structures.html#METH_O) вместо вызова [`PyArg_ParseTuple()`](https://python-all.ru/3.7/c-api/arg.html#c.PyArg_ParseTuple) с аргументом `"O"`. Они имеют тип [`PyCFunction`](https://python-all.ru/3.7/c-api/structures.html#c.PyCFunction), с параметром *self* и параметром [`PyObject*`](https://python-all.ru/3.7/c-api/structures.html#c.PyObject), представляющим единственный аргумент.147148Эти две константы не используются для указания соглашения о вызовах, а для привязки при использовании с методами классов. Они не могут использоваться для функций, определённых для модулей. Для любого данного метода может быть установлен не более чем один из этих флагов.149150#### `METH_CLASS`151152Метод получит объект типа в качестве первого параметра, а не экземпляр типа. Это используется для создания *методов класса*, аналогично тому, что создаётся при использовании [`classmethod()`](https://python-all.ru/3.7/library/functions.html#classmethod) встроенной функции.153154#### `METH_STATIC`155156Метод получит `NULL` в качестве первого параметра, а не экземпляр типа. Это используется для создания *статических методов*, аналогично тому, что создаётся при использовании встроенной функции [`staticmethod()`](https://python-all.ru/3.7/library/functions.html#staticmethod).157158Ещё одна константа управляет тем, загружается ли метод вместо другого определения с тем же именем метода.159160#### `METH_COEXIST`161162Метод будет загружен вместо существующих определений. Без *METH\_COEXIST* по умолчанию повторяющиеся определения пропускаются. Поскольку обёртки слотов загружаются до таблицы методов, наличие слота *sq\_contains*, например, приведёт к созданию обёрнутого метода с именем [`__contains__()`](https://python-all.ru/3.7/reference/datamodel.html#object.__contains__) и предотвратит загрузку соответствующего PyCFunction с тем же именем. При установленном флаге PyCFunction будет загружен вместо объекта-обёртки и будет сосуществовать со слотом. Это полезно, поскольку вызовы PyCFunctions оптимизированы лучше, чем вызовы объектов-обёрток.163164**`PyMemberDef`**165166Структура, описывающая атрибут типа, который соответствует члену C-структуры. Её поля:167168| Поле | Тип C | Значение |169| --- | --- | --- |170| `name` | const char \* | имя члена |171| `type` | int | тип члена в C-структуре |172| `offset` | Py\_ssize\_t | смещение в байтах, по которому член расположен в объектной структуре типа |173| `flags` | int | биты флага, указывающие, должно ли поле быть только для чтения или доступным для записи |174| `doc` | const char \* | указывает на содержимое докстринга |175176`type` может быть одним из многих макросов `T_`, соответствующих различным C типам. При обращении к члену из Python он будет преобразован в эквивалентный тип Python.177178| Имя макроса | Тип C |179| --- | --- |180| T\_SHORT | short |181| T\_INT | int |182| T\_LONG | long |183| T\_FLOAT | float |184| T\_DOUBLE | double |185| T\_STRING | const char \* |186| T\_OBJECT | PyObject \* |187| T\_OBJECT\_EX | PyObject \* |188| T\_CHAR | char |189| T\_BYTE | char |190| T\_UBYTE | unsigned char |191| T\_UINT | unsigned int |192| T\_USHORT | unsigned short |193| T\_ULONG | unsigned long |194| T\_BOOL | char |195| T\_LONGLONG | long long |196| T\_ULONGLONG | unsigned long long |197| T\_PYSSIZET | Py\_ssize\_t |198199`T_OBJECT` и `T_OBJECT_EX` различаются тем, что `T_OBJECT` возвращает `None`, если член равен `NULL`, а `T_OBJECT_EX` возбуждает [`AttributeError`](https://python-all.ru/3.7/library/exceptions.html#AttributeError). Старайтесь использовать `T_OBJECT_EX` вместо `T_OBJECT`, потому что `T_OBJECT_EX` правильнее обрабатывает использование оператора [`del`](https://python-all.ru/3.7/reference/simple_stmts.html#del) для этого атрибута, чем `T_OBJECT`.200201`flags` может быть `0` для доступа на запись и чтение или `READONLY` для доступа только на чтение. Использование `T_STRING` для [`type`](https://python-all.ru/3.7/library/functions.html#type) подразумевает `READONLY`. Данные `T_STRING` интерпретируются как UTF-8. Удалять можно только члены `T_OBJECT` и `T_OBJECT_EX`. (Они устанавливаются в `NULL`).202203**`PyGetSetDef`**204205Структура для определения доступа по типу свойства для типа. См. также описание слота [`PyTypeObject.tp_getset`](https://python-all.ru/3.7/c-api/typeobj.html#c.PyTypeObject.tp_getset).206207| Поле | Тип C | Значение |208| --- | --- | --- |209| имя | const char \* | имя атрибута |210| get | getter | C-функция для получения атрибута |211| множество | setter | необязательная C-функция для установки или удаления атрибута, если не указана, атрибут доступен только для чтения |212| doc | const char \* | необязательная строка документации |213| closure | void \* | необязательный указатель на функцию, предоставляющий дополнительные данные для геттера и сеттера |214215Функция `get` принимает один параметр [`PyObject*`](https://python-all.ru/3.7/c-api/structures.html#c.PyObject) (экземпляр) и указатель на функцию (связанный `closure`):216217```c218typedef PyObject *(*getter)(PyObject *, void *);219```220221В случае успеха должна возвращать новую ссылку или `NULL` с установленным исключением в случае неудачи.222223Функции `set` принимают два параметра [`PyObject*`](https://python-all.ru/3.7/c-api/structures.html#c.PyObject) (экземпляр и устанавливаемое значение) и указатель на функцию (связанный `closure`):224225```c226typedef int (*setter)(PyObject *, PyObject *, void *);227```228229Если атрибут должен быть удален, второй параметр равен `NULL`. В случае успеха должна возвращать `0` или `-1` с установленным исключением в случае неудачи.230