weakref – Слабые ссылки¶weakref – Weak references

Исходный код: Lib/weakref.py

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

В дальнейшем под термином referent понимается объект, на который указывает слабая ссылка.

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

Основное применение слабых ссылок – реализация кэшей или отображений, содержащих большие объекты, когда требуется, чтобы большой объект не оставался в живых только потому, что он присутствует в кэше или отображении.

Например, если у вас есть несколько больших бинарных объектов-изображений, вы можете захотеть связать имя с каждым. Если вы используете словарь Python для отображения имён на изображения или изображений на имена, объекты-изображения будут оставаться живыми только потому, что они присутствуют как значения или ключи в словарях. Классы WeakKeyDictionary и WeakValueDictionary, предоставляемые модулем weakref, являются альтернативой: они используют слабые ссылки для построения отображений, которые не сохраняют объекты живыми только из-за их присутствия в объектах-отображениях. Если, например, объект-изображение является значением в WeakValueDictionary, то, когда последние оставшиеся ссылки на этот объект-изображение являются слабыми ссылками, хранящимися в слабых отображениях, сборщик мусора может переработать объект, и соответствующие записи в слабых отображениях просто удаляются.

WeakKeyDictionary и WeakValueDictionary используют слабые ссылки в своей реализации, устанавливая функции обратного вызова на слабые ссылки, которые уведомляют слабые словари, когда ключ или значение были переработаны сборщиком мусора. WeakSet реализует интерфейс set, но хранит слабые ссылки на свои элементы, подобно тому, как это делает WeakKeyDictionary.

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

Большинству программ должно быть достаточно использования одного из этих типов слабых контейнеров или finalize – обычно нет необходимости создавать собственные слабые ссылки напрямую. Низкоуровневые механизмы предоставляются модулем weakref для продвинутого использования.

Не все объекты могут быть слабо ссылаемыми. Объекты, поддерживающие слабые ссылки, включают экземпляры классов, функции, написанные на Python (но не на C), методы экземпляров, множества, неизменяемые множества, некоторые файловые объекты, генераторы, объекты типов, сокеты, массивы, двусторонние очереди, объекты шаблонов регулярных выражений и объекты кода.

Некоторые встроенные типы, такие как list и dict, не поддерживают напрямую слабые ссылки, но могут добавить поддержку через наследование:

class Dict(dict):
    pass

obj = Dict(red=1, green=2, blue=3)   # этот объект поддерживает слабые ссылки

Расширяемые типы можно легко научить поддерживать слабые ссылки; см. Поддержка слабых ссылок.

Когда для данного типа определены __slots__, поддержка слабых ссылок отключается, если в последовательности строк в объявлении __slots__ также не присутствует строка '__weakref__'. Подробнее см. документацию __slots__.

class weakref.ref(object[, callback])¶

Возвращает слабую ссылку на object. Исходный объект можно получить, вызвав объект ссылки, если референт ещё жив; если референт больше не жив, вызов объекта ссылки приведёт к возврату None. Если колбэк указан и не равен None, и возвращённый объект weakref всё ещё жив, колбэк будет вызван, когда объект будет близок к финализации; объект слабой ссылки будет передан как единственный параметр колбэку; референт больше не будет доступен.

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

Исключения, возбуждаемые колбэком, будут отмечены в стандартном потоке ошибок, но не могут быть распространены; они обрабатываются точно так же, как исключения, возбуждаемые методом __del__() объекта.

Слабые ссылки являются хешируемыми, если object хешируем. Они сохраняют своё хеш-значение даже после удаления object. Если hash() вызывается впервые только после удаления object, вызов возбудит TypeError.

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

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

Слабые ссылки являются обобщёнными по типу объекта, на который они ссылаются.

__callback__¶

Этот атрибут только для чтения возвращает колбэк, в данный момент связанный с weakref. Если колбэка нет или референт weakref больше не жив, то этот атрибут будет иметь значение None.

Изменено в версии 3.4: Добавлен атрибут __callback__.

weakref.proxy(object[, callback])¶

Возвращает прокси на object, который использует слабую ссылку. Это позволяет использовать прокси в большинстве контекстов без необходимости явного разыменования, используемого с объектами слабых ссылок. Возвращаемый объект будет иметь тип либо ProxyType, либо CallableProxyType, в зависимости от того, является ли object вызываемым. Прокси-объекты не являются хешируемыми независимо от референта; это избегает ряда проблем, связанных с их принципиально изменчивой природой, и предотвращает их использование в качестве ключей словаря. колбэк – это то же самое, что параметр с тем же именем у функции ref().

Доступ к атрибуту прокси-объекта после того, как референт был собран сборщиком мусора, возбуждает ReferenceError.

Изменено в версии 3.8: Расширена поддержка операторов для прокси-объектов, включены операторы матричного умножения @ и @=.

weakref.getweakrefcount(object)¶

Возвращает количество слабых ссылок и прокси, которые ссылаются на object.

weakref.getweakrefs(object)¶

Возвращает список всех объектов слабых ссылок и прокси, которые ссылаются на object.

class weakref.WeakKeyDictionary([dict])¶

Класс отображения, который хранит слабые ссылки на ключи. Записи словаря будут удалены, когда на ключ больше не останется сильных ссылок. Это можно использовать для связывания дополнительных данных с объектом, принадлежащим другим частям приложения, без добавления атрибутов к этим объектам. Это особенно полезно для объектов, которые переопределяют доступ к атрибутам.

Обратите внимание, что когда в словарь вставляется ключ, равный по значению существующему ключу (но не совпадающий по идентичности), он заменяет значение, но не заменяет существующий ключ. Из-за этого, когда удаляется ссылка на исходный ключ, также удаляется и запись в словаре:

>>> class T(str): pass
...
>>> k1, k2 = T(), T()
>>> d = weakref.WeakKeyDictionary()
>>> d[k1] = 1   # d = {k1: 1}
>>> d[k2] = 2   # d = {k1: 2}
>>> del k1      # d = {}

Обходной путь – удалить ключ перед переназначением:

>>> class T(str): pass
...
>>> k1, k2 = T(), T()
>>> d = weakref.WeakKeyDictionary()
>>> d[k1] = 1   # d = {k1: 1}
>>> del d[k1]
>>> d[k2] = 2   # d = {k2: 2}
>>> del k1      # d = {k2: 2}

Изменено в версии 3.9: Добавлена поддержка операторов | и |=, как указано в PEP 584.

WeakKeyDictionary объекты имеют дополнительный метод, который напрямую раскрывает внутренние ссылки. Эти ссылки не гарантированно являются «живыми» на момент использования, поэтому результат вызова ссылок необходимо проверять перед использованием. Это можно использовать, чтобы избежать создания ссылок, которые заставят сборщик мусора удерживать ключи дольше, чем необходимо.

WeakKeyDictionary.keyrefs()¶

Возвращает итератор по слабым ссылкам на ключи.

class weakref.WeakValueDictionary([dict])¶

Класс отображения, который хранит слабые ссылки на значения. Записи словаря будут удалены, когда на значение больше не будет сильных ссылок.

Изменено в версии 3.9: Добавлена поддержка операторов | и |=, как указано в PEP 584.

WeakValueDictionary объекты имеют дополнительный метод, который имеет те же проблемы, что и метод WeakKeyDictionary.keyrefs().

WeakValueDictionary.valuerefs()¶

Возвращает итератор по слабым ссылкам на значения.

class weakref.WeakSet([elements])¶

Класс множества, который хранит слабые ссылки на свои элементы. Элемент будет удален, когда на него больше не останется сильных ссылок.

class weakref.WeakMethod(method[, callback])¶

Пользовательский подкласс ref, который имитирует слабую ссылку на привязанный метод (т.е. метод, определенный в классе и полученный через экземпляр). Поскольку привязанный метод является эфемерным, обычная слабая ссылка не может его удержать. WeakMethod содержит специальный код для воссоздания привязанного метода до тех пор, пока не будут удалены объект или исходная функция:

>>> class C:
...     def method(self):
...         print("method called!")
...
>>> c = C()
>>> r = weakref.ref(c.method)
>>> r()
>>> r = weakref.WeakMethod(c.method)
>>> r()
<bound method C.method of <__main__.C object at 0x7fc859830220>>
>>> r()()
method called!
>>> del c
>>> gc.collect()
0
>>> r()
>>>

колбэк – это то же самое, что и одноименный параметр функции ref().

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

class weakref.finalize(obj, func, /, *args, **kwargs)¶

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

Финализатор считается живым, пока он не вызван (явно или при сборке мусора), после чего он считается мертвым. Вызов живого финализатора возвращает результат вычисления func(*arg, **kwargs), а вызов мертвого финализатора возвращает None.

Исключения, возбуждаемые колбэками финализатора во время сборки мусора, будут показаны в стандартный поток ошибок, но не могут быть распространены. Они обрабатываются так же, как исключения, возбуждаемые методом __del__() объекта или колбэком слабой ссылки.

При завершении программы вызывается каждый оставшийся живой финализатор, если только его атрибут atexit не установлен в false. Они вызываются в порядке, обратном порядку создания.

Финализатор никогда не вызовет свой колбэк на позднем этапе завершения интерпретатора, когда глобальные переменные модуля могут быть заменены на None.

__call__()¶

Если self жив, то пометить его как мертвый и вернуть результат вызова func(*args, **kwargs). Если self мертв, то вернуть None.

detach()¶

Если self жив, то пометить его как мёртвый и вернуть кортеж (obj, func, args, kwargs). Если self мёртв, то вернуть None.

peek()¶

Если self жив, то вернуть кортеж (obj, func, args, kwargs). Если self мёртв, то вернуть None.

alive¶

Свойство, которое истинно, если финализатор жив, и ложно в противном случае.

atexit¶

Записываемое логическое свойство, по умолчанию истинное. При завершении программы вызываются все оставшиеся живые финализаторы, для которых atexit истинно. Они вызываются в порядке, обратном порядку создания.

Примечание

Важно убедиться, что func, args и kwargs не содержат ссылок на obj, ни прямых, ни косвенных, иначе obj никогда не будет собран сборщиком мусора. В частности, func не должен быть привязанным методом obj.

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

class weakref.ReferenceType¶

Объект типа для объектов слабых ссылок.

class weakref.ProxyType¶

Объект типа для прокси-объектов, которые не являются вызываемыми.

class weakref.CallableProxyType¶

Объект типа для прокси вызываемых объектов.

weakref.ProxyTypes¶

Последовательность, содержащая все объекты типа для прокси. Это упрощает проверку, является ли объект прокси, без необходимости называть оба типа прокси.

>>> import weakref
>>> class Object:
...     pass
...
>>> o = Object()
>>> r = weakref.ref(o)
>>> o2 = r()
>>> o is o2
True

>>> del o, o2
>>> print(r())
None

# r – объект слабой ссылки
o = r()
if o is None:
    # объект был собран сборщиком мусора
    print("Object has been deallocated; can't frobnicate.")
else:
    print("Object is still live!")
    o.do_something_useful()

import weakref

class ExtendedRef(weakref.ref):
    def __init__(self, ob, callback=None, /, **annotations):
        super().__init__(ob, callback)
        self.__counter = 0
        for k, v in annotations.items():
            setattr(self, k, v)

    def __call__(self):
        """Возвращает пару, содержащую объект и количество
        вызовов ссылки.
        """
        ob = super().__call__()
        if ob is not None:
            self.__counter += 1
            ob = (ob, self.__counter)
        return ob

import weakref

_id2obj_dict = weakref.WeakValueDictionary()

def remember(obj):
    oid = id(obj)
    _id2obj_dict[oid] = obj
    return oid

def id2obj(oid):
    return _id2obj_dict[oid]

>>> import weakref
>>> class Object:
...     pass
...
>>> kenny = Object()
>>> weakref.finalize(kenny, print, "You killed Kenny!")
<finalize object at ...; for 'Object' at ...>
>>> del kenny
You killed Kenny!

>>> def callback(x, y, z):
...     print("CALLBACK")
...     return x + y + z
...
>>> obj = Object()
>>> f = weakref.finalize(obj, callback, 1, 2, z=3)
>>> assert f.alive
>>> assert f() == 6
CALLBACK
>>> assert not f.alive
>>> f()                     # колбэк не вызван, так как финализатор неактивен
>>> del obj                 # колбэк не вызван, так как финализатор неактивен

>>> obj = Object()
>>> f = weakref.finalize(obj, callback, 1, 2, z=3)
>>> f.detach()
(<...Object object ...>, <function callback ...>, (1, 2), {'z': 3})
>>> newobj, func, args, kwargs = _
>>> assert not f.alive
>>> assert newobj is obj
>>> assert func(*args, **kwargs) == 6
CALLBACK

>>> obj = Object()
>>> weakref.finalize(obj, print, "obj dead or exiting")
<finalize object at ...; for 'Object' at ...>
>>> exit()
obj dead or exiting

class TempDir:
    def __init__(self):
        self.name = tempfile.mkdtemp()

    def remove(self):
        if self.name is not None:
            shutil.rmtree(self.name)
            self.name = None

    @property
    def removed(self):
        return self.name is None

    def __del__(self):
        self.remove()

class TempDir:
    def __init__(self):
        self.name = tempfile.mkdtemp()
        self._finalizer = weakref.finalize(self, shutil.rmtree, self.name)

    def remove(self):
        self._finalizer()

    @property
    def removed(self):
        return not self._finalizer.alive

import weakref, sys
def unloading_module():
    # неявная ссылка на глобальные переменные модуля из тела функции
weakref.finalize(sys.modules[__name__], unloading_module)