8.11.weakref — Weak references¶

Source code:Lib/weakref.py

Theweakref module allows the Python programmer to createweakreferences to objects.

In the following, the termreferent means the object which is referred toby a weak reference.

A weak reference to an object is not enough to keep the object alive: when theonly remaining references to a referent are weak references,garbage collection is free to destroy the referent and reuse its memoryfor something else. A primary use for weak references is to implement caches ormappings holding large objects, where it’s desired that a large object not bekept alive solely because it appears in a cache or mapping.

For example, if you have a number of large binary image objects, you may wish toassociate a name with each. If you used a Python dictionary to map names toimages, or images to names, the image objects would remain alive just becausethey appeared as values or keys in the dictionaries. TheWeakKeyDictionary andWeakValueDictionary classes supplied bytheweakref module are an alternative, using weak references to constructmappings that don’t keep objects alive solely because they appear in the mappingobjects. If, for example, an image object is a value in aWeakValueDictionary, then when the last remaining references to thatimage object are the weak references held by weak mappings, garbage collectioncan reclaim the object, and its corresponding entries in weak mappings aresimply deleted.

WeakKeyDictionary andWeakValueDictionary use weak referencesin their implementation, setting up callback functions on the weak referencesthat notify the weak dictionaries when a key or value has been reclaimed bygarbage collection. Most programs should find that using one of these weakdictionary types is all they need – it’s not usually necessary to create yourown weak references directly. The low-level machinery used by the weakdictionary implementations is exposed by theweakref module for thebenefit of advanced uses.

Not all objects can be weakly referenced; those objects which can include classinstances, functions written in Python (but not in C), methods (both bound andunbound), sets, frozensets, file objects,generators, type objects,DBcursor objects from thebsddb module, sockets, arrays, deques,regular expression pattern objects, and code objects.

Several built-in types such aslist anddict do not directlysupport weak references but can add support through subclassing:

classDict(dict):passobj=Dict(red=1,green=2,blue=3)# this object is weak referenceable

Extension types can easily be made to support weak references; seeWeak Reference Support.

classweakref.ref(object[,callback])¶

Return a weak reference toobject. The original object can be retrieved bycalling the reference object if the referent is still alive; if the referent isno longer alive, calling the reference object will causeNone to bereturned. Ifcallback is provided and notNone, and the returnedweakref object is still alive, the callback will be called when the object isabout to be finalized; the weak reference object will be passed as the onlyparameter to the callback; the referent will no longer be available.

It is allowable for many weak references to be constructed for the same object.Callbacks registered for each weak reference will be called from the mostrecently registered callback to the oldest registered callback.

Exceptions raised by the callback will be noted on the standard error output,but cannot be propagated; they are handled in exactly the same way as exceptionsraised from an object’s__del__() method.

Weak references arehashable if theobject is hashable. They will maintaintheir hash value even after theobject was deleted. Ifhash() is calledthe first time only after theobject was deleted, the call will raiseTypeError.

Weak references support tests for equality, but not ordering. If the referentsare still alive, two references have the same equality relationship as theirreferents (regardless of thecallback). If either referent has been deleted,the references are equal only if the reference objects are the same object.

Changed in version 2.4:This is now a subclassable type rather than a factory function; it derives fromobject.

weakref.proxy(object[,callback])¶

Return a proxy toobject which uses a weak reference. This supports use ofthe proxy in most contexts instead of requiring the explicit dereferencing usedwith weak reference objects. The returned object will have a type of eitherProxyType orCallableProxyType, depending on whetherobject iscallable. Proxy objects are nothashable regardless of the referent; thisavoids a number of problems related to their fundamentally mutable nature, andprevent their use as dictionary keys.callback is the same as the parameterof the same name to theref() function.

weakref.getweakrefcount(object)¶

Return the number of weak references and proxies which refer toobject.

weakref.getweakrefs(object)¶

Return a list of all weak reference and proxy objects which refer toobject.

classweakref.WeakKeyDictionary([dict])¶

Mapping class that references keys weakly. Entries in the dictionary will bediscarded when there is no longer a strong reference to the key. This can beused to associate additional data with an object owned by other parts of anapplication without adding attributes to those objects. This can be especiallyuseful with objects that override attribute accesses.

Note

Caution: Because aWeakKeyDictionary is built on top of a Pythondictionary, it must not change size when iterating over it. This can bedifficult to ensure for aWeakKeyDictionary because actionsperformed by the program during iteration may cause items in thedictionary to vanish “by magic” (as a side effect of garbage collection).

WeakKeyDictionary objects have the following additional methods. Theseexpose the internal references directly. The references are not guaranteed tobe “live” at the time they are used, so the result of calling the referencesneeds to be checked before being used. This can be used to avoid creatingreferences that will cause the garbage collector to keep the keys around longerthan needed.

WeakKeyDictionary.iterkeyrefs()¶

Return an iterable of the weak references to the keys.

New in version 2.5.

WeakKeyDictionary.keyrefs()¶

Return a list of weak references to the keys.

New in version 2.5.

classweakref.WeakValueDictionary([dict])¶

Mapping class that references values weakly. Entries in the dictionary will bediscarded when no strong reference to the value exists any more.

Note

Caution: Because aWeakValueDictionary is built on top of a Pythondictionary, it must not change size when iterating over it. This can bedifficult to ensure for aWeakValueDictionary because actions performedby the program during iteration may cause items in the dictionary to vanish “bymagic” (as a side effect of garbage collection).

WeakValueDictionary objects have the following additional methods.These methods have the same issues as theiterkeyrefs() andkeyrefs() methods ofWeakKeyDictionary objects.

WeakValueDictionary.itervaluerefs()¶

Return an iterable of the weak references to the values.

New in version 2.5.

WeakValueDictionary.valuerefs()¶

Return a list of weak references to the values.

New in version 2.5.

classweakref.WeakSet([elements])¶

Set class that keeps weak references to its elements. An element will bediscarded when no strong reference to it exists any more.

New in version 2.7.

weakref.ReferenceType¶

The type object for weak references objects.

weakref.ProxyType¶

The type object for proxies of objects which are not callable.

weakref.CallableProxyType¶

The type object for proxies of callable objects.

weakref.ProxyTypes¶

Sequence containing all the type objects for proxies. This can make it simplerto test if an object is a proxy without being dependent on naming both proxytypes.

exceptionweakref.ReferenceError¶

Exception raised when a proxy object is used but the underlying object has beencollected. This is the same as the standardReferenceError exception.

>>>importweakref>>>classObject:...pass...>>>o=Object()>>>r=weakref.ref(o)>>>o2=r()>>>oiso2True

>>>delo,o2>>>printr()None

# r is a weak reference objecto=r()ifoisNone:# referent has been garbage collectedprint"Object has been deallocated; can't frobnicate."else:print"Object is still live!"o.do_something_useful()

importweakrefclassExtendedRef(weakref.ref):def__init__(self,ob,callback=None,**annotations):super(ExtendedRef,self).__init__(ob,callback)self.__counter=0fork,vinannotations.iteritems():setattr(self,k,v)def__call__(self):"""Return a pair containing the referent and the number of        times the reference has been called.        """ob=super(ExtendedRef,self).__call__()ifobisnotNone:self.__counter+=1ob=(ob,self.__counter)returnob

importweakref_id2obj_dict=weakref.WeakValueDictionary()defremember(obj):oid=id(obj)_id2obj_dict[oid]=objreturnoiddefid2obj(oid):return_id2obj_dict[oid]