`structures.md`

294 строк · 16.7 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.0/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.0/c-api/structures.html#PyObject) и [`PyVarObject`](https://python-all.ru/3.0/c-api/structures.html#PyVarObject), которые, в свою очередь, определяются расширениями некоторых макросов, также используемых, прямо или косвенно, при определении всех остальных объектов Python.1213**\[PyObject\]`PyObject`**1415Все типы объектов являются расширениями этого типа. Это тип, содержащий информацию, необходимую Python для обработки указателя на объект как объекта. В обычной «release»-сборке он содержит только счетчик ссылок объекта и указатель на соответствующий объект типа. Он соответствует полям, определенным расширением макроса1617`PyObject_HEAD`1819.2021**\[PyVarObject\]`PyVarObject`**2223Это расширение2425[`PyObject`](https://python-all.ru/3.0/c-api/structures.html#PyObject)2627, добавляющее поле2829[`ob_size`](https://python-all.ru/3.0/c-api/typeobj.html#ob_size)3031. Оно используется только для объектов, имеющих понятие3233*длины*3435. Этот тип редко встречается в Python/C API. Он соответствует полям, определенным расширением макроса3637`PyObject_VAR_HEAD`3839.4041Эти макросы используются в определении [`PyObject`](https://python-all.ru/3.0/c-api/structures.html#PyObject) и [`PyVarObject`](https://python-all.ru/3.0/c-api/structures.html#PyVarObject):4243**\[PyObject\_HEAD\]`PyObject_HEAD`**4445Это макрос, который разворачивается в объявления полей типа [`PyObject`](https://python-all.ru/3.0/c-api/structures.html#PyObject); он используется при объявлении новых типов, представляющих объекты без изменяемой длины. Конкретные поля, в которые он разворачивается, зависят от определения `Py_TRACE_REFS`. По умолчанию этот макрос не определен, и [`PyObject_HEAD`](https://python-all.ru/3.0/c-api/structures.html#PyObject_HEAD) разворачивается в:4647```c48Py_ssize_t ob_refcnt;49PyTypeObject *ob_type;50```5152Когда `Py_TRACE_REFS` определен, он раскрывается в:5354```c55PyObject *_ob_next, *_ob_prev;56Py_ssize_t ob_refcnt;57PyTypeObject *ob_type;58```5960**\[PyObject\_VAR\_HEAD\]`PyObject_VAR_HEAD`**6162Это макрос, который разворачивается в объявления полей типа [`PyVarObject`](https://python-all.ru/3.0/c-api/structures.html#PyVarObject); он используется при объявлении новых типов, представляющих объекты с длиной, меняющейся от экземпляра к экземпляру. Этот макрос всегда разворачивается в:6364```c65PyObject_HEAD66Py_ssize_t ob_size;67```6869Обратите внимание, что [`PyObject_HEAD`](https://python-all.ru/3.0/c-api/structures.html#PyObject_HEAD) является частью раскрытия, и его собственное раскрытие зависит от определения `Py_TRACE_REFS`.7071**\[PyObject\_HEAD\_INIT\]`PyObject_HEAD_INIT`**7273**\[PyCFunction\]`PyCFunction`**7475Тип функций, используемых для реализации большинства вызываемых объектов Python на C. Функции этого типа принимают два параметра7677[`PyObject*`](https://python-all.ru/3.0/c-api/structures.html#PyObject)7879и возвращают одно такое значение. Если возвращаемое значение равно8081*NULL*8283, должно быть установлено исключение. Если не8485*NULL*8687, возвращаемое значение интерпретируется как возвращаемое значение функции, представленное в Python. Функция должна возвращать новую ссылку.8889**\[PyCFunctionWithKeywords\]`PyCFunctionWithKeywords`**9091Тип функций, используемых для реализации вызываемых объектов Python на C, которые принимают именованные аргументы: они принимают три параметра9293[`PyObject*`](https://python-all.ru/3.0/c-api/structures.html#PyObject)9495и возвращают одно такое значение. См.9697[`PyCFunction`](https://python-all.ru/3.0/c-api/structures.html#PyCFunction)9899выше для описания возвращаемого значения.100101**\[PyMethodDef\]`PyMethodDef`**102103Структура, используемая для описания метода типа-расширения. Эта структура имеет четыре поля:104105| Поле | Тип C | Значение |106| --- | --- | --- |107| `ml_name` | char \* | имя метода |108| `ml_meth` | PyCFunction | указатель на реализацию на C |109| `ml_flags` | int | биты флагов, указывающие, как должен быть построен вызов |110| `ml_doc` | char \* | указывает на содержимое докстринга |111112Поле `ml_meth` – это указатель на функцию C. Функции могут быть разных типов, но они всегда возвращают [`PyObject*`](https://python-all.ru/3.0/c-api/structures.html#PyObject). Если функция не является [`PyCFunction`](https://python-all.ru/3.0/c-api/structures.html#PyCFunction), компилятор потребует приведения типа в таблице методов. Хотя [`PyCFunction`](https://python-all.ru/3.0/c-api/structures.html#PyCFunction) определяет первый параметр как [`PyObject*`](https://python-all.ru/3.0/c-api/structures.html#PyObject), часто реализация метода использует конкретный C-тип объекта *self*.113114Поле `ml_flags` – это битовое поле, которое может содержать следующие флаги. Отдельные флаги указывают либо соглашение о вызове, либо соглашение о связывании. Из флагов соглашения о вызове можно комбинировать только [`METH_VARARGS`](https://python-all.ru/3.0/c-api/structures.html#METH_VARARGS) и [`METH_KEYWORDS`](https://python-all.ru/3.0/c-api/structures.html#METH_KEYWORDS) (но обратите внимание, что [`METH_KEYWORDS`](https://python-all.ru/3.0/c-api/structures.html#METH_KEYWORDS) сам по себе эквивалентен `METH_VARARGS | METH_KEYWORDS`). Любой флаг соглашения о вызове можно комбинировать с флагом связывания.115116#### `[METH_VARARGS]METH_VARARGS`117118Это типичное соглашение о вызове, когда методы имеют тип119120[`PyCFunction`](https://python-all.ru/3.0/c-api/structures.html#PyCFunction)121122. Функция ожидает два значения123124[`PyObject*`](https://python-all.ru/3.0/c-api/structures.html#PyObject)125126. Первое – это объект127128*self*129130для методов; для функций модуля оно равно значению, переданному в131132[`Py_InitModule4`](https://python-all.ru/3.0/c-api/allocation.html#Py_InitModule4)133134(или135136*NULL*137138, если использовался139140[`Py_InitModule`](https://python-all.ru/3.0/c-api/allocation.html#Py_InitModule)141142). Второй параметр (часто называемый143144*args*145146) – это объект-кортеж, представляющий все аргументы. Этот параметр обычно обрабатывается с помощью147148[`PyArg_ParseTuple`](https://python-all.ru/3.0/c-api/arg.html#PyArg_ParseTuple)149150или151152[`PyArg_UnpackTuple`](https://python-all.ru/3.0/c-api/arg.html#PyArg_UnpackTuple)153154.155156#### `[METH_KEYWORDS]METH_KEYWORDS`157158Методы с этими флагами должны иметь тип159160[`PyCFunctionWithKeywords`](https://python-all.ru/3.0/c-api/structures.html#PyCFunctionWithKeywords)161162. Функция ожидает три параметра:163164*self*165166,167168*args*169170и словарь всех именованных аргументов. Этот флаг обычно комбинируется с171172[`METH_VARARGS`](https://python-all.ru/3.0/c-api/structures.html#METH_VARARGS)173174, и параметры обычно обрабатываются с помощью175176[`PyArg_ParseTupleAndKeywords`](https://python-all.ru/3.0/c-api/arg.html#PyArg_ParseTupleAndKeywords)177178.179180#### `[METH_NOARGS]METH_NOARGS`181182Методам без параметров не нужно проверять, переданы ли аргументы, если они перечислены с флагом183184[`METH_NOARGS`](https://python-all.ru/3.0/c-api/structures.html#METH_NOARGS)185186. Они должны иметь тип187188[`PyCFunction`](https://python-all.ru/3.0/c-api/structures.html#PyCFunction)189190. При использовании с методами объектов первый параметр обычно называется191192`self`193194и содержит ссылку на экземпляр объекта. Во всех случаях второй параметр будет равен195196*NULL*197198.199200#### `[METH_O]METH_O`201202Методы с одним объектным аргументом могут быть перечислены с флагом203204[`METH_O`](https://python-all.ru/3.0/c-api/structures.html#METH_O)205206вместо вызова207208[`PyArg_ParseTuple`](https://python-all.ru/3.0/c-api/arg.html#PyArg_ParseTuple)209210с аргументом211212`"O"`213214. Они имеют тип215216[`PyCFunction`](https://python-all.ru/3.0/c-api/structures.html#PyCFunction)217218, с параметром219220*self*221222и параметром223224[`PyObject*`](https://python-all.ru/3.0/c-api/structures.html#PyObject)225226, представляющим единственный аргумент.227228Эти две константы не используются для указания соглашения о вызовах, а для привязки при использовании с методами классов. Они не могут использоваться для функций, определённых для модулей. Для любого данного метода может быть установлен не более чем один из этих флагов.229230#### `[METH_CLASS]METH_CLASS`231232Методу будет передан объект типа в качестве первого параметра, а не экземпляр типа. Это используется для создания *методов класса*, аналогично тому, что создается при использовании встроенной функции [`classmethod()`](https://python-all.ru/3.0/library/functions.html#classmethod).233234#### `[METH_STATIC]METH_STATIC`235236Методу будет передан *NULL* в качестве первого параметра, а не экземпляр типа. Это используется для создания *статических методов*, аналогично тому, что создается при использовании встроенной функции [`staticmethod()`](https://python-all.ru/3.0/library/functions.html#staticmethod).237238Ещё одна константа управляет тем, загружается ли метод вместо другого определения с тем же именем метода.239240#### `[METH_COEXIST]METH_COEXIST`241242Метод будет загружен вместо существующих определений. Без243244*METH\_COEXIST*245246по умолчанию повторные определения пропускаются. Поскольку обёртки слотов загружаются до таблицы методов, наличие слота247248*sq\_contains*249250, например, приведёт к созданию обёрнутого метода с именем251252[`__contains__()`](https://python-all.ru/3.0/reference/datamodel.html#object.__contains__)253254и не позволит загрузить соответствующий PyCFunction с тем же именем. С установленным флагом PyCFunction будет загружен вместо объекта-обёртки и будет сосуществовать со слотом. Это полезно, так как вызовы PyCFunctions оптимизированы лучше, чем вызовы объектов-обёрток.255256**\[PyMemberDef\]`PyMemberDef`**257258Структура, описывающая атрибут типа, который соответствует члену C-структуры. Её поля:259260| Поле | Тип C | Значение |261| --- | --- | --- |262| `name` | char \* | имя члена |263| [`type`](https://python-all.ru/3.0/library/functions.html#type) | int | тип члена в C-структуре |264| `offset` | Py\_ssize\_t | смещение в байтах, по которому член расположен в объектной структуре типа |265| `flags` | int | биты флага, указывающие, должно ли поле быть только для чтения или доступным для записи |266| `doc` | char \* | указывает на содержимое докстринга |267268Поле [`type`](https://python-all.ru/3.0/library/functions.html#type) может быть одним из многих макросов `T_`, соответствующих различным типам C. При обращении к элементу из Python он будет преобразован в соответствующий тип Python.269270| Имя макроса | Тип C |271| --- | --- |272| T\_SHORT | short |273| T\_INT | int |274| T\_LONG | long |275| T\_FLOAT | float |276| T\_DOUBLE | double |277| T\_STRING | char \* |278| T\_OBJECT | PyObject \* |279| T\_OBJECT\_EX | PyObject \* |280| T\_CHAR | char |281| T\_BYTE | char |282| T\_UNBYTE | беззнаковый char |283| T\_UINT | беззнаковый int |284| T\_USHORT | беззнаковый short |285| T\_ULONG | беззнаковый long |286| T\_BOOL | char |287| T\_LONGLONG | long long |288| T\_ULONGLONG | беззнаковый long long |289| T\_PYSSIZET | Py\_ssize\_t |290291`T_OBJECT` и `T_OBJECT_EX` различаются тем, что `T_OBJECT` возвращает `None`, если член равен *NULL*, а `T_OBJECT_EX` возбуждает исключение [`AttributeError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.AttributeError).292293`flags` может быть 0 для доступа на запись и чтение или `READONLY` для доступа только для чтения. Использование `T_STRING` для [`type`](https://python-all.ru/3.0/library/functions.html#type) неявно подразумевает `READONLY`. Только члены `T_OBJECT` и `T_OBJECT_EX` могут быть удалены. (Они устанавливаются в *NULL*).294