structures.md

1> **Источник:** https://python-all.ru/3.4/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.4/c-api/structures.html#c.PyObject) и [`PyVarObject`](https://python-all.ru/3.4/c-api/structures.html#c.PyVarObject), которые, в свою очередь, определяются через раскрытие некоторых макросов, также используемых (напрямую или косвенно) в определении всех остальных объектов Python.1213**`PyObject`**1415Все типы объектов являются расширениями этого типа. Это тип, который содержит информацию, необходимую Python для обработки указателя на объект как объекта. В обычной «релизной» сборке он содержит только счётчик ссылок объекта и указатель на соответствующий объект-тип. Ни один объект не объявляется как [`PyObject`](https://python-all.ru/3.4/c-api/structures.html#c.PyObject), но любой указатель на объект Python может быть приведён к [`PyObject*`](https://python-all.ru/3.4/c-api/structures.html#c.PyObject). Доступ к членам должен осуществляться с помощью макросов [`Py_REFCNT`](https://python-all.ru/3.4/c-api/structures.html#c.Py_REFCNT) и [`Py_TYPE`](https://python-all.ru/3.4/c-api/structures.html#c.Py_TYPE).1617**`PyVarObject`**1819Это расширение [`PyObject`](https://python-all.ru/3.4/c-api/structures.html#c.PyObject), добавляющее поле `ob_size`. Оно используется только для объектов, имеющих некоторое понятие *длины*. Этот тип редко встречается в Python/C API. Доступ к членам должен осуществляться с помощью макросов [`Py_REFCNT`](https://python-all.ru/3.4/c-api/structures.html#c.Py_REFCNT), [`Py_TYPE`](https://python-all.ru/3.4/c-api/structures.html#c.Py_TYPE) и [`Py_SIZE`](https://python-all.ru/3.4/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.4/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.4/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.4/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.4/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.4/c-api/structures.html#c.PyObject) и возвращают одно такое значение. Если возвращаемое значение *NULL*, то должно быть установлено исключение. Если не *NULL*, возвращаемое значение интерпретируется как возвращаемое значение функции, доступное в Python. Функция должна возвращать новую ссылку.8687**`PyCFunctionWithKeywords`**8889Тип функций, используемых для реализации вызываемых объектов Python на C, которые принимают именованные аргументы: они принимают три параметра [`PyObject*`](https://python-all.ru/3.4/c-api/structures.html#c.PyObject) и возвращают одно такое значение. См. [`PyCFunction`](https://python-all.ru/3.4/c-api/structures.html#c.PyCFunction) выше для описания возвращаемого значения.9091**`PyMethodDef`**9293Структура, используемая для описания метода типа-расширения. Эта структура имеет четыре поля:9495| Поле | Тип C | Значение |96| --- | --- | --- |97| `ml_name` | char \* | имя метода |98| `ml_meth` | PyCFunction | указатель на реализацию на C |99| `ml_flags` | int | биты флагов, указывающие, как должен быть построен вызов |100| `ml_doc` | char \* | указывает на содержимое докстринга |101102Поле `ml_meth` – это указатель на функцию на C. Функции могут быть разных типов, но всегда возвращают [`PyObject*`](https://python-all.ru/3.4/c-api/structures.html#c.PyObject). Если функция не относится к типу [`PyCFunction`](https://python-all.ru/3.4/c-api/structures.html#c.PyCFunction), компилятор потребует явного приведения типа в таблице методов. Хотя [`PyCFunction`](https://python-all.ru/3.4/c-api/structures.html#c.PyCFunction) определяет первый параметр как [`PyObject*`](https://python-all.ru/3.4/c-api/structures.html#c.PyObject), реализации методов часто используют конкретный C-тип объекта *self*.103104Поле `ml_flags` – это битовое поле, которое может содержать следующие флаги. Отдельные флаги указывают либо соглашение о вызове, либо соглашение о связывании. Из флагов соглашения о вызове можно комбинировать только [`METH_VARARGS`](https://python-all.ru/3.4/c-api/structures.html#METH_VARARGS) и [`METH_KEYWORDS`](https://python-all.ru/3.4/c-api/structures.html#METH_KEYWORDS) (но обратите внимание, что [`METH_KEYWORDS`](https://python-all.ru/3.4/c-api/structures.html#METH_KEYWORDS) сам по себе эквивалентен `METH_VARARGS | METH_KEYWORDS`). Любой флаг соглашения о вызове можно комбинировать с флагом связывания.105106#### `METH_VARARGS`107108Это стандартное соглашение о вызове, при котором методы имеют тип [`PyCFunction`](https://python-all.ru/3.4/c-api/structures.html#c.PyCFunction). Функция ожидает два значения [`PyObject*`](https://python-all.ru/3.4/c-api/structures.html#c.PyObject). Первое – это объект *self* для методов; для модульных функций это объект модуля. Второй параметр (часто называемый *args*) представляет собой кортеж, содержащий все аргументы. Этот параметр обычно обрабатывается с помощью [`PyArg_ParseTuple()`](https://python-all.ru/3.4/c-api/arg.html#c.PyArg_ParseTuple) или [`PyArg_UnpackTuple()`](https://python-all.ru/3.4/c-api/arg.html#c.PyArg_UnpackTuple).109110#### `METH_KEYWORDS`111112Методы с этими флагами должны иметь тип [`PyCFunctionWithKeywords`](https://python-all.ru/3.4/c-api/structures.html#c.PyCFunctionWithKeywords). Функция ожидает три параметра: *self*, *args* и словарь всех именованных аргументов. Этот флаг обычно комбинируется с [`METH_VARARGS`](https://python-all.ru/3.4/c-api/structures.html#METH_VARARGS), и параметры обычно обрабатываются с помощью [`PyArg_ParseTupleAndKeywords()`](https://python-all.ru/3.4/c-api/arg.html#c.PyArg_ParseTupleAndKeywords).113114#### `METH_NOARGS`115116Методы без параметров не должны проверять, переданы ли аргументы, если они указаны с флагом [`METH_NOARGS`](https://python-all.ru/3.4/c-api/structures.html#METH_NOARGS). Они должны иметь тип [`PyCFunction`](https://python-all.ru/3.4/c-api/structures.html#c.PyCFunction). Первый параметр обычно называется *self* и содержит ссылку на модуль или экземпляр объекта. Во всех случаях второй параметр будет *NULL*.117118#### `METH_O`119120Методы с одним объектным аргументом могут быть указаны с флагом [`METH_O`](https://python-all.ru/3.4/c-api/structures.html#METH_O) вместо вызова [`PyArg_ParseTuple()`](https://python-all.ru/3.4/c-api/arg.html#c.PyArg_ParseTuple) с аргументом `"O"`. Они имеют тип [`PyCFunction`](https://python-all.ru/3.4/c-api/structures.html#c.PyCFunction), с параметром *self* и параметром [`PyObject*`](https://python-all.ru/3.4/c-api/structures.html#c.PyObject), представляющим единственный аргумент.121122Эти две константы не используются для указания соглашения о вызовах, а для привязки при использовании с методами классов. Они не могут использоваться для функций, определённых для модулей. Для любого данного метода может быть установлен не более чем один из этих флагов.123124#### `METH_CLASS`125126Методу будет передан объект типа в качестве первого параметра, а не экземпляр этого типа. Это используется для создания *методов класса*, аналогично тому, что создаётся при использовании встроенной функции [`classmethod()`](https://python-all.ru/3.4/library/functions.html#classmethod).127128#### `METH_STATIC`129130Методу будет передан *NULL* в качестве первого параметра, а не экземпляр типа. Это используется для создания *статических методов*, аналогично тому, что создаётся при использовании встроенной функции [`staticmethod()`](https://python-all.ru/3.4/library/functions.html#staticmethod).131132Ещё одна константа управляет тем, загружается ли метод вместо другого определения с тем же именем метода.133134#### `METH_COEXIST`135136Метод будет загружен вместо существующих определений. Без *METH\_COEXIST* по умолчанию повторные определения пропускаются. Поскольку обёртки слотов загружаются до таблицы методов, существование слота *sq\_contains*, например, породит метод-обёртку с именем [`__contains__()`](https://python-all.ru/3.4/reference/datamodel.html#object.__contains__) и помешает загрузке соответствующей PyCFunction с тем же именем. Если флаг определён, PyCFunction будет загружена вместо объекта-обёртки и будет сосуществовать со слотом. Это полезно, потому что вызовы PyCFunctions оптимизированы лучше, чем вызовы объектов-обёрток.137138**`PyMemberDef`**139140Структура, описывающая атрибут типа, который соответствует члену C-структуры. Её поля:141142| Поле | Тип C | Значение |143| --- | --- | --- |144| `name` | char \* | имя члена |145| [`type`](https://python-all.ru/3.4/library/functions.html#type) | int | тип члена в C-структуре |146| `offset` | Py\_ssize\_t | смещение в байтах, по которому член расположен в объектной структуре типа |147| `flags` | int | биты флага, указывающие, должно ли поле быть только для чтения или доступным для записи |148| `doc` | char \* | указывает на содержимое докстринга |149150Поле [`type`](https://python-all.ru/3.4/library/functions.html#type) может быть одним из многих макросов `T_`, соответствующих различным типам C. При обращении к элементу из Python он будет преобразован в соответствующий тип Python.151152| Имя макроса | Тип C |153| --- | --- |154| T\_SHORT | short |155| T\_INT | int |156| T\_LONG | long |157| T\_FLOAT | float |158| T\_DOUBLE | double |159| T\_STRING | char \* |160| T\_OBJECT | PyObject \* |161| T\_OBJECT\_EX | PyObject \* |162| T\_CHAR | char |163| T\_BYTE | char |164| T\_UBYTE | unsigned char |165| T\_UINT | unsigned int |166| T\_USHORT | unsigned short |167| T\_ULONG | unsigned long |168| T\_BOOL | char |169| T\_LONGLONG | long long |170| T\_ULONGLONG | unsigned long long |171| T\_PYSSIZET | Py\_ssize\_t |172173`T_OBJECT` и `T_OBJECT_EX` различаются тем, что `T_OBJECT` возвращает `None`, если поле равно *NULL*, а `T_OBJECT_EX` возбуждает [`AttributeError`](https://python-all.ru/3.4/library/exceptions.html#AttributeError). Рекомендуется использовать `T_OBJECT_EX` вместо `T_OBJECT`, так как `T_OBJECT_EX` корректнее обрабатывает применение оператора [`del`](https://python-all.ru/3.4/reference/simple_stmts.html#del) к этому атрибуту, чем `T_OBJECT`.174175`flags` может быть 0 для доступа на запись и чтение или `READONLY` для доступа только для чтения. Использование `T_STRING` для [`type`](https://python-all.ru/3.4/library/functions.html#type) неявно подразумевает `READONLY`. Только члены `T_OBJECT` и `T_OBJECT_EX` могут быть удалены. (Они устанавливаются в *NULL*).176