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

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 указан как const char* строка UTF-8, а не как PyObject*.

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

int PyObject_HasAttr(PyObject *o, PyObject *attr_name)

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

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

Примечание

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

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

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

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

Примечание

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

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

Значение возврата: Новая ссылка. Часть Стабильной ABI.

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

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

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

Значение возврата: Новая ссылка. Часть Стабильной ABI.

Это то же самое, что и PyObject_GetAttr(), но attr_name задаётся как строка const char* в кодировке UTF-8, а не как 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 задаётся как строка const char* в кодировке UTF-8, а не как 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.

Установка значения атрибута с именем 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 задаётся как строка const char* в кодировке UTF-8, а не как 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.

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

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.

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

PyObject *PyObject_Dir(PyObject *o)

Значение возврата: Новая ссылка. Часть Стабильного ABI.

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

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.

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.