8.8. 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)   # этот объект поддерживает слабые ссылки

Другие встроенные типы, такие как tuple и int, не поддерживают слабые ссылки даже при создании подклассов (это деталь реализации и может отличаться в разных реализациях Python.).

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

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

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

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

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

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

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

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

__callback__¶

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

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

weakref.proxy(object[, callback])¶

Return a proxy to object which uses a weak reference. This supports use of the proxy in most contexts instead of requiring the explicit dereferencing used with weak reference objects. The returned object will have a type of either ProxyType or CallableProxyType, depending on whether object is callable. Proxy objects are not hashable regardless of the referent; this avoids a number of problems related to their fundamentally mutable nature, and prevent their use as dictionary keys. callback is the same as the parameter of the same name to the ref() function.

weakref.getweakrefcount(object)¶

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

weakref.getweakrefs(object)¶

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

class weakref.WeakKeyDictionary([dict])¶

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

Примечание

Предостережение: Поскольку WeakKeyDictionary построен на основе словаря Python, его размер не должен изменяться при итерации. Это может быть трудно обеспечить для WeakKeyDictionary, потому что действия, выполняемые программой во время итерации, могут привести к тому, что элементы словаря исчезнут «магическим образом» (как побочный эффект сборки мусора).

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

WeakKeyDictionary.keyrefs()¶

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

class weakref.WeakValueDictionary([dict])¶

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

Примечание

Предостережение: Поскольку WeakValueDictionary построен на основе словаря Python, его размер не должен изменяться при итерации. Это может быть трудно обеспечить для WeakValueDictionary, потому что действия, выполняемые программой во время итерации, могут привести к тому, что элементы словаря исчезнут «магическим образом» (как побочный эффект сборки мусора).

Объекты WeakValueDictionary имеют следующие дополнительные методы. У этих методов такие же проблемы, как и у метода keyrefs() объектов WeakKeyDictionary.

WeakValueDictionary.valuerefs()¶

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

class weakref.WeakSet([elements])¶

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

class weakref.WeakMethod(method)¶

Пользовательский подкласс 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()
>>>

Новое в версии 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.

weakref.ReferenceType¶

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

weakref.ProxyType¶

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

weakref.CallableProxyType¶

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

weakref.ProxyTypes¶

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

exception weakref.ReferenceError¶

Исключение, возникающее при использовании прокси-объекта, когда исходный объект уже собран сборщиком мусора. Это то же самое, что и стандартное исключение ReferenceError.

>>> 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(ExtendedRef, self).__init__(ob, callback)
        self.__counter = 0
        for k, v in annotations.items():
            setattr(self, k, v)

    def __call__(self):
        """Возвращает пару, содержащую объект и количество
        вызовов ссылки.
        """
        ob = super(ExtendedRef, self).__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()                                           
(<__main__.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)