Lib/weakref.py

   1 """Weak reference support for Python.
   2
   3 This module is an implementation of PEP 205:
   4
   5 http://www.python.org/dev/peps/pep-0205/
   6 """
   7
   8 # Naming convention: Variables named "wr" are weak reference objects;
   9 # they are called this instead of "ref" to avoid name collisions with
  10 # the module-global ref() function imported from _weakref.
  11
  12 import UserDict
  13
  14 from _weakref import (
  15      getweakrefcount,
  16      getweakrefs,
  17      ref,
  18      proxy,
  19      CallableProxyType,
  20      ProxyType,
  21      ReferenceType)
  22
  23 from exceptions import ReferenceError
  24
  25
  26 ProxyTypes = (ProxyType, CallableProxyType)
  27
  28 __all__ = ["ref", "proxy", "getweakrefcount", "getweakrefs",
  29            "WeakKeyDictionary", "ReferenceError", "ReferenceType", "ProxyType",
  30            "CallableProxyType", "ProxyTypes", "WeakValueDictionary"]
  31
  32
  33 class WeakValueDictionary(UserDict.UserDict):
  34     """Mapping class that references values weakly.
  35
  36     Entries in the dictionary will be discarded when no strong
  37     reference to the value exists anymore
  38     """
  39     # We inherit the constructor without worrying about the input
  40     # dictionary; since it uses our .update() method, we get the right
  41     # checks (if the other dictionary is a WeakValueDictionary,
  42     # objects are unwrapped on the way out, and we always wrap on the
  43     # way in).
  44
  45     def __init__(self, *args, **kw):
  46         def remove(wr, selfref=ref(self)):
  47             self = selfref()
  48             if self is not None:
  49                 del self.data[wr.key]
  50         self._remove = remove
  51         UserDict.UserDict.__init__(self, *args, **kw)
  52
  53     def __getitem__(self, key):
  54         o = self.data[key]()
  55         if o is None:
  56             raise KeyError, key
  57         else:
  58             return o
  59
  60     def __contains__(self, key):
  61         try:
  62             o = self.data[key]()
  63         except KeyError:
  64             return False
  65         return o is not None
  66
  67     def has_key(self, key):
  68         try:
  69             o = self.data[key]()
  70         except KeyError:
  71             return False
  72         return o is not None
  73
  74     def __repr__(self):
  75         return "<WeakValueDictionary at %s>" % id(self)
  76
  77     def __setitem__(self, key, value):
  78         self.data[key] = KeyedRef(value, self._remove, key)
  79
  80     def copy(self):
  81         new = WeakValueDictionary()
  82         for key, wr in self.data.items():
  83             o = wr()
  84             if o is not None:
  85                 new[key] = o
  86         return new
  87
  88     def get(self, key, default=None):
  89         try:
  90             wr = self.data[key]
  91         except KeyError:
  92             return default
  93         else:
  94             o = wr()
  95             if o is None:
  96                 # This should only happen
  97                 return default
  98             else:
  99                 return o
 100
 101     def items(self):
 102         L = []
 103         for key, wr in self.data.items():
 104             o = wr()
 105             if o is not None:
 106                 L.append((key, o))
 107         return L
 108
 109     def iteritems(self):
 110         for wr in self.data.itervalues():
 111             value = wr()
 112             if value is not None:
 113                 yield wr.key, value
 114
 115     def iterkeys(self):
 116         return self.data.iterkeys()
 117
 118     def __iter__(self):
 119         return self.data.iterkeys()
 120
 121     def itervaluerefs(self):
 122         """Return an iterator that yields the weak references to the values.
 123
 124         The references are not guaranteed to be 'live' at the time
 125         they are used, so the result of calling the references needs
 126         to be checked before being used.  This can be used to avoid
 127         creating references that will cause the garbage collector to
 128         keep the values around longer than needed.
 129
 130         """
 131         return self.data.itervalues()
 132
 133     def itervalues(self):
 134         for wr in self.data.itervalues():
 135             obj = wr()
 136             if obj is not None:
 137                 yield obj
 138
 139     def popitem(self):
 140         while 1:
 141             key, wr = self.data.popitem()
 142             o = wr()
 143             if o is not None:
 144                 return key, o
 145
 146     def pop(self, key, *args):
 147         try:
 148             o = self.data.pop(key)()
 149         except KeyError:
 150             if args:
 151                 return args[0]
 152             raise
 153         if o is None:
 154             raise KeyError, key
 155         else:
 156             return o
 157
 158     def setdefault(self, key, default=None):
 159         try:
 160             wr = self.data[key]
 161         except KeyError:
 162             self.data[key] = KeyedRef(default, self._remove, key)
 163             return default
 164         else:
 165             return wr()
 166
 167     def update(self, dict=None, **kwargs):
 168         d = self.data
 169         if dict is not None:
 170             if not hasattr(dict, "items"):
 171                 dict = type({})(dict)
 172             for key, o in dict.items():
 173                 d[key] = KeyedRef(o, self._remove, key)
 174         if len(kwargs):
 175             self.update(kwargs)
 176
 177     def valuerefs(self):
 178         """Return a list of weak references to the values.
 179
 180         The references are not guaranteed to be 'live' at the time
 181         they are used, so the result of calling the references needs
 182         to be checked before being used.  This can be used to avoid
 183         creating references that will cause the garbage collector to
 184         keep the values around longer than needed.
 185
 186         """
 187         return self.data.values()
 188
 189     def values(self):
 190         L = []
 191         for wr in self.data.values():
 192             o = wr()
 193             if o is not None:
 194                 L.append(o)
 195         return L
 196
 197
 198 class KeyedRef(ref):
 199     """Specialized reference that includes a key corresponding to the value.
 200
 201     This is used in the WeakValueDictionary to avoid having to create
 202     a function object for each key stored in the mapping.  A shared
 203     callback object can use the 'key' attribute of a KeyedRef instead
 204     of getting a reference to the key from an enclosing scope.
 205
 206     """
 207
 208     __slots__ = "key",
 209
 210     def __new__(type, ob, callback, key):
 211         self = ref.__new__(type, ob, callback)
 212         self.key = key
 213         return self
 214
 215     def __init__(self, ob, callback, key):
 216         super(KeyedRef,  self).__init__(ob, callback)
 217
 218
 219 class WeakKeyDictionary(UserDict.UserDict):
 220     """ Mapping class that references keys weakly.
 221
 222     Entries in the dictionary will be discarded when there is no
 223     longer a strong reference to the key. This can be used to
 224     associate additional data with an object owned by other parts of
 225     an application without adding attributes to those objects. This
 226     can be especially useful with objects that override attribute
 227     accesses.
 228     """
 229
 230     def __init__(self, dict=None):
 231         self.data = {}
 232         def remove(k, selfref=ref(self)):
 233             self = selfref()
 234             if self is not None:
 235                 del self.data[k]
 236         self._remove = remove
 237         if dict is not None: self.update(dict)
 238
 239     def __delitem__(self, key):
 240         del self.data[ref(key)]
 241
 242     def __getitem__(self, key):
 243         return self.data[ref(key)]
 244
 245     def __repr__(self):
 246         return "<WeakKeyDictionary at %s>" % id(self)
 247
 248     def __setitem__(self, key, value):
 249         self.data[ref(key, self._remove)] = value
 250
 251     def copy(self):
 252         new = WeakKeyDictionary()
 253         for key, value in self.data.items():
 254             o = key()
 255             if o is not None:
 256                 new[o] = value
 257         return new
 258
 259     def get(self, key, default=None):
 260         return self.data.get(ref(key),default)
 261
 262     def has_key(self, key):
 263         try:
 264             wr = ref(key)
 265         except TypeError:
 266             return 0
 267         return wr in self.data
 268
 269     def __contains__(self, key):
 270         try:
 271             wr = ref(key)
 272         except TypeError:
 273             return 0
 274         return wr in self.data
 275
 276     def items(self):
 277         L = []
 278         for key, value in self.data.items():
 279             o = key()
 280             if o is not None:
 281                 L.append((o, value))
 282         return L
 283
 284     def iteritems(self):
 285         for wr, value in self.data.iteritems():
 286             key = wr()
 287             if key is not None:
 288                 yield key, value
 289
 290     def iterkeyrefs(self):
 291         """Return an iterator that yields the weak references to the keys.
 292
 293         The references are not guaranteed to be 'live' at the time
 294         they are used, so the result of calling the references needs
 295         to be checked before being used.  This can be used to avoid
 296         creating references that will cause the garbage collector to
 297         keep the keys around longer than needed.
 298
 299         """
 300         return self.data.iterkeys()
 301
 302     def iterkeys(self):
 303         for wr in self.data.iterkeys():
 304             obj = wr()
 305             if obj is not None:
 306                 yield obj
 307
 308     def __iter__(self):
 309         return self.iterkeys()
 310
 311     def itervalues(self):
 312         return self.data.itervalues()
 313
 314     def keyrefs(self):
 315         """Return a list of weak references to the keys.
 316
 317         The references are not guaranteed to be 'live' at the time
 318         they are used, so the result of calling the references needs
 319         to be checked before being used.  This can be used to avoid
 320         creating references that will cause the garbage collector to
 321         keep the keys around longer than needed.
 322
 323         """
 324         return self.data.keys()
 325
 326     def keys(self):
 327         L = []
 328         for wr in self.data.keys():
 329             o = wr()
 330             if o is not None:
 331                 L.append(o)
 332         return L
 333
 334     def popitem(self):
 335         while 1:
 336             key, value = self.data.popitem()
 337             o = key()
 338             if o is not None:
 339                 return o, value
 340
 341     def pop(self, key, *args):
 342         return self.data.pop(ref(key), *args)
 343
 344     def setdefault(self, key, default=None):
 345         return self.data.setdefault(ref(key, self._remove),default)
 346
 347     def update(self, dict=None, **kwargs):
 348         d = self.data
 349         if dict is not None:
 350             if not hasattr(dict, "items"):
 351                 dict = type({})(dict)
 352             for key, value in dict.items():
 353                 d[ref(key, self._remove)] = value
 354         if len(kwargs):
 355             self.update(kwargs)