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

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

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

int PyObject_HasAttr(PyObject *o, PyObject *attr_name): Входит в стабильный 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): Входит в стабильный ABI.
Аналогична PyObject_HasAttr(), но attr_name задаётся как строка байтов в кодировке UTF-8 типа const char*, а не как 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 задаётся как строка байтов в кодировке UTF-8 типа const char*, а не как 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 задаётся как строка байтов в кодировке UTF-8 типа const char*, а не как 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.

Установить для объекта 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): Входит в стабильный ABI начиная с версии 3.13.
Удалить у объекта o атрибут с именем attr_name. В случае ошибки возвращает -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.

Примечание

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

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

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

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

PyObject *PyObject_ASCII(PyObject *o)

Возвращаемое значение: новая ссылка. Входит в стабильный ABI.

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

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

PyObject *PyObject_Str(PyObject *o)

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

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

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

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

PyObject *PyObject_Bytes(PyObject *o)

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

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

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

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 есть метод __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, функция работает как dir() в Python и возвращает имена текущих локальных переменных; в этом случае, если активного кадра выполнения нет, возвращается 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. Исключение 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.

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

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

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

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

Для корректного использования этой функции обычно требуется поддержка со стороны деаллокатора obj (tp_dealloc). Например, следующий набросок можно адаптировать для реализации «weakmap», работающего подобно 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` is safe to use
        PyMutex_Unlock(&mutex);
        return result;
    }
    // if we get here, `result` is starting to be garbage-collected,
    // but has not been removed from the weakmap yet
    PyMutex_Unlock(&mutex);
    return NULL;
}

// tp_dealloc function for weakmap values
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.