Общие структуры объектов¶
Существует большое количество структур, которые используются при определении типов объектов в Python. В этом разделе описываются эти структуры и то, как они используются.
Типы базовых объектов и макросы¶
Все объекты Python в конечном итоге разделяют небольшое количество полей в начале представления объекта в памяти. Они представлены типами PyObject
и PyVarObject
, которые, в свою очередь, определяются расширениями некоторых макросов, прямо или косвенно используемых в определении всех других объектов Python. Дополнительные макросы можно найти в разделе reference counting.
-
type PyObject¶
- Часть Ограниченный API. (Только некоторые члены являются частью стабильного ABI).
Все типы объектов являются расширениями этого типа. Это тип, который содержит информацию, необходимую Python для того, чтобы рассматривать указатель на объект как объект. В обычной «релизной» сборке он содержит только счетчик ссылок на объект и указатель на объект соответствующего типа. На самом деле ничто не объявлено как
PyObject
, но каждый указатель на объект Python может быть приведен к PyObject*. Доступ к членам должен осуществляться с помощью макросовPy_REFCNT
иPy_TYPE
.
-
type PyVarObject¶
- Часть Ограниченный API. (Только некоторые члены являются частью стабильного ABI).
Это расширение
PyObject
, добавляющее полеob_size
. Оно используется только для объектов, имеющих некоторое понятие о длине. Этот тип не часто встречается в API Python/C. Доступ к членам должен осуществляться с помощью макросовPy_REFCNT
,Py_TYPE
иPy_SIZE
.
-
PyObject_HEAD¶
Этот макрос используется при объявлении новых типов, представляющих объекты, длина которых не изменяется. Макрос PyObject_HEAD расширяется до:
PyObject ob_base;
См. документацию по
PyObject
выше.
-
PyObject_VAR_HEAD¶
Этот макрос используется при объявлении новых типов, которые представляют объекты с длиной, изменяющейся от экземпляра к экземпляру. Макрос PyObject_VAR_HEAD расширяется до:
PyVarObject ob_base;
См. документацию по
PyVarObject
выше.
-
int Py_Is(PyObject *x, PyObject *y)¶
- Часть Стабильный ABI с версии 3.10.
Проверяет, является ли объект x объектом y, так же как
x is y
в Python.Added in version 3.10.
-
int Py_IsNone(PyObject *x)¶
- Часть Стабильный ABI с версии 3.10.
Проверяет, является ли объект синглтоном
None
, как иx is None
в Python.Added in version 3.10.
-
int Py_IsTrue(PyObject *x)¶
- Часть Стабильный ABI с версии 3.10.
Проверяет, является ли объект синглтоном
True
, как иx is True
в Python.Added in version 3.10.
-
int Py_IsFalse(PyObject *x)¶
- Часть Стабильный ABI с версии 3.10.
Проверяет, является ли объект синглтоном
False
, как иx is False
в Python.Added in version 3.10.
-
PyTypeObject *Py_TYPE(PyObject *o)¶
- Возвращаемое значение: Заимствованная ссылка.
Получение типа объекта Python o.
Возвращает borrowed reference.
Используйте функцию
Py_SET_TYPE()
, чтобы задать тип объекта.
-
int Py_IS_TYPE(PyObject *o, PyTypeObject *type)¶
Возвращает ненулевое значение, если тип объекта o равен type. В противном случае возвращается ноль. Эквивалентно:
Py_TYPE(o) == type
.Added in version 3.9.
-
void Py_SET_TYPE(PyObject *o, PyTypeObject *type)¶
Установите тип объекта o в type.
Added in version 3.9.
-
Py_ssize_t Py_SIZE(PyVarObject *o)¶
Получите размер объекта Python o.
Используйте функцию
Py_SET_SIZE()
, чтобы задать размер объекта.Изменено в версии 3.11:
Py_SIZE()
заменена на встроенную статическую функцию. Тип параметра больше не является const PyVarObject*.
-
void Py_SET_SIZE(PyVarObject *o, Py_ssize_t size)¶
Установите размер объекта o на size.
Added in version 3.9.
-
PyObject_HEAD_INIT(type)¶
Это макрос, который расширяет значения инициализации для нового типа
PyObject
. Этот макрос расширяется до:_PyObject_EXTRA_INIT 1, type,
-
PyVarObject_HEAD_INIT(type, size)¶
Это макрос, который расширяет значения инициализации для нового типа
PyVarObject
, включая полеob_size
. Этот макрос расширяется до:_PyObject_EXTRA_INIT 1, type, size,
Реализация функций и методов¶
-
type PyCFunction¶
- Часть Стабильный ABI.
Тип функций, используемых для реализации большинства вызываемых функций Python на языке C. Функции этого типа принимают два параметра PyObject* и возвращают одно такое значение. Если возвращаемое значение равно
NULL
, то должно быть установлено исключение. Если неNULL
, то возвращаемое значение интерпретируется как возвращаемое значение функции в том виде, в котором оно представлено в Python. Функция должна возвращать новую ссылку.Сигнатура функции выглядит так:
PyObject *PyCFunction(PyObject *self, PyObject *args);
-
type PyCFunctionWithKeywords¶
- Часть Стабильный ABI.
Тип функции, используемой для реализации вызываемых файлов Python на языке C с сигнатурой METH_VARARGS | METH_KEYWORDS. Сигнатура функции выглядит следующим образом:
PyObject *PyCFunctionWithKeywords(PyObject *self, PyObject *args, PyObject *kwargs);
-
type PyCFunctionFast¶
- Часть Стабильный ABI с версии 3.13.
Тип функции, используемой для реализации вызываемых файлов Python на языке C с сигнатурой
METH_FASTCALL
. Сигнатура функции выглядит следующим образом:PyObject *PyCFunctionFast(PyObject *self, PyObject *const *args, Py_ssize_t nargs);
-
type PyCFunctionFastWithKeywords¶
- Часть Стабильный ABI с версии 3.13.
Тип функции, используемой для реализации вызываемых файлов Python на языке C с сигнатурой METH_FASTCALL | METH_KEYWORDS. Сигнатура функции выглядит следующим образом:
PyObject *PyCFunctionFastWithKeywords(PyObject *self, PyObject *const *args, Py_ssize_t nargs, PyObject *kwnames);
-
type PyCMethod¶
Тип функции, используемой для реализации вызываемых файлов Python на языке C с сигнатурой METH_METHOD | METH_FASTCALL | METH_KEYWORDS. Сигнатура функции выглядит следующим образом:
PyObject *PyCMethod(PyObject *self, PyTypeObject *defining_class, PyObject *const *args, Py_ssize_t nargs, PyObject *kwnames)
Added in version 3.9.
-
type PyMethodDef¶
- Часть Стабильный ABI (включая всех членов).
Структура, используемая для описания метода типа расширения. Эта структура состоит из четырех полей:
-
const char *ml_name¶
Имя метода.
-
PyCFunction ml_meth¶
Указатель на реализацию на языке C.
-
int ml_flags¶
Биты флагов, указывающие на то, как должен быть построен вызов.
-
const char *ml_doc¶
Указывает на содержимое строки docstring.
-
const char *ml_name¶
ml_meth
- это указатель функции языка Си. Функции могут быть разных типов, но они всегда возвращают PyObject*. Если функция не относится к PyCFunction
, компилятор потребует приведения в таблице методов. Несмотря на то, что в PyCFunction
первый параметр определяется как PyObject*, обычно в реализации метода используется конкретный тип C объекта self.
Поле ml_flags
- это битовое поле, которое может содержать следующие флаги. Отдельные флаги указывают либо на конвенцию вызова, либо на конвенцию связывания.
Существуют такие условные обозначения:
-
METH_VARARGS¶
Это типичное соглашение о вызове, в котором методы имеют тип
PyCFunction
. Функция ожидает два значения PyObject*. Первое - это объект self для методов; для функций модуля - объект модуля. Второй параметр (часто называемый args) - это кортеж, представляющий все аргументы. Этот параметр обычно обрабатывается с помощьюPyArg_ParseTuple()
илиPyArg_UnpackTuple()
.
-
METH_KEYWORDS¶
Может использоваться только в определенных комбинациях с другими флагами: METH_VARARGS | METH_KEYWORDS, METH_FASTCALL | METH_KEYWORDS и METH_METHOD | METH_FASTCALL | METH_KEYWORDS.
- METH_VARARGS | METH_KEYWORDS
Методы с этими флагами должны иметь тип
PyCFunctionWithKeywords
. Функция ожидает три параметра: self, args, kwargs, где kwargs - это словарь всех аргументов ключевых слов или, возможно,NULL
, если аргументов ключевых слов нет. Параметры обычно обрабатываются с помощьюPyArg_ParseTupleAndKeywords()
.
-
METH_FASTCALL¶
Быстрая конвенция вызова, поддерживающая только позиционные аргументы. Методы имеют тип
PyCFunctionFast
. Первым параметром является self, вторым - массив C из значений PyObject*, обозначающих аргументы, а третьим - количество аргументов (длина массива).Added in version 3.7.
Изменено в версии 3.10:
METH_FASTCALL
теперь является частью stable ABI.
- METH_FASTCALL | METH_KEYWORDS
Расширение
METH_FASTCALL
, поддерживающее также аргументы в виде ключевых слов, с методами типаPyCFunctionFastWithKeywords
. Аргументы ключевых слов передаются так же, как и в vectorcall protocol: есть дополнительный четвертый параметр PyObject*, который является кортежем, представляющим имена аргументов ключевых слов (которые гарантированно являются строками) или, возможно,NULL
, если ключевых слов нет. Значения аргументов ключевых слов хранятся в массиве args, после позиционных аргументов.Added in version 3.7.
-
METH_METHOD¶
Может использоваться только в комбинации с другими флагами: METH_METHOD | METH_FASTCALL | METH_KEYWORDS.
- METH_METHOD | METH_FASTCALL | METH_KEYWORDS
Расширение METH_FASTCALL | METH_KEYWORDS, поддерживающее определяющий класс, то есть класс, содержащий рассматриваемый метод. Определяющий класс может быть суперклассом
Py_TYPE(self)
.Метод должен иметь тип
PyCMethod
, такой же, как и дляMETH_FASTCALL | METH_KEYWORDS
, с аргументомdefining_class
, добавленным послеself
.Added in version 3.9.
-
METH_NOARGS¶
Методам без параметров не нужно проверять, переданы ли аргументы, если они перечислены с флагом
METH_NOARGS
. Они должны иметь типPyCFunction
. Первый параметр обычно называется self и содержит ссылку на модуль или экземпляр объекта. Во всех случаях второй параметр будет иметь типNULL
.Функция должна иметь 2 параметра. Поскольку второй параметр не используется, для предотвращения предупреждения компилятора можно использовать
Py_UNUSED
.
-
METH_O¶
Методы с одним объектным аргументом можно перечислить с флагом
METH_O
, вместо того чтобы вызыватьPyArg_ParseTuple()
с аргументом"O"
. Они имеют типPyCFunction
с параметром self и параметром PyObject*, представляющим единственный аргумент.
Эти две константы используются не для указания соглашения о вызове, а для привязки при использовании с методами классов. Они не могут использоваться для функций, определенных для модулей. Для любого метода может быть установлен только один из этих флагов.
-
METH_CLASS¶
В качестве первого параметра методу будет передан объект типа, а не экземпляр типа. Это используется для создания классовых методов, аналогичных тем, что создаются при использовании встроенной функции
classmethod()
.
-
METH_STATIC¶
В качестве первого параметра методу будет передан
NULL
, а не экземпляр типа. Это используется для создания статических методов, аналогичных тем, что создаются при использовании встроенной функцииstaticmethod()
.
Еще одна константа управляет тем, загружается ли метод вместо другого определения с тем же именем метода.
-
METH_COEXIST¶
Метод будет загружен вместо существующих определений. Без METH_COEXIST по умолчанию повторяющиеся определения пропускаются. Поскольку слоты-обертки загружаются до таблицы методов, существование слота sq_contains, например, создаст обернутый метод с именем
__contains__()
и исключит загрузку соответствующей PyCFunction с тем же именем. Если флаг определен, PyCFunction будет загружена вместо объекта-обертки и будет сосуществовать со слотом. Это полезно, поскольку вызовы PyCFunctions оптимизируются сильнее, чем вызовы объектов-оберток.
-
PyObject *PyCMethod_New(PyMethodDef *ml, PyObject *self, PyObject *module, PyTypeObject *cls)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI с версии 3.9.
Превращает ml в объект Python callable. Вызывающая сторона должна убедиться, что ml переживет callable. Обычно ml определяется как статическая переменная.
Параметр self при вызове будет передан в качестве аргумента self функции C в
ml->ml_meth
. Параметр self может бытьNULL
.Атрибут callable объекта
__module__
может быть установлен из заданного аргумента module. module должен быть строкой Python, которая будет использоваться в качестве имени модуля, в котором определена функция. Если он недоступен, его можно установить в значениеNone
илиNULL
.См.также
Параметр cls будет передан в качестве аргумента определяющий_класс в функцию C. Должен быть установлен, если
METH_METHOD
установлен наml->ml_flags
.Added in version 3.9.
-
PyObject *PyCFunction_NewEx(PyMethodDef *ml, PyObject *self, PyObject *module)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Эквивалент
PyCMethod_New(ml, self, module, NULL)
.
-
PyObject *PyCFunction_New(PyMethodDef *ml, PyObject *self)¶
- Возвращаемое значение: Новая ссылка. Часть Стабильный ABI с версии 3.4.
Эквивалент
PyCMethod_New(ml, self, NULL, NULL)
.
Доступ к атрибутам типов расширений¶
-
type PyMemberDef¶
- Часть Стабильный ABI (включая всех членов).
Структура, описывающая атрибут типа, который соответствует члену C struct. При определении класса поместите NULL-терминированный массив этих структур в слот
tp_members
.Его полями являются, в порядке убывания:
-
const char *name¶
Имя члена. Значение NULL обозначает конец массива
PyMemberDef[]
.Строка должна быть статичной, ее копия не создается.
-
int type¶
Тип члена в структуре C. Возможные значения см. в разделе Типы участников.
-
Py_ssize_t offset¶
Смещение в байтах, по которому член находится в объектной структуре типа.
-
int flags¶
Ноль или более из Флаги членов, объединенных с помощью побитового ИЛИ.
-
const char *doc¶
Строка документа, или NULL. Строка должна быть статической, ее копия не создается. Обычно она определяется с помощью
PyDoc_STR
.
По умолчанию (когда
flags
равен0
) члены разрешают доступ как для чтения, так и для записи. Для доступа только на чтение используйте флагPy_READONLY
. Некоторые типы, напримерPy_T_STRING
, подразумеваютPy_READONLY
. Удалять можно только членыPy_T_OBJECT_EX
(и унаследованныеT_OBJECT
).Для типов, выделенных из кучи (созданных с помощью
PyType_FromSpec()
или аналогичных),PyMemberDef
может содержать определение специального члена"__vectorcalloffset__"
, соответствующегоtp_vectorcall_offset
в объектах типа. Они должны быть определены с помощьюPy_T_PYSSIZET
иPy_READONLY
, например:static PyMemberDef spam_type_members[] = { {"__vectorcalloffset__", Py_T_PYSSIZET, offsetof(Spam_object, vectorcall), Py_READONLY}, {NULL} /* Sentinel */ };
(Возможно, вам понадобится
#include <stddef.h>
дляoffsetof()
).Унаследованные смещения
tp_dictoffset
иtp_weaklistoffset
можно определить аналогичным образом, используя члены"__dictoffset__"
и"__weaklistoffset__"
, но расширениям настоятельно рекомендуется использовать вместо нихPy_TPFLAGS_MANAGED_DICT
иPy_TPFLAGS_MANAGED_WEAKREF
.Изменено в версии 3.12:
PyMemberDef
доступен всегда. Ранее для этого требовалось включить"structmember.h"
. -
const char *name¶
-
PyObject *PyMember_GetOne(const char *obj_addr, struct PyMemberDef *m)¶
- Часть Стабильный ABI.
Получить атрибут, принадлежащий объекту по адресу obj_addr. Атрибут описывается
PyMemberDef
m. При ошибке возвращаетNULL
.Изменено в версии 3.12:
PyMember_GetOne
доступен всегда. Ранее для этого требовалось включить"structmember.h"
.
-
int PyMember_SetOne(char *obj_addr, struct PyMemberDef *m, PyObject *o)¶
- Часть Стабильный ABI.
Установить атрибут, принадлежащий объекту по адресу obj_addr, на объект o. Устанавливаемый атрибут описывается
PyMemberDef
m. Возвращает0
в случае успеха и отрицательное значение в случае неудачи.Изменено в версии 3.12:
PyMember_SetOne
доступен всегда. Ранее для этого требовалось включить"structmember.h"
.
Флаги членов¶
Следующие флаги могут использоваться с PyMemberDef.flags
:
-
Py_READONLY¶
Не подлежит записи.
-
Py_AUDIT_READ¶
Выдайте
object.__getattr__
audit event перед чтением.
-
Py_RELATIVE_OFFSET¶
Указывает, что
offset
этой записиPyMemberDef
указывает на смещение от данных, специфичных для подкласса, а не отPyObject
.Может использоваться только как часть
Py_tp_members
slot
при создании класса с использованием отрицательногоbasicsize
. В этом случае он является обязательным.Этот флаг используется только в
PyType_Slot
. При установкеtp_members
во время создания класса Python очищает его и устанавливаетPyMemberDef.offset
на смещение из структурыPyObject
.
Изменено в версии 3.10: Макросы RESTRICTED
, READ_RESTRICTED
и WRITE_RESTRICTED
, доступные при использовании #include "structmember.h"
, устарели. READ_RESTRICTED
и RESTRICTED
эквивалентны Py_AUDIT_READ
; WRITE_RESTRICTED
ничего не делает.
Изменено в версии 3.12: Макрос READONLY
был переименован в Py_READONLY
. Макрос PY_AUDIT_READ
был переименован с префиксом Py_
. Новые имена теперь всегда доступны. Ранее для них требовалось #include "structmember.h"
. Заголовок по-прежнему доступен и предоставляет старые имена.
Типы участников¶
PyMemberDef.type
может быть одним из следующих макросов, соответствующих различным типам C. Когда к члену обращаются в Python, он будет преобразован в эквивалентный тип Python. Когда он будет установлен из Python, он будет преобразован обратно к типу C. Если это невозможно, будет вызвано исключение, такое как TypeError
или ValueError
.
Если не отмечено (D), атрибуты, определенные таким образом, не могут быть удалены, например, с помощью del
или delattr()
.
Имя макроса |
Тип C |
Тип Python |
---|---|---|
|
char |
|
|
short |
|
|
int |
|
|
long |
|
|
long long |
|
|
unsigned char |
|
|
unsigned int |
|
|
unsigned short |
|
|
unsigned long |
|
|
unsigned long long |
|
|
||
|
float |
|
|
double |
|
|
char (записывается как 0 или 1) |
|
|
const char* (*) |
|
|
const char[] (*) |
|
|
char (0-127) |
|
|
|
(*): Нуль-терминированная, закодированная в UTF8 строка на языке C. При значении
Py_T_STRING
C-представление является указателем; при значенииPy_T_STRING_INPLACE
строка хранится непосредственно в структуре.(**): Строка длиной 1. Принимается только ASCII.
(RO): Подразумевает
Py_READONLY
.(D): может быть удален, в этом случае указатель устанавливается в
NULL
. Чтение указателяNULL
вызываетAttributeError
.
Added in version 3.12: В предыдущих версиях макросы были доступны только с #include "structmember.h"
и назывались без префикса Py_
(например, как T_INT
). Заголовок по-прежнему доступен и содержит старые имена, а также следующие устаревшие типы:
-
T_OBJECT¶
Как и
Py_T_OBJECT_EX
, ноNULL
преобразуется вNone
. Это приводит к удивительному поведению в Python: удаление атрибута эффективно устанавливает его вNone
.
-
T_NONE¶
Всегда
None
. Должно использоваться сPy_READONLY
.
Определение геттеров и сеттеров¶
-
type PyGetSetDef¶
- Часть Стабильный ABI (включая всех членов).
Структура для определения доступа к типу как к свойству. См. также описание слота
PyTypeObject.tp_getset
.-
const char *name¶
имя атрибута
-
setter set¶
Необязательная C-функция для установки или удаления атрибута. Если
NULL
, атрибут доступен только для чтения.
-
const char *doc¶
необязательная строка документа
-
void *closure¶
Необязательный указатель пользовательских данных, предоставляющий дополнительные данные для getter и setter.
-
const char *name¶
-
typedef PyObject *(*getter)(PyObject*, void*)¶
- Часть Стабильный ABI.
Функция
get
принимает один параметр PyObject* (экземпляр) и указатель пользовательских данных (связанныйclosure
):Он должен возвращать новую ссылку в случае успеха или
NULL
с установленным исключением в случае неудачи.
-
typedef int (*setter)(PyObject*, PyObject*, void*)¶
- Часть Стабильный ABI.
Функции
set
принимают два параметра PyObject* (экземпляр и устанавливаемое значение) и указатель пользовательских данных (связанныйclosure
):В случае, если атрибут должен быть удален, вторым параметром будет
NULL
. Должен возвращать0
в случае успеха или-1
с установленным исключением в случае неудачи.