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

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

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

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

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

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

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

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

Некоторые встроенные типы, такие как 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.

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

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

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])¶

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

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]