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

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_HasAttr(PyObject *o, PyObject *attr_name)

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

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

Примечание

Исключения, возникающие при вызове методов __getattr__() и __getattribute__(), молча игнорируются. Для корректной обработки ошибок используйте вместо этого 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_GetAttrString().

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

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

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

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

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

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

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().

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)

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

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

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

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(), с помощью экранирующих последовательностей \x, \u или \U. В результате получается строка, похожая на возвращаемую функцией PyObject_Repr() в Python 2. Вызывается встроенной функцией ascii().

PyObject *PyObject_Str(PyObject *o)

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

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

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

PyObject *PyObject_Bytes(PyObject *o)

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

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

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_GetAIter(PyObject *o)

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

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

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