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

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

Следует ограничивать количество различных имён атрибутов, передаваемых этой функции; обычно для этого в качестве 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)

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

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

То же, что и 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. Полученная строка похожа на строку, возвращаемую 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 — кортеж, проверка выполняется для каждого его элемента. Результат будет 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 — кортеж, проверка выполняется для каждого его элемента. Результат будет 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.

Удаляет сопоставление объекта key с объектом o. В случае ошибки возвращает -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.