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

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

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

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

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

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

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

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

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

class Dict(dict):
    pass

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

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

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

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

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

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

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

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

Изменено в версии 2.4: Теперь это тип, от которого можно наследовать, а не фабричная функция; он происходит от object.

weakref.proxy(object[, callback])¶

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

weakref.getweakrefcount(object)¶

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

weakref.getweakrefs(object)¶

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

class weakref.WeakKeyDictionary([dict])¶

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

Примечание

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

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

WeakKeyDictionary.iterkeyrefs()¶

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

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

WeakKeyDictionary.keyrefs()¶

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

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

class weakref.WeakValueDictionary([dict])¶

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

Примечание

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

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

WeakValueDictionary.itervaluerefs()¶

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

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

WeakValueDictionary.valuerefs()¶

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

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

class weakref.WeakSet([elements])¶

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

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

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.iteritems():
            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]