Протокол объектов¶Object Protocol

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)¶

Часть Stable ABI.

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

Примечание

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

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

Часть Stable ABI.

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

Примечание

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

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

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

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

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

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

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

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

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

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

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

Часть Stable ABI.

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

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

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

Часть Stable ABI.

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

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

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

Часть Stable ABI.

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

int PyObject_DelAttr(PyObject *o, PyObject *attr_name)¶

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

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

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

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

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

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

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

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

Новое в версии 3.3.

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

Часть Stable 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)¶

Возвращаемое значение: новая ссылка. Часть Stable 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)¶

Часть Stable ABI.

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

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

Часть Stable ABI.

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

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

PyObject *PyObject_Repr(PyObject *o)¶

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

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

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

PyObject *PyObject_ASCII(PyObject *o)¶

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

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

PyObject *PyObject_Str(PyObject *o)¶

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

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

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

PyObject *PyObject_Bytes(PyObject *o)¶

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

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

int PyObject_IsSubclass(PyObject *derived, PyObject *cls)¶

Часть Stable 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)¶

Часть Stable 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)¶

Часть Stable ABI.

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

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

Py_hash_t PyObject_HashNotImplemented(PyObject *o)¶

Часть Stable ABI.

Set a TypeError indicating that type(o) is not hashable and return -1. This function receives special treatment when stored in a tp_hash slot, allowing a type to explicitly indicate to the interpreter that it is not hashable.

int PyObject_IsTrue(PyObject *o)¶

Часть Stable ABI.

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

int PyObject_Not(PyObject *o)¶

Часть Stable ABI.

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

PyObject *PyObject_Type(PyObject *o)¶

Возвращаемое значение: новая ссылка. Часть Stable 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)¶

Часть Stable 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)¶

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

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

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

Часть Stable ABI.

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

int PyObject_DelItem(PyObject *o, PyObject *key)¶

Часть Stable ABI.

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

PyObject *PyObject_Dir(PyObject *o)¶

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

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

PyObject *PyObject_GetIter(PyObject *o)¶

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

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

PyObject *PyObject_GetAIter(PyObject *o)¶

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

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

Новое в версии 3.10.