Протокол объектов¶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().

void PyObject_Dump(PyObject *op)¶

Выводит дамп объекта op в stderr. Это следует использовать только для отладки.

Вывод предназначен для попытки дампа объектов даже после повреждения памяти:

Информация записывается, начиная с полей, которые с наименьшей вероятностью приведут к сбою при обращении.
Эта функция может быть вызвана без прикреплённого состояния потока, но делать это не рекомендуется: это может привести к взаимоблокировкам.
Объект, не принадлежащий текущему интерпретатору, может быть сброшен, но это также может вызвать сбои или нежелательное поведение.
Реализует эвристику для проверки, была ли освобождена память объекта. В этом случае содержимое объекта не выводится, только его адрес в памяти.
Формат вывода может измениться в любой момент.

Пример вывода:

object address  : 0x7f80124702c0
object refcount : 2
object type     : 0x9902e0
object type name: str
object repr     : 'abcdef'

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

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(), однако в настоящее время нет планов по его удалению.

Функцию нельзя вызывать с NULL v, если уже установлено исключение. Такая ситуация может возникнуть из-за отсутствия проверок NULL и приведёт к удалению атрибута.

Изменено в версии 3.15: Нельзя вызывать со значением NULL, если установлено исключение.

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(), который может использоваться внутри для создания объекта ключа.

Изменено в версии 3.15: Нельзя вызывать со значением NULL, если установлено исключение.

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 в противном случае.

Примечание

Если o1 и o2 – один и тот же объект, PyObject_RichCompareBool() всегда будет возвращать 1 для Py_EQ и 0 для Py_NE.

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

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 есть метод __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.

int PyUnstable_Object_EnableDeferredRefcount(PyObject *obj)¶

Это нестабильное API. Оно может меняться без предупреждения в минорных версиях.

Включает отложенный подсчёт ссылок для obj, если это поддерживается средой выполнения. В сборке со свободными потоками это позволяет интерпретатору избегать корректировки счётчика ссылок для obj, что может повысить производительность в многопоточном режиме. Плата за это – то, что obj будет освобождаться только сборщиком мусора, отслеживающим циклические ссылки, а не в тот момент, когда у интерпретатора больше нет ссылок на него.

Эта функция возвращает 1, если для obj включён отложенный подсчёт ссылок, и 0, если отложенный подсчёт ссылок не поддерживается или подсказка была проигнорирована интерпретатором, например, когда отложенный подсчёт ссылок уже включён для obj. Эта функция потокобезопасна и не может завершиться ошибкой.

Эта функция ничего не делает в сборках с включённым GIL, которые не поддерживают отложенный подсчёт ссылок. Она также ничего не делает, если obj не является объектом, отслеживаемым сборщиком мусора (см. gc.is_tracked() и PyObject_GC_IsTracked()).

Эту функцию предполагается использовать вскоре после создания obj, кодом, который его создаёт, например, в слот tp_new объекта.

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

int PyUnstable_Object_IsUniqueReferencedTemporary(PyObject *obj)¶

Это нестабильное API. Оно может меняться без предупреждения в минорных версиях.

Проверяет, является ли obj уникальным временным объектом. Возвращает 1, если obj известен как уникальный временный объект, и 0 в противном случае. Эта функция не может завершиться ошибкой, но проверка консервативна и может вернуть 0 в некоторых случаях, даже если obj является уникальным временным объектом.

Если объект является уникальным временным, гарантируется, что текущий код содержит единственную ссылку на объект. Для аргументов C-функций следует использовать эту функцию вместо проверки того, равен ли счётчик ссылок 1. Начиная с Python 3.14, интерпретатор внутренне избегает некоторых изменений счётчика ссылок при загрузке объектов на стек операндов путём заимствования ссылок, когда это возможно, что означает, что счётчик ссылок, равный 1, сам по себе не гарантирует, что аргумент функции уникально ссылается на объект.

В примере ниже my_func вызывается с уникальным временным объектом в качестве аргумента:

my_func([1, 2, 3])

В примере ниже my_func не вызывается с уникальным временным объектом в качестве аргумента, даже если его счётчик ссылок равен 1:

my_list = [1, 2, 3]
my_func(my_list)

См. также функцию Py_REFCNT().

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

int PyUnstable_IsImmortal(PyObject *obj)¶: Это нестабильное API. Оно может меняться без предупреждения в минорных версиях.

Эта функция возвращает ненулевое значение, если obj является бессмертным, и ноль в противном случае. Эта функция не может завершиться ошибкой.

Примечание

Объекты, являющиеся бессмертными в одной версии CPython, не гарантированно являются бессмертными в другой.

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

int PyUnstable_TryIncRef(PyObject *obj)¶

Это нестабильное API. Оно может меняться без предупреждения в минорных версиях.

Увеличивает счётчик ссылок obj, если он не равен нулю. Возвращает 1, если счётчик ссылок объекта был успешно увеличен. В противном случае эта функция возвращает 0.

PyUnstable_EnableTryIncRef() должна была быть вызвана ранее для obj, иначе эта функция может ложно вернуть 0 в сборке со свободными потоками.

Эта функция логически эквивалентна следующему коду на C, за исключением того, что она ведёт себя атомарно в сборке со свободными потоками:

if (Py_REFCNT(op) > 0) {
   Py_INCREF(op);
   return 1;
}
return 0;

Предназначен как строительный блок для управления слабыми ссылками без накладных расходов объекта слабой ссылки Python.

Обычно правильное использование этой функции требует поддержки со стороны деаллокатора obj (tp_dealloc). Например, следующий набросок можно адаптировать для реализации «слабого словаря», работающего как WeakValueDictionary для конкретного типа:

PyMutex mutex;

PyObject *
add_entry(weakmap_key_type *key, PyObject *value)
{
    PyUnstable_EnableTryIncRef(value);
    weakmap_type weakmap = ...;
    PyMutex_Lock(&mutex);
    weakmap_add_entry(weakmap, key, value);
    PyMutex_Unlock(&mutex);
    Py_RETURN_NONE;
}

PyObject *
get_value(weakmap_key_type *key)
{
    weakmap_type weakmap = ...;
    PyMutex_Lock(&mutex);
    PyObject *result = weakmap_find(weakmap, key);
    if (PyUnstable_TryIncRef(result)) {
        // `result` можно безопасно использовать
        PyMutex_Unlock(&mutex);
        return result;
    }
    // если мы попали сюда, `result` начинает собираться сборщиком мусора,
    // но ещё не удалён из weakmap
    PyMutex_Unlock(&mutex);
    return NULL;
}

// Функция tp_dealloc для значений weakmap
void
value_dealloc(PyObject *value)
{
    weakmap_type weakmap = ...;
    PyMutex_Lock(&mutex);
    weakmap_remove_value(weakmap, value);

    ...
    PyMutex_Unlock(&mutex);
}

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

void PyUnstable_EnableTryIncRef(PyObject *obj)¶: Это нестабильное API. Оно может меняться без предупреждения в минорных версиях.

Включает последующее использование PyUnstable_TryIncRef() на obj. Вызывающий должен удерживать сильную ссылку на obj при вызове этой функции.

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

int PyUnstable_Object_IsUniquelyReferenced(PyObject *op)¶

Это нестабильное API. Оно может меняться без предупреждения в минорных версиях.

Определяет, имеет ли op только одну ссылку.

В сборках с GIL эта функция эквивалентна Py_REFCNT(op) == 1.

В сборке со свободной многопоточностью эта функция проверяет, равен ли op счётчик ссылок единице, и дополнительно проверяет, используется ли op только этим потоком. Py_REFCNT(op) == 1 не является потокобезопасным в сборках со свободной многопоточностью; предпочтительнее использовать эту функцию.

Вызывающий должен удерживать присоединённое состояние потока, несмотря на то, что эта функция не вызывает интерпретатор Python. Эта функция не может завершиться ошибкой.

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

int PyUnstable_SetImmortal(PyObject *op)¶

Это нестабильное API. Оно может меняться без предупреждения в минорных версиях.

Помечает объект op как бессмертный. Вызывающий поток должен быть единственным, кто ссылается на аргумент. Эта функция предназначена для уменьшения конкуренции за счётчик ссылок в сборке со свободной многопоточностью для объектов, совместно используемых потоками.

Это однонаправленный процесс: объекты можно только сделать бессмертными; их нельзя снова сделать смертными. Бессмертные объекты не участвуют в подсчёте ссылок и никогда не будут собраны сборщиком мусора. Если объект отслеживается сборщиком мусора (GC), он перестаёт отслеживаться.

Эту функцию следует использовать вскоре после создания op, кодом, который его создаёт, например, в слоте tp_new объекта. Возвращает 1, если объект был сделан бессмертным, и 0 в противном случае. Эта функция не может завершиться ошибкой.

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