> **Источник:** https://python-all.ru/3.10/c-api/refcounting.html
>
> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.

---

# Подсчёт ссылок

Макросы в этом разделе используются для управления счётчиками ссылок на объекты Python.

#### `void Py_INCREF(PyObject *o)`

Указывает на создание новой [сильной ссылки](https://python-all.ru/3.10/glossary.html#term-strong-reference) на объект *o*, показывая, что он используется и не должен быть уничтожен.

Эта функция обычно используется для преобразования [заимствованной ссылки](https://python-all.ru/3.10/glossary.html#term-borrowed-reference) в [сильную ссылку](https://python-all.ru/3.10/glossary.html#term-strong-reference) на месте. Функция [`Py_NewRef()`](https://python-all.ru/3.10/c-api/refcounting.html#c.Py_NewRef) может использоваться для создания новой [сильной ссылки](https://python-all.ru/3.10/glossary.html#term-strong-reference).

Когда объект больше не нужен, освободите его, вызвав [`Py_DECREF()`](https://python-all.ru/3.10/c-api/refcounting.html#c.Py_DECREF).

Объект не должен быть `NULL`; если нет уверенности, что он не `NULL`, используйте [`Py_XINCREF()`](https://python-all.ru/3.10/c-api/refcounting.html#c.Py_XINCREF).

Не следует ожидать, что эта функция действительно изменит *o* каким-либо образом.

#### `void Py_XINCREF(PyObject *o)`

Аналогично [`Py_INCREF()`](https://python-all.ru/3.10/c-api/refcounting.html#c.Py_INCREF), но объект *o* может быть `NULL`, в этом случае функция не действует.

См. также [`Py_XNewRef()`](https://python-all.ru/3.10/c-api/refcounting.html#c.Py_XNewRef).

#### `PyObject *Py_NewRef(PyObject *o)`

*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable) начиная с версии 3.10.*

Создаёт новую [сильную ссылку](https://python-all.ru/3.10/glossary.html#term-strong-reference) на объект: вызывает [`Py_INCREF()`](https://python-all.ru/3.10/c-api/refcounting.html#c.Py_INCREF) для *o* и возвращает объект *o*.

Когда [сильная ссылка](https://python-all.ru/3.10/glossary.html#term-strong-reference) больше не нужна, для её освобождения следует вызвать [`Py_DECREF()`](https://python-all.ru/3.10/c-api/refcounting.html#c.Py_DECREF).

Объект *o* не должен быть `NULL`; используйте [`Py_XNewRef()`](https://python-all.ru/3.10/c-api/refcounting.html#c.Py_XNewRef), если *o* может быть `NULL`.

Например:

```c
Py_INCREF(obj);
self->attr = obj;
```

можно записать как:

```c
self->attr = Py_NewRef(obj);
```

См. также [`Py_INCREF()`](https://python-all.ru/3.10/c-api/refcounting.html#c.Py_INCREF).

Новое в версии 3.10.

#### `PyObject *Py_XNewRef(PyObject *o)`

*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable) начиная с версии 3.10.*

Аналогично [`Py_NewRef()`](https://python-all.ru/3.10/c-api/refcounting.html#c.Py_NewRef), но объект *o* может быть NULL.

Если объект *o* равен `NULL`, функция просто возвращает `NULL`.

Новое в версии 3.10.

#### `void Py_DECREF(PyObject *o)`

Освобождает [сильную ссылку](https://python-all.ru/3.10/glossary.html#term-strong-reference) на объект *o*, показывая, что ссылка больше не используется.

Когда последняя [сильная ссылка](https://python-all.ru/3.10/glossary.html#term-strong-reference) освобождена (т.е. счётчик ссылок объекта достигает 0), вызывается функция освобождения типа объекта (которая не должна быть `NULL`).

Эта функция обычно используется для удаления [сильной ссылки](https://python-all.ru/3.10/glossary.html#term-strong-reference) перед выходом из области видимости.

Объект не должен быть `NULL`; если нет уверенности, что он не `NULL`, используйте [`Py_XDECREF()`](https://python-all.ru/3.10/c-api/refcounting.html#c.Py_XDECREF).

Не следует ожидать, что эта функция действительно изменит *o* каким-либо образом.

> **Предупреждение**
>
> Функция освобождения может вызвать выполнение произвольного кода Python (например, при освобождении экземпляра класса с методом `__del__()`). Хотя исключения в таком коде не распространяются, выполняемый код имеет свободный доступ ко всем глобальным переменным Python. Это означает, что любой объект, достижимый из глобальной переменной, должен находиться в согласованном состоянии перед вызовом [`Py_DECREF()`](https://python-all.ru/3.10/c-api/refcounting.html#c.Py_DECREF). Например, код, удаляющий объект из списка, должен скопировать ссылку на удаляемый объект во временную переменную, обновить структуру данных списка, а затем вызвать [`Py_DECREF()`](https://python-all.ru/3.10/c-api/refcounting.html#c.Py_DECREF) для временной переменной.

#### `void Py_XDECREF(PyObject *o)`

Аналогично [`Py_DECREF()`](https://python-all.ru/3.10/c-api/refcounting.html#c.Py_DECREF), но объект *o* может быть `NULL`, в этом случае функция не имеет эффекта. Предупреждение из [`Py_DECREF()`](https://python-all.ru/3.10/c-api/refcounting.html#c.Py_DECREF) применимо и здесь.

#### `void Py_CLEAR(PyObject *o)`

Освобождает [сильную ссылку](https://python-all.ru/3.10/glossary.html#term-strong-reference) на объект *o*. Объект может быть `NULL`, в этом случае макрос не имеет эффекта; в противном случае эффект такой же, как для [`Py_DECREF()`](https://python-all.ru/3.10/c-api/refcounting.html#c.Py_DECREF), за исключением того, что аргумент также устанавливается в `NULL`. Предупреждение для [`Py_DECREF()`](https://python-all.ru/3.10/c-api/refcounting.html#c.Py_DECREF) не применяется к переданному объекту, потому что макрос осторожно использует временную переменную и устанавливает аргумент в `NULL` перед освобождением ссылки.

Рекомендуется использовать этот макрос всякий раз, когда освобождается ссылка на объект, который может быть обойдён во время сборки мусора.

#### `void Py_IncRef(PyObject *o)`

*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*

Указывает на получение новой [сильной ссылки](https://python-all.ru/3.10/glossary.html#term-strong-reference) на объект *o*. Функциональная версия [`Py_XINCREF()`](https://python-all.ru/3.10/c-api/refcounting.html#c.Py_XINCREF). Может использоваться для динамического встраивания Python во время выполнения.

#### `void Py_DecRef(PyObject *o)`

*Часть [Stable ABI](https://python-all.ru/3.10/c-api/stable.html#stable).*

Освобождает [сильную ссылку](https://python-all.ru/3.10/glossary.html#term-strong-reference) на объект *o*. Функциональная версия [`Py_XDECREF()`](https://python-all.ru/3.10/c-api/refcounting.html#c.Py_XDECREF). Может использоваться для динамического встраивания Python во время выполнения.

Следующие функции или макросы предназначены только для использования в ядре интерпретатора: `_Py_Dealloc()`, `_Py_ForgetReference()`, `_Py_NewReference()`, а также глобальная переменная `_Py_RefTotal`.