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

PyObject *Py_GetConstant(unsigned int constant_id)

Входит в Стабильный ABI начиная с версии 3.13.

Получить сильную ссылку на константу.

Установить исключение и вернуть 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	()

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

Добавлено в версии 3.13.

Особенность реализации CPython: в CPython все эти константы являются бессмертными.

PyObject *Py_GetConstantBorrowed(unsigned int constant_id)

Входит в Стабильный ABI начиная с версии 3.13.

Аналогично Py_GetConstant(), но возвращает заимствованную ссылку.

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

Ссылка заимствуется у интерпретатора и действительна до его завершения.

Добавлено в версии 3.13.

PyObject *Py_NotImplemented

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

Py_RETURN_NOTIMPLEMENTED

Правильно обрабатывает возврат Py_NotImplemented из функции C (то есть создает новую сильную ссылку на 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; если он задан, выводится str() объекта вместо repr().

int PyObject_HasAttrWithError(PyObject *o, PyObject *attr_name)

Входит в Стабильный ABI начиная с версии 3.13.

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

Добавлено в версии 3.13.

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

Входит в Стабильный ABI начиная с версии 3.13.

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

Добавлено в версии 3.13.

int PyObject_HasAttr(PyObject *o, PyObject *attr_name)

Входит в Стабильный ABI.

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

Примечание

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

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

Входит в Стабильный ABI.

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

Примечание

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

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

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

Получить из объекта o атрибут с именем attr_name. При успешном выполнении возвращает значение атрибута, при ошибке — NULL. Эквивалентное выражение Python: o.attr_name.

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

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

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

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

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

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

Входит в Стабильный ABI начиная с версии 3.13.

Вариант PyObject_GetAttr(), который не вызывает исключение AttributeError, если атрибут не найден.

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

Добавлено в версии 3.13.

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

Входит в Стабильный ABI начиная с версии 3.13.

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

Добавлено в версии 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.

Установить для объекта o значение v атрибута с именем attr_name. При ошибке вызвать исключение и вернуть -1; при успехе вернуть 0. Эквивалентный оператор Python: o.attr_name = v.

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

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

Входит в Стабильный ABI.

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

Если v равен NULL, атрибут удаляется, однако эта возможность объявлена устаревшей в пользу использования PyObject_DelAttrString().

Следует свести к минимуму количество различных имен атрибутов, передаваемых этой функции; обычно для этого в качестве attr_name используют статически выделенную строку. Для имен атрибутов, неизвестных во время компиляции, предпочтительнее напрямую вызывать PyUnicode_FromString() и PyObject_SetAttr(). Дополнительные сведения см. в описании PyUnicode_InternFromString(), которую можно использовать внутри для создания объекта-ключа.

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.

Удалить у объекта o атрибут с именем attr_name. При ошибке возвращает -1. Эквивалентный оператор Python: del o.attr_name.

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

Входит в Стабильный ABI начиная с версии 3.13.

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

Следует свести к минимуму количество различных имен атрибутов, передаваемых этой функции; обычно для этого в качестве attr_name используют статически выделенную строку. Для имен атрибутов, неизвестных во время компиляции, предпочтительнее напрямую вызывать PyUnicode_FromString() и PyObject_DelAttr(). Дополнительные сведения см. в описании PyUnicode_InternFromString(), которую можно использовать внутри для создания объекта-ключа поиска.

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

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

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

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

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

Добавлено в версии 3.3.

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

Входит в Стабильный ABI начиная с версии 3.7.

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

Добавлено в версии 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.

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. Эквивалентное выражение Python: repr(o). Вызывается встроенной функцией repr().

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

PyObject *PyObject_ASCII(PyObject *o)

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

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

PyObject *PyObject_Str(PyObject *o)

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

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

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

PyObject *PyObject_Bytes(PyObject *o)

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

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

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. Эквивалентно выражению Python hash(o).

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

Py_hash_t PyObject_HashNotImplemented(PyObject *o)

Часть стабильного ABI.

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

int PyObject_IsTrue(PyObject *o)

Часть стабильного ABI.

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

int PyObject_Not(PyObject *o)

Часть стабильного ABI.

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

PyObject *PyObject_Type(PyObject *o)

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

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

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. Эквивалентно выражению Python len(o).

Py_ssize_t PyObject_LengthHint(PyObject *o, Py_ssize_t defaultvalue)

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

Добавлено в версии 3.4.

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

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

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

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

Часть стабильного ABI.

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

int PyObject_DelItem(PyObject *o, PyObject *key)

Часть стабильного ABI.

Удаляет из объекта o сопоставление для объекта key. В случае ошибки возвращает -1. Эквивалентно инструкции Python del o[key].

int PyObject_DelItemString(PyObject *o, const char *key)

Часть стабильного ABI.

Аналогична PyObject_DelItem(), но key задаётся в виде строки байтов UTF-8 типа const char*, а не типа PyObject*.

PyObject *PyObject_Dir(PyObject *o)

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

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

PyObject *PyObject_GetIter(PyObject *o)

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

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

PyObject *PyObject_SelfIter(PyObject *obj)

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

Эквивалентна методу Python __iter__(self): return self. Предназначена для типов итераторов и используется в слоте PyTypeObject.tp_iter.

PyObject *PyObject_GetAIter(PyObject *o)

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

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

Добавлено в версии 3.10.

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

Часть стабильного ABI начиная с версии 3.12.

Возвращает указатель на данные, зарезервированные для подкласса cls.

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

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

Добавлено в версии 3.12.

Py_ssize_t PyType_GetTypeDataSize(PyTypeObject *cls)

Часть стабильного ABI начиная с версии 3.12.

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

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

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

В случае ошибки устанавливает исключение и возвращает отрицательное значение.

Добавлено в версии 3.12.

void *PyObject_GetItemData(PyObject *o)

Возвращает указатель на данные отдельного элемента для класса с флагом Py_TPFLAGS_ITEMS_AT_END.

В случае ошибки устанавливает исключение и возвращает NULL. Если у o не установлен флаг Py_TPFLAGS_ITEMS_AT_END, вызывается TypeError.

Добавлено в версии 3.12.

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

Обходит управляемый словарь объекта obj.

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

Добавлено в версии 3.13.

void PyObject_ClearManagedDict(PyObject *obj)

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

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

Добавлено в версии 3.13.