`structures.md`

310 строк · 18.5 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/2.6/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/2.6/c-api/structures.html#PyObject) и [`PyVarObject`](https://python-all.ru/2.6/c-api/structures.html#PyVarObject), которые, в свою очередь, определяются через раскрытие некоторых макросов, также используемых (напрямую или косвенно) в определении всех остальных объектов Python.1213**`PyObject`**1415Все типы объектов являются расширениями этого типа. Это тип, содержащий информацию, необходимую Python для обработки указателя на объект как объекта. В обычной «релизной» сборке он содержит только счетчик ссылок объекта и указатель на соответствующий объект типа. Он соответствует полям, определяемым раскрытием макроса1617`PyObject_HEAD`1819.2021**`PyVarObject`**2223Это расширение2425[`PyObject`](https://python-all.ru/2.6/c-api/structures.html#PyObject)2627, которое добавляет поле2829[`ob_size`](https://python-all.ru/2.6/c-api/typeobj.html#ob_size)3031. Используется только для объектов, имеющих некоторое понятие3233*длины*3435. Этот тип нечасто встречается в Python/C API. Он соответствует полям, определяемым развёртыванием макроса3637`PyObject_VAR_HEAD`3839.4041Эти макросы используются в определении [`PyObject`](https://python-all.ru/2.6/c-api/structures.html#PyObject) и [`PyVarObject`](https://python-all.ru/2.6/c-api/structures.html#PyVarObject):4243**`PyObject_HEAD`**4445Это макрос, который раскрывается в объявления полей типа [`PyObject`](https://python-all.ru/2.6/c-api/structures.html#PyObject); он используется при объявлении новых типов, представляющих объекты без изменяемой длины. Конкретные поля, в которые он раскрывается, зависят от определения `Py_TRACE_REFS`. По умолчанию этот макрос не определен, и [`PyObject_HEAD`](https://python-all.ru/2.6/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`**6162Это макрос, который раскрывается в объявления полей типа [`PyVarObject`](https://python-all.ru/2.6/c-api/structures.html#PyVarObject); он используется при объявлении новых типов, представляющих объекты с длиной, которая меняется от экземпляра к экземпляру. Этот макрос всегда раскрывается в:6364```c65PyObject_HEAD66Py_ssize_t ob_size;67```6869Обратите внимание, что [`PyObject_HEAD`](https://python-all.ru/2.6/c-api/structures.html#PyObject_HEAD) является частью раскрытия, и его собственное раскрытие зависит от определения `Py_TRACE_REFS`.7071**`PyObject_HEAD_INIT`(type)**7273Это макрос, который раскрывается в значения инициализации для нового типа [`PyObject`](https://python-all.ru/2.6/c-api/structures.html#PyObject). Он раскрывается в:7475```c76_PyObject_EXTRA_INIT771, type,78```7980**`PyVarObject_HEAD_INIT`(type, size)**8182Это макрос, который раскрывается в значения инициализации для нового типа [`PyVarObject`](https://python-all.ru/2.6/c-api/structures.html#PyVarObject), включая поле [`ob_size`](https://python-all.ru/2.6/c-api/typeobj.html#ob_size). Этот макрос раскрывается в:8384```c85_PyObject_EXTRA_INIT861, type, size,87```8889**`PyCFunction`**9091Тип функций, используемых для реализации большинства вызываемых объектов Python на C. Функции этого типа принимают два параметра9293[`PyObject*`](https://python-all.ru/2.6/c-api/structures.html#PyObject)9495и возвращают одно такое значение. Если возвращаемое значение9697*NULL*9899, то должно быть установлено исключение. Если не100101*NULL*102103, возвращаемое значение интерпретируется как возвращаемое значение функции, доступное в Python. Функция должна возвращать новую ссылку.104105**`PyMethodDef`**106107Структура, используемая для описания метода типа-расширения. Эта структура имеет четыре поля:108109| Поле | Тип C | Значение |110| --- | --- | --- |111| `ml_name` | char \* | имя метода |112| `ml_meth` | PyCFunction | указатель на реализацию на C |113| `ml_flags` | int | биты флагов, указывающие, как должен быть построен вызов |114| `ml_doc` | char \* | указывает на содержимое докстринга |115116Поле `ml_meth` – это указатель на функцию C. Функции могут быть разных типов, но они всегда возвращают [`PyObject*`](https://python-all.ru/2.6/c-api/structures.html#PyObject). Если функция не является [`PyCFunction`](https://python-all.ru/2.6/c-api/structures.html#PyCFunction), компилятор потребует приведения типа в таблице методов. Хотя [`PyCFunction`](https://python-all.ru/2.6/c-api/structures.html#PyCFunction) определяет первый параметр как [`PyObject*`](https://python-all.ru/2.6/c-api/structures.html#PyObject), часто реализация метода использует конкретный C-тип объекта *self*.117118Поле `ml_flags` – это битовое поле, которое может содержать следующие флаги. Отдельные флаги указывают либо соглашение о вызове, либо соглашение о связывании. Из флагов соглашения о вызове можно комбинировать только [`METH_VARARGS`](https://python-all.ru/2.6/c-api/structures.html#METH_VARARGS) и [`METH_KEYWORDS`](https://python-all.ru/2.6/c-api/structures.html#METH_KEYWORDS) (но обратите внимание, что [`METH_KEYWORDS`](https://python-all.ru/2.6/c-api/structures.html#METH_KEYWORDS) сам по себе эквивалентен `METH_VARARGS | METH_KEYWORDS`). Любой флаг соглашения о вызове можно комбинировать с флагом связывания.119120#### `METH_VARARGS`121122Это типичное соглашение о вызове, при котором методы имеют тип123124[`PyCFunction`](https://python-all.ru/2.6/c-api/structures.html#PyCFunction)125126. Функция ожидает два значения127128[`PyObject*`](https://python-all.ru/2.6/c-api/structures.html#PyObject)129130. Первое значение – это объект131132*self*133134для методов; для функций модуля оно равно значению, переданному в135136[`Py_InitModule4()`](https://python-all.ru/2.6/c-api/allocation.html#Py_InitModule4)137138(или139140*NULL*141142, если использовалась143144[`Py_InitModule()`](https://python-all.ru/2.6/c-api/allocation.html#Py_InitModule)145146). Второй параметр (часто называемый147148*args*149150) – это объект-кортеж, представляющий все аргументы. Этот параметр обычно обрабатывается с помощью151152[`PyArg_ParseTuple()`](https://python-all.ru/2.6/c-api/arg.html#PyArg_ParseTuple)153154или155156[`PyArg_UnpackTuple()`](https://python-all.ru/2.6/c-api/arg.html#PyArg_UnpackTuple)157158.159160#### `METH_KEYWORDS`161162Методы с этими флагами должны иметь тип163164`PyCFunctionWithKeywords`165166. Функция ожидает три параметра:167168*self*169170,171172*args*173174и словарь всех именованных аргументов. Обычно этот флаг комбинируют с175176[`METH_VARARGS`](https://python-all.ru/2.6/c-api/structures.html#METH_VARARGS)177178, а параметры обычно обрабатывают с помощью179180[`PyArg_ParseTupleAndKeywords()`](https://python-all.ru/2.6/c-api/arg.html#PyArg_ParseTupleAndKeywords)181182.183184#### `METH_NOARGS`185186Методам без параметров не нужно проверять, переданы ли аргументы, если они указаны с флагом187188[`METH_NOARGS`](https://python-all.ru/2.6/c-api/structures.html#METH_NOARGS)189190. Они должны быть типа191192[`PyCFunction`](https://python-all.ru/2.6/c-api/structures.html#PyCFunction)193194. При использовании в методах объектов первый параметр обычно называется195196`self`197198и содержит ссылку на экземпляр объекта. Во всех случаях второй параметр будет199200*NULL*201202.203204#### `METH_O`205206Методы с одним объектным аргументом могут быть указаны с флагом207208[`METH_O`](https://python-all.ru/2.6/c-api/structures.html#METH_O)209210вместо вызова211212[`PyArg_ParseTuple()`](https://python-all.ru/2.6/c-api/arg.html#PyArg_ParseTuple)213214с аргументом215216`"O"`217218. Они имеют тип219220[`PyCFunction`](https://python-all.ru/2.6/c-api/structures.html#PyCFunction)221222, с параметром223224*self*225226и параметром227228[`PyObject*`](https://python-all.ru/2.6/c-api/structures.html#PyObject)229230, представляющим единственный аргумент.231232#### `METH_OLDARGS`233234Это соглашение о вызове устарело. Метод должен быть типа235236[`PyCFunction`](https://python-all.ru/2.6/c-api/structures.html#PyCFunction)237238. Второй аргумент равен239240*NULL*241242, если аргументы не переданы, одному объекту, если передан ровно один аргумент, и кортежу объектов, если передано более одного аргумента. Функция, использующая это соглашение, не может различить вызов с несколькими аргументами и вызов с единственным аргументом-кортежем.243244Эти две константы не используются для указания соглашения о вызовах, а для привязки при использовании с методами классов. Они не могут использоваться для функций, определённых для модулей. Для любого данного метода может быть установлен не более чем один из этих флагов.245246#### `METH_CLASS`247248Методу будет передан объект типа в качестве первого параметра, а не экземпляр этого типа. Это используется для создания *методов класса*, аналогично тому, что создаётся при использовании встроенной функции [`classmethod()`](https://python-all.ru/2.6/library/functions.html#classmethod).249250Новое в версии 2.3.251252#### `METH_STATIC`253254Методу будет передан *NULL* в качестве первого параметра, а не экземпляр типа. Это используется для создания *статических методов*, аналогично тому, что создаётся при использовании встроенной функции [`staticmethod()`](https://python-all.ru/2.6/library/functions.html#staticmethod).255256Новое в версии 2.3.257258Ещё одна константа управляет тем, загружается ли метод вместо другого определения с тем же именем метода.259260#### `METH_COEXIST`261262Метод будет загружен вместо существующих определений. Без *METH\_COEXIST* по умолчанию повторные определения пропускаются. Поскольку обёртки слотов загружаются до таблицы методов, существование слота *sq\_contains*, например, породит метод-обёртку с именем [`__contains__()`](https://python-all.ru/2.6/reference/datamodel.html#object.__contains__) и помешает загрузке соответствующей PyCFunction с тем же именем. Если флаг определён, PyCFunction будет загружена вместо объекта-обёртки и будет сосуществовать со слотом. Это полезно, потому что вызовы PyCFunctions оптимизированы лучше, чем вызовы объектов-обёрток.263264Новое в версии 2.4.265266**`PyMemberDef`**267268Структура, описывающая атрибут типа, который соответствует члену C-структуры. Её поля:269270| Поле | Тип C | Значение |271| --- | --- | --- |272| `name` | char \* | имя члена |273| [`type`](https://python-all.ru/2.6/library/functions.html#type) | int | тип члена в C-структуре |274| `offset` | Py\_ssize\_t | смещение в байтах, по которому член расположен в объектной структуре типа |275| `flags` | int | биты флага, указывающие, должно ли поле быть только для чтения или доступным для записи |276| `doc` | char \* | указывает на содержимое докстринга |277278Поле [`type`](https://python-all.ru/2.6/library/functions.html#type) может быть одним из многих макросов `T_`, соответствующих различным типам C. При обращении к элементу из Python он будет преобразован в соответствующий тип Python.279280| Имя макроса | Тип C |281| --- | --- |282| T\_SHORT | short |283| T\_INT | int |284| T\_LONG | long |285| T\_FLOAT | float |286| T\_DOUBLE | double |287| T\_STRING | char \* |288| T\_OBJECT | PyObject \* |289| T\_OBJECT\_EX | PyObject \* |290| T\_CHAR | char |291| T\_BYTE | char |292| T\_UBYTE | беззнаковый char |293| T\_UINT | беззнаковый int |294| T\_USHORT | беззнаковый short |295| T\_ULONG | беззнаковый long |296| T\_BOOL | char |297| T\_LONGLONG | long long |298| T\_ULONGLONG | беззнаковый long long |299| T\_PYSSIZET | Py\_ssize\_t |300301`T_OBJECT` и `T_OBJECT_EX` различаются тем, что `T_OBJECT` возвращает `None`, если поле равно *NULL*, а `T_OBJECT_EX` возбуждает [`AttributeError`](https://python-all.ru/2.6/library/exceptions.html#exceptions.AttributeError). Рекомендуется использовать `T_OBJECT_EX` вместо `T_OBJECT`, так как `T_OBJECT_EX` корректнее обрабатывает применение оператора [`del`](https://python-all.ru/2.6/reference/simple_stmts.html#del) к этому атрибуту, чем `T_OBJECT`.302303`flags` может быть 0 для доступа на запись и чтение или `READONLY` для доступа только для чтения. Использование `T_STRING` для [`type`](https://python-all.ru/2.6/library/functions.html#type) неявно подразумевает `READONLY`. Только члены `T_OBJECT` и `T_OBJECT_EX` могут быть удалены. (Они устанавливаются в *NULL*).304305**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `Py_FindMethod`([PyMethodDef](https://python-all.ru/2.6/c-api/structures.html#PyMethodDef) *table\[\]*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*ob*, char *\*name*)**306307*Возвращаемое значение: новая ссылка.*308309Возвращает объект привязанного метода для типа-расширения, реализованного на C. Это может быть полезно при реализации обработчика [`tp_getattro`](https://python-all.ru/2.6/c-api/typeobj.html#tp_getattro) или [`tp_getattr`](https://python-all.ru/2.6/c-api/typeobj.html#tp_getattr), который не использует функцию [`PyObject_GenericGetAttr()`](https://python-all.ru/2.6/c-api/object.html#PyObject_GenericGetAttr).310