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

PyObject *Py_GetConstant(unsigned int constant_id)¶

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

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

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

Часть Stable ABI, начиная с версии 3.13.

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

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

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

Часть Stable ABI.

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

Примечание

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

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

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

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

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

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

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

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

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

int PyObject_GetOptionalAttr(PyObject *obj, PyObject *attr_name, PyObject **result);¶

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

Часть Stable ABI, начиная с версии 3.13.

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

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

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

Количество различных имён атрибутов, передаваемых в эту функцию, должно быть небольшим; обычно для этого используется статически выделенная строка в качестве attr_name. Для имён атрибутов, неизвестных на этапе компиляции, предпочтительнее напрямую вызывать PyUnicode_FromString() и PyObject_SetAttr(). Подробнее см. PyUnicode_InternFromString(), который может использоваться внутри для создания объекта ключа.

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

Часть Stable ABI, начиная с версии 3.13.

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

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

Часть Stable ABI, начиная с версии 3.13.

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

Количество различных имён атрибутов, передаваемых в эту функцию, должно быть небольшим; обычно для этого используется статически выделенная строка в качестве attr_name. Для имён атрибутов, неизвестных на этапе компиляции, предпочтительнее напрямую вызывать PyUnicode_FromString() и PyObject_DelAttr(). Подробнее см. PyUnicode_InternFromString(), который может использоваться внутри для создания объекта ключа для поиска.

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

Если аргумент равен NULL, возвращает строку '<NULL>'.

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

PyObject *PyObject_ASCII(PyObject *o)¶

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

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

Если аргумент равен NULL, возвращает строку '<NULL>'.

PyObject *PyObject_Str(PyObject *o)¶

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

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

Если аргумент равен NULL, возвращает строку '<NULL>'.

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

PyObject *PyObject_Bytes(PyObject *o)¶

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

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

Если аргумент равен NULL, возвращает объект bytes b'<NULL>'.

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.

When o is non-NULL, returns a type object corresponding to the object type of object o. On failure, raises SystemError and returns NULL. This is equivalent to the Python expression type(o). This function creates a new strong reference to the return value. There’s really no reason to use this function instead of the Py_TYPE() function, which returns a pointer of type PyTypeObject*, except when a new strong reference is needed.

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].

int PyObject_DelItemString(PyObject *o, const char *key)¶

Часть Stable ABI.

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

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_SelfIter(PyObject *obj)¶

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

This is equivalent to the Python __iter__(self): return self method. It is intended for iterator types, to be used in the PyTypeObject.tp_iter slot.

PyObject *PyObject_GetAIter(PyObject *o)¶

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

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

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

void *PyObject_GetTypeData(PyObject *o, PyTypeObject *cls)¶

Часть Stable ABI начиная с версии 3.12.

Получить указатель на данные, специфичные для подкласса, зарезервированные для cls.

Объект o должен быть экземпляром cls, а cls должен быть создан с использованием отрицательного PyType_Spec.basicsize. Python не проверяет это.

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

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

Py_ssize_t PyType_GetTypeDataSize(PyTypeObject *cls)¶

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