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

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.

Получение атрибута с именем attr_name объекта o. Возвращает значение атрибута при успехе или 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.

Установка значения атрибута 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)

Часть Стабильной 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)

Удаление атрибута 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*.

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. Если словаря нет, возвращает 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.

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

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. TypeError генерируется, если у o нет Py_TPFLAGS_ITEMS_AT_END.

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