Протокол объекта

PyObject *Py_GetConstant(unsigned int constant_id)

Часть Стабильный ABI с версии 3.13.

Приведите strong reference к константе.

Установите исключение и верните NULL, если constant_id недействителен.

constant_id должен быть одним из этих идентификаторов констант:

Постоянный идентификатор	Значение	Возвращаемый объект
Py_CONSTANT_NONE	0	None
Py_CONSTANT_FALSE	1	False
Py_CONSTANT_TRUE	2	True
Py_CONSTANT_ELLIPSIS	3	Ellipsis
Py_CONSTANT_NOT_IMPLEMENTED	4	NotImplemented
Py_CONSTANT_ZERO	5	0
Py_CONSTANT_ONE	6	1
Py_CONSTANT_EMPTY_STR	7	''
Py_CONSTANT_EMPTY_BYTES	8	b''
Py_CONSTANT_EMPTY_TUPLE	9	()

Числовые значения приводятся только для проектов, которые не могут использовать постоянные идентификаторы.

Added in version 3.13.

Детали реализации CPython: В CPython все эти константы имеют значение immortal.

PyObject *Py_GetConstantBorrowed(unsigned int constant_id)

Часть Стабильный ABI с версии 3.13.

Аналогично Py_GetConstant(), но возвращает borrowed reference.

Эта функция предназначена в первую очередь для обратной совместимости: для нового кода рекомендуется использовать Py_GetConstant().

Ссылка заимствуется из интерпретатора и действует до завершения работы интерпретатора. … versionadded:: 3.13

PyObject *Py_NotImplemented

Синглтон NotImplemented, используемый для сигнализации о том, что операция не реализована для данной комбинации типов.

Py_RETURN_NOTIMPLEMENTED

Правильно обрабатывайте возврат Py_NotImplemented внутри функции C (то есть создавайте новые strong reference - NotImplemented и возвращайте их).

Py_PRINT_RAW

Флаг для использования с несколькими функциями, печатающими объект (например, PyObject_Print() и PyFile_WriteObject()). Если флаг передан, эти функции будут использовать str() объекта вместо repr().

int PyObject_Print(PyObject *o, FILE *fp, int flags)

Печать объекта o в файл fp. При ошибке возвращает -1. Аргумент flags используется для включения определенных опций печати. В настоящее время поддерживается только параметр Py_PRINT_RAW; если он задан, то вместо repr() записывается str() объекта.

int PyObject_HasAttrWithError(PyObject *o, const char *attr_name)

Часть Стабильный ABI с версии 3.13.

Возвращает 1, если o имеет атрибут attr_name, и 0 в противном случае. Это эквивалентно выражению hasattr(o, attr_name) в Python. В случае неудачи возвращается -1.

Added in version 3.13.

int PyObject_HasAttrStringWithError(PyObject *o, const char *attr_name)

Часть Стабильный ABI с версии 3.13.

Это то же самое, что и PyObject_HasAttrWithError(), но attr_name указывается как const char*. байтовой строки в кодировке UTF-8, а не PyObject*.

Added in version 3.13.

int PyObject_HasAttr(PyObject *o, PyObject *attr_name)

Часть Стабильный ABI.

Возвращает 1, если o имеет атрибут attr_name, и 0 в противном случае. Эта функция всегда успешна.

Примечание

Исключения, возникающие при вызове методов __getattr__() и __getattribute__(), молча игнорируются. Для правильной обработки ошибок используйте вместо них методы PyObject_HasAttrWithError(), PyObject_GetOptionalAttr() или PyObject_GetAttr().

int PyObject_HasAttrString(PyObject *o, const char *attr_name)

Часть Стабильный ABI.

Это то же самое, что и PyObject_HasAttr(), но attr_name указывается как const char*. байтовой строки в кодировке UTF-8, а не PyObject*.

Примечание

Исключения, возникающие при вызове методов __getattr__() и __getattribute__() или при создании временного объекта str, молча игнорируются. Для правильной обработки ошибок используйте вместо этого PyObject_HasAttrStringWithError(), PyObject_GetOptionalAttrString() или PyObject_GetAttrString().

PyObject *PyObject_GetAttr(PyObject *o, PyObject *attr_name)

Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.

Получение атрибута с именем attr_name из объекта o. Возвращает значение атрибута в случае успеха или NULL в случае неудачи. Это эквивалентно выражению o.attr_name в Python.

Если отсутствующий атрибут не должен рассматриваться как сбой, вместо него можно использовать PyObject_GetOptionalAttr().

PyObject *PyObject_GetAttrString(PyObject *o, const char *attr_name)

Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.

Это то же самое, что и PyObject_GetAttr(), но attr_name указывается как const char*. байтовой строки в кодировке UTF-8, а не PyObject*.

Если отсутствующий атрибут не должен рассматриваться как сбой, вместо него можно использовать PyObject_GetOptionalAttrString().

int PyObject_GetOptionalAttr(PyObject *obj, PyObject *attr_name, PyObject **result);

Часть Стабильный ABI с версии 3.13.

Вариант PyObject_GetAttr(), который не поднимает AttributeError, если атрибут не найден.

Если атрибут найден, верните 1 и установите *результат в новый strong reference для атрибута. Если атрибут не найден, верните 0 и установите *результат в NULL; AttributeError затихает. Если возникла ошибка, отличная от AttributeError, верните -1 и установите *результат в NULL.

Added in version 3.13.

int PyObject_GetOptionalAttrString(PyObject *obj, const char *attr_name, PyObject **result);

Часть Стабильный ABI с версии 3.13.

Это то же самое, что и PyObject_GetOptionalAttr(), но attr_name указывается как const char*. байтовой строки в кодировке UTF-8, а не PyObject*.

Added in version 3.13.

PyObject *PyObject_GenericGetAttr(PyObject *o, PyObject *name)

Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.

Общая функция получения атрибутов, предназначенная для размещения в слоте tp_getattro объекта типа. Она ищет дескриптор в словаре классов в MRO объекта, а также атрибут в __dict__ объекта (если он есть). Как указано в Реализация дескрипторов, дескрипторы данных имеют предпочтение перед атрибутами экземпляра, а дескрипторы, не содержащие данных, - нет. В противном случае возникает ошибка AttributeError.

int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v)

Часть Стабильный ABI.

Установите значение атрибута с именем attr_name для объекта o в значение v. Вызывает исключение и возвращает -1 при неудаче; возвращает 0 при успехе. Это эквивалентно выражению o.attr_name = v в языке Python.

Если v равно NULL, атрибут удаляется. Это поведение устарело в пользу использования PyObject_DelAttr(), но в настоящее время его не планируется удалять.

int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v)

Часть Стабильный ABI.

Это то же самое, что и PyObject_SetAttr(), но attr_name указывается как const char*. байтовой строки в кодировке UTF-8, а не PyObject*.

Если v равно NULL, атрибут будет удален, но эта функция устарела в пользу использования PyObject_DelAttrString().

int PyObject_GenericSetAttr(PyObject *o, PyObject *name, PyObject *value)

Часть Стабильный ABI.

Общая функция установки и удаления атрибутов, предназначенная для размещения в слоте tp_setattro объекта типа. Она ищет дескриптор данных в словаре классов в MRO объекта, и если находит, то отдает предпочтение установке или удалению атрибута в словаре экземпляров. В противном случае атрибут устанавливается или удаляется в __dict__ объекта (если он есть). В случае успеха возвращается 0, в противном случае возникает ошибка AttributeError и возвращается -1.

int PyObject_DelAttr(PyObject *o, PyObject *attr_name)

Часть Стабильный ABI с версии 3.13.

Удаление атрибута с именем attr_name для объекта o. Возвращает -1 при неудаче. Это эквивалентно выражению del o.attr_name в языке Python.

int PyObject_DelAttrString(PyObject *o, const char *attr_name)

Часть Стабильный ABI с версии 3.13.

Это то же самое, что и PyObject_DelAttr(), но attr_name указывается как const char*. байтовой строки в кодировке UTF-8, а не PyObject*.

PyObject *PyObject_GenericGetDict(PyObject *o, void *context)

Возвращаемое значение: Новая ссылка. Часть Стабильный ABI с версии 3.10.

Общая реализация для геттера дескриптора __dict__. При необходимости он создает словарь.

Эта функция также может быть вызвана для получения __dict__ объекта o. При вызове передавайте NULL для контекста. Поскольку этой функции может потребоваться выделение памяти для словаря, более эффективным будет вызов PyObject_GetAttr() при обращении к атрибуту объекта.

В случае неудачи возвращается NULL с набором исключений.

Added in version 3.3.

int PyObject_GenericSetDict(PyObject *o, PyObject *value, void *context)

Часть Стабильный ABI с версии 3.7.

Общая реализация для сеттера дескриптора __dict__. Эта реализация не позволяет удалять словарь.

Added in version 3.3.

PyObject **_PyObject_GetDictPtr(PyObject *obj)

Возвращает указатель на __dict__ объекта obj. Если нет __dict__, верните NULL, не устанавливая исключения.

Этой функции может потребоваться выделение памяти для словаря, поэтому при обращении к атрибуту объекта эффективнее вызывать PyObject_GetAttr().

PyObject *PyObject_RichCompare(PyObject *o1, PyObject *o2, int opid)

Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.

Сравните значения o1 и o2, используя операцию, указанную opid, которая должна быть одной из Py_LT, Py_LE, Py_EQ, Py_NE, Py_GT или Py_GE, соответствующих <, <=, ==, !=, > или >= соответственно. Это эквивалентно выражению Python o1 op o2, где op - оператор, соответствующий opid. Возвращает значение сравнения в случае успеха или NULL в случае неудачи.

int PyObject_RichCompareBool(PyObject *o1, PyObject *o2, int opid)

Часть Стабильный ABI.

Сравнивает значения o1 и o2 с помощью операции, указанной opid, как PyObject_RichCompare(), но возвращает -1 при ошибке, 0, если результат ложный, 1 в противном случае.

Примечание

Если o1 и o2 - один и тот же объект, PyObject_RichCompareBool() всегда будет возвращать 1 для Py_EQ и 0 для Py_NE.

PyObject *PyObject_Format(PyObject *obj, PyObject *format_spec)

Часть Стабильный ABI.

Отформатируйте obj с помощью format_spec. Это эквивалентно выражению Python format(obj, format_spec).

format_spec может иметь значение NULL. В этом случае вызов эквивалентен format(obj). Возвращает отформатированную строку при успехе, NULL при неудаче.

PyObject *PyObject_Repr(PyObject *o)

Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.

Вычислите строковое представление объекта o. При успехе возвращает строковое представление, при неудаче - NULL. Это эквивалентно выражению repr(o) в Python. Вызывается встроенной функцией repr().

Изменено в версии 3.4: Эта функция теперь включает отладочное утверждение, чтобы гарантировать, что она не будет молча отбрасывать активное исключение.

PyObject *PyObject_ASCII(PyObject *o)

Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.

Как и PyObject_Repr(), вычислите строковое представление объекта o, но экранируйте символы, не относящиеся к ASCII, в строке, возвращаемой PyObject_Repr(), с помощью \x, \u или \U эскейпов. Получается строка, аналогичная той, что возвращает PyObject_Repr() в Python 2. Вызывается встроенной функцией ascii().

PyObject *PyObject_Str(PyObject *o)

Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.

Вычислите строковое представление объекта o. При успехе возвращает строковое представление, при неудаче - NULL. Это эквивалентно выражению str(o) в Python. Вызывается встроенной функцией str() и, следовательно, функцией print().

Изменено в версии 3.4: Эта функция теперь включает отладочное утверждение, чтобы гарантировать, что она не будет молча отбрасывать активное исключение.

PyObject *PyObject_Bytes(PyObject *o)

Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.

Вычислить байтовое представление объекта o. В случае неудачи возвращается NULL, а в случае успеха - байтовый объект. Это эквивалентно выражению Python bytes(o), когда o не является целым числом. В отличие от bytes(o), когда o является целым числом, а не нуль-инициализированным объектом bytes, возникает ошибка типа TypeError.

int PyObject_IsSubclass(PyObject *derived, PyObject *cls)

Часть Стабильный ABI.

Верните 1, если класс derived идентичен или производен от класса cls, в противном случае верните 0. В случае ошибки возвращается -1.

Если cls - кортеж, то проверка будет выполнена для каждой записи в cls. Результатом будет 1, если хотя бы одна из проверок вернет 1, иначе - 0.

Если у cls есть метод __subclasscheck__(), он будет вызван для определения статуса подкласса, как описано в PEP 3119. В противном случае derived является подклассом cls, если он является прямым или косвенным подклассом, т. е. содержится в cls.__mro__.

Обычно классами считаются только объекты классов, то есть экземпляры type или производного класса. Однако объекты могут отменить это, имея атрибут __bases__ (который должен быть кортежем базовых классов).

int PyObject_IsInstance(PyObject *inst, PyObject *cls)

Часть Стабильный ABI.

Возвращает 1, если inst является экземпляром класса cls или подкласса cls, или 0, если нет. При ошибке возвращается -1 и устанавливается исключение.

Если cls - кортеж, то проверка будет выполнена для каждой записи в cls. Результатом будет 1, если хотя бы одна из проверок вернет 1, иначе - 0.

Если у cls есть метод __instancecheck__(), он будет вызван для определения статуса подкласса, как описано в PEP 3119. В противном случае inst является экземпляром cls, если его класс является подклассом cls.

Экземпляр inst может переопределить то, что считается его классом, имея атрибут __class__.

Объект cls может переопределить, считается ли он классом и каковы его базовые классы, с помощью атрибута __bases__ (который должен представлять собой кортеж базовых классов).

Py_hash_t PyObject_Hash(PyObject *o)

Часть Стабильный ABI.

Вычислите и верните хэш-значение объекта o. В случае неудачи возвращается -1. Это эквивалентно выражению hash(o) в Python.

Изменено в версии 3.2: Возвращаемый тип теперь Py_hash_t. Это знаковое целое число того же размера, что и Py_ssize_t.

Py_hash_t PyObject_HashNotImplemented(PyObject *o)

Часть Стабильный ABI.

Установите TypeError, указывающий на то, что type(o) не является hashable, и верните -1. Эта функция получает особое обращение, когда хранится в слоте tp_hash, позволяя типу явно указать интерпретатору, что он не является хэшируемым.

int PyObject_IsTrue(PyObject *o)

Часть Стабильный ABI.

Возвращает 1, если объект o считается истинным, и 0 в противном случае. Это эквивалентно выражению not not o в Python. В случае неудачи возвращается -1.

int PyObject_Not(PyObject *o)

Часть Стабильный ABI.

Возвращает 0, если объект o считается истинным, и 1 в противном случае. Это эквивалентно выражению not o в Python. В случае неудачи возвращается -1.

PyObject *PyObject_Type(PyObject *o)

Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.

Если o не``NULL``, возвращает объект типа, соответствующего типу объекта o. В случае неудачи вызывает SystemError и возвращает NULL. Это эквивалентно выражению type(o) в Python. Эта функция создает новый strong reference для возвращаемого значения. На самом деле нет причин использовать эту функцию вместо функции Py_TYPE(), которая возвращает указатель типа PyTypeObject*, за исключением случаев, когда требуется новый strong reference.

int PyObject_TypeCheck(PyObject *o, PyTypeObject *type)

Возвращает ненулевое значение, если объект o имеет тип type или подтип type, и 0 в противном случае. Оба параметра должны быть не``NULL``.

Py_ssize_t PyObject_Size(PyObject *o)

Py_ssize_t PyObject_Length(PyObject *o)

Часть Стабильный ABI.

Возвращает длину объекта o. Если объект o предоставляет протоколы последовательности и отображения, возвращается длина последовательности. При ошибке возвращается -1. Это эквивалентно выражению len(o) в Python.

Py_ssize_t PyObject_LengthHint(PyObject *o, Py_ssize_t defaultvalue)

Возвращает оценочную длину для объекта o. Сначала попробуйте вернуть его фактическую длину, затем оценочную, используя __length_hint__(), и, наконец, верните значение по умолчанию. При ошибке возвращается -1. Это эквивалентно выражению operator.length_hint(o, defaultvalue) в Python.

Added in version 3.4.

PyObject *PyObject_GetItem(PyObject *o, PyObject *key)

Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.

Возвращает элемент o, соответствующий объекту key, или NULL при неудаче. Это эквивалентно выражению o[key] в Python.

int PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v)

Часть Стабильный ABI.

Сопоставьте объект key со значением v. При неудаче вызывает исключение и возвращает -1; при успехе возвращает 0. Это эквивалентно выражению o[key] = v в Python. Эта функция не крадет ссылку на v.

int PyObject_DelItem(PyObject *o, PyObject *key)

Часть Стабильный ABI.

Удалить отображение для объекта key из объекта o. При неудаче возвращается -1. Это эквивалентно выражению del o[key] в языке Python.

PyObject *PyObject_Dir(PyObject *o)

Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.

Это эквивалентно выражению Python dir(o), возвращающему (возможно, пустой) список строк, соответствующих аргументу object, или NULL, если произошла ошибка. Если аргумент равен NULL, то это похоже на выражение Python dir(), возвращающее имена текущих локалей; в этом случае, если ни один кадр выполнения не активен, возвращается NULL, а PyErr_Occurred() вернет false.

PyObject *PyObject_GetIter(PyObject *o)

Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.

Это эквивалентно выражению iter(o) в Python. Возвращает новый итератор для аргумента object или сам объект, если объект уже является итератором. Вызывает TypeError и возвращает NULL, если объект не может быть итератором.

PyObject *PyObject_GetAIter(PyObject *o)

Возвращаемое значение: Новая ссылка. Часть Стабильный ABI с версии 3.10.

Это эквивалентно выражению aiter(o) в Python. Принимает объект AsyncIterable и возвращает для него AsyncIterator. Обычно это новый итератор, но если аргументом является AsyncIterator, он возвращает сам себя. Вызывает TypeError и возвращает NULL, если объект не может быть итерирован.

Added in version 3.10.

void *PyObject_GetTypeData(PyObject *o, PyTypeObject *cls)

Часть Стабильный ABI с версии 3.12.

Получает указатель на данные, специфичные для подкласса, зарезервированные для cls.

Объект o должен быть экземпляром cls, а cls должен быть создан с помощью отрицательного PyType_Spec.basicsize. Python не проверяет это.

При ошибке установите исключение и верните NULL.

Added in version 3.12.

Py_ssize_t PyType_GetTypeDataSize(PyTypeObject *cls)

Часть Стабильный ABI с версии 3.12.

Возвращает размер пространства памяти экземпляра, зарезервированного для cls, то есть размер возвращаемой памяти PyObject_GetTypeData().

Этот размер может быть больше, чем при использовании -PyType_Spec.basicsize; безопасно использовать этот больший размер (например, с помощью memset()).

Тип cls должен быть создан с помощью отрицательного PyType_Spec.basicsize. Python не проверяет это.

При ошибке создайте исключение и верните отрицательное значение.

Added in version 3.12.

void *PyObject_GetItemData(PyObject *o)

Получите указатель на данные по каждому элементу для класса с Py_TPFLAGS_ITEMS_AT_END.

При ошибке устанавливается исключение и возвращается NULL. TypeError поднимается, если у o не установлен Py_TPFLAGS_ITEMS_AT_END.

Added in version 3.12.

int PyObject_VisitManagedDict(PyObject *obj, visitproc visit, void *arg)

Посетите управляемый словарь obj.

Эта функция должна вызываться только в функции траверса того типа, у которого установлен флаг Py_TPFLAGS_MANAGED_DICT.

Added in version 3.13.

void PyObject_ClearManagedDict(PyObject *obj)

Очистить управляемый словарь obj.

Эта функция должна вызываться только в функции траверса того типа, у которого установлен флаг Py_TPFLAGS_MANAGED_DICT.

Added in version 3.13.