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 _weakrefset import WeakSet, _IterationGuard 24 25 from exceptions import ReferenceError 26 27 28 ProxyTypes = (ProxyType, CallableProxyType) 29 30 __all__ = ["ref", "proxy", "getweakrefcount", "getweakrefs", 31 "WeakKeyDictionary", "ReferenceError", "ReferenceType", "ProxyType", 32 "CallableProxyType", "ProxyTypes", "WeakValueDictionary", 'WeakSet'] 33 34 35 class WeakValueDictionary(UserDict.UserDict): 36 """Mapping class that references values weakly. 37 38 Entries in the dictionary will be discarded when no strong 39 reference to the value exists anymore 40 """ 41 # We inherit the constructor without worrying about the input 42 # dictionary; since it uses our .update() method, we get the right 43 # checks (if the other dictionary is a WeakValueDictionary, 44 # objects are unwrapped on the way out, and we always wrap on the 45 # way in). 46 47 def __init__(*args, **kw): 48 if not args: 49 raise TypeError("descriptor '__init__' of 'WeakValueDictionary' " 50 "object needs an argument") 51 self = args[0] 52 args = args[1:] 53 if len(args) > 1: 54 raise TypeError('expected at most 1 arguments, got %d' % len(args)) 55 def remove(wr, selfref=ref(self)): 56 self = selfref() 57 if self is not None: 58 if self._iterating: 59 self._pending_removals.append(wr.key) 60 else: 61 del self.data[wr.key] 62 self._remove = remove 63 # A list of keys to be removed 64 self._pending_removals = [] 65 self._iterating = set() 66 UserDict.UserDict.__init__(self, *args, **kw) 67 68 def _commit_removals(self): 69 l = self._pending_removals 70 d = self.data 71 # We shouldn't encounter any KeyError, because this method should 72 # always be called *before* mutating the dict. 73 while l: 74 del d[l.pop()] 75 76 def __getitem__(self, key): 77 o = self.data[key]() 78 if o is None: 79 raise KeyError, key 80 else: 81 return o 82 83 def __delitem__(self, key): 84 if self._pending_removals: 85 self._commit_removals() 86 del self.data[key] 87 88 def __contains__(self, key): 89 try: 90 o = self.data[key]() 91 except KeyError: 92 return False 93 return o is not None 94 95 def has_key(self, key): 96 try: 97 o = self.data[key]() 98 except KeyError: 99 return False 100 return o is not None 101 102 def __repr__(self): 103 return "<WeakValueDictionary at %s>" % id(self) 104 105 def __setitem__(self, key, value): 106 if self._pending_removals: 107 self._commit_removals() 108 self.data[key] = KeyedRef(value, self._remove, key) 109 110 def clear(self): 111 if self._pending_removals: 112 self._commit_removals() 113 self.data.clear() 114 115 def copy(self): 116 new = WeakValueDictionary() 117 for key, wr in self.data.items(): 118 o = wr() 119 if o is not None: 120 new[key] = o 121 return new 122 123 __copy__ = copy 124 125 def __deepcopy__(self, memo): 126 from copy import deepcopy 127 new = self.__class__() 128 for key, wr in self.data.items(): 129 o = wr() 130 if o is not None: 131 new[deepcopy(key, memo)] = o 132 return new 133 134 def get(self, key, default=None): 135 try: 136 wr = self.data[key] 137 except KeyError: 138 return default 139 else: 140 o = wr() 141 if o is None: 142 # This should only happen 143 return default 144 else: 145 return o 146 147 def items(self): 148 L = [] 149 for key, wr in self.data.items(): 150 o = wr() 151 if o is not None: 152 L.append((key, o)) 153 return L 154 155 def iteritems(self): 156 with _IterationGuard(self): 157 for wr in self.data.itervalues(): 158 value = wr() 159 if value is not None: 160 yield wr.key, value 161 162 def iterkeys(self): 163 with _IterationGuard(self): 164 for k in self.data.iterkeys(): 165 yield k 166 167 __iter__ = iterkeys 168 169 def itervaluerefs(self): 170 """Return an iterator that yields the weak references to the values. 171 172 The references are not guaranteed to be 'live' at the time 173 they are used, so the result of calling the references needs 174 to be checked before being used. This can be used to avoid 175 creating references that will cause the garbage collector to 176 keep the values around longer than needed. 177 178 """ 179 with _IterationGuard(self): 180 for wr in self.data.itervalues(): 181 yield wr 182 183 def itervalues(self): 184 with _IterationGuard(self): 185 for wr in self.data.itervalues(): 186 obj = wr() 187 if obj is not None: 188 yield obj 189 190 def popitem(self): 191 if self._pending_removals: 192 self._commit_removals() 193 while 1: 194 key, wr = self.data.popitem() 195 o = wr() 196 if o is not None: 197 return key, o 198 199 def pop(self, key, *args): 200 if self._pending_removals: 201 self._commit_removals() 202 try: 203 o = self.data.pop(key)() 204 except KeyError: 205 if args: 206 return args[0] 207 raise 208 if o is None: 209 raise KeyError, key 210 else: 211 return o 212 213 def setdefault(self, key, default=None): 214 try: 215 wr = self.data[key] 216 except KeyError: 217 if self._pending_removals: 218 self._commit_removals() 219 self.data[key] = KeyedRef(default, self._remove, key) 220 return default 221 else: 222 return wr() 223 224 def update(*args, **kwargs): 225 if not args: 226 raise TypeError("descriptor 'update' of 'WeakValueDictionary' " 227 "object needs an argument") 228 self = args[0] 229 args = args[1:] 230 if len(args) > 1: 231 raise TypeError('expected at most 1 arguments, got %d' % len(args)) 232 dict = args[0] if args else None 233 if self._pending_removals: 234 self._commit_removals() 235 d = self.data 236 if dict is not None: 237 if not hasattr(dict, "items"): 238 dict = type({})(dict) 239 for key, o in dict.items(): 240 d[key] = KeyedRef(o, self._remove, key) 241 if len(kwargs): 242 self.update(kwargs) 243 244 def valuerefs(self): 245 """Return a list of weak references to the values. 246 247 The references are not guaranteed to be 'live' at the time 248 they are used, so the result of calling the references needs 249 to be checked before being used. This can be used to avoid 250 creating references that will cause the garbage collector to 251 keep the values around longer than needed. 252 253 """ 254 return self.data.values() 255 256 def values(self): 257 L = [] 258 for wr in self.data.values(): 259 o = wr() 260 if o is not None: 261 L.append(o) 262 return L 263 264 265 class KeyedRef(ref): 266 """Specialized reference that includes a key corresponding to the value. 267 268 This is used in the WeakValueDictionary to avoid having to create 269 a function object for each key stored in the mapping. A shared 270 callback object can use the 'key' attribute of a KeyedRef instead 271 of getting a reference to the key from an enclosing scope. 272 273 """ 274 275 __slots__ = "key", 276 277 def __new__(type, ob, callback, key): 278 self = ref.__new__(type, ob, callback) 279 self.key = key 280 return self 281 282 def __init__(self, ob, callback, key): 283 super(KeyedRef, self).__init__(ob, callback) 284 285 286 class WeakKeyDictionary(UserDict.UserDict): 287 """ Mapping class that references keys weakly. 288 289 Entries in the dictionary will be discarded when there is no 290 longer a strong reference to the key. This can be used to 291 associate additional data with an object owned by other parts of 292 an application without adding attributes to those objects. This 293 can be especially useful with objects that override attribute 294 accesses. 295 """ 296 297 def __init__(self, dict=None): 298 self.data = {} 299 def remove(k, selfref=ref(self)): 300 self = selfref() 301 if self is not None: 302 if self._iterating: 303 self._pending_removals.append(k) 304 else: 305 del self.data[k] 306 self._remove = remove 307 # A list of dead weakrefs (keys to be removed) 308 self._pending_removals = [] 309 self._iterating = set() 310 if dict is not None: 311 self.update(dict) 312 313 def _commit_removals(self): 314 # NOTE: We don't need to call this method before mutating the dict, 315 # because a dead weakref never compares equal to a live weakref, 316 # even if they happened to refer to equal objects. 317 # However, it means keys may already have been removed. 318 l = self._pending_removals 319 d = self.data 320 while l: 321 try: 322 del d[l.pop()] 323 except KeyError: 324 pass 325 326 def __delitem__(self, key): 327 del self.data[ref(key)] 328 329 def __getitem__(self, key): 330 return self.data[ref(key)] 331 332 def __repr__(self): 333 return "<WeakKeyDictionary at %s>" % id(self) 334 335 def __setitem__(self, key, value): 336 self.data[ref(key, self._remove)] = value 337 338 def copy(self): 339 new = WeakKeyDictionary() 340 for key, value in self.data.items(): 341 o = key() 342 if o is not None: 343 new[o] = value 344 return new 345 346 __copy__ = copy 347 348 def __deepcopy__(self, memo): 349 from copy import deepcopy 350 new = self.__class__() 351 for key, value in self.data.items(): 352 o = key() 353 if o is not None: 354 new[o] = deepcopy(value, memo) 355 return new 356 357 def get(self, key, default=None): 358 return self.data.get(ref(key),default) 359 360 def has_key(self, key): 361 try: 362 wr = ref(key) 363 except TypeError: 364 return 0 365 return wr in self.data 366 367 def __contains__(self, key): 368 try: 369 wr = ref(key) 370 except TypeError: 371 return 0 372 return wr in self.data 373 374 def items(self): 375 L = [] 376 for key, value in self.data.items(): 377 o = key() 378 if o is not None: 379 L.append((o, value)) 380 return L 381 382 def iteritems(self): 383 with _IterationGuard(self): 384 for wr, value in self.data.iteritems(): 385 key = wr() 386 if key is not None: 387 yield key, value 388 389 def iterkeyrefs(self): 390 """Return an iterator that yields the weak references to the keys. 391 392 The references are not guaranteed to be 'live' at the time 393 they are used, so the result of calling the references needs 394 to be checked before being used. This can be used to avoid 395 creating references that will cause the garbage collector to 396 keep the keys around longer than needed. 397 398 """ 399 with _IterationGuard(self): 400 for wr in self.data.iterkeys(): 401 yield wr 402 403 def iterkeys(self): 404 with _IterationGuard(self): 405 for wr in self.data.iterkeys(): 406 obj = wr() 407 if obj is not None: 408 yield obj 409 410 __iter__ = iterkeys 411 412 def itervalues(self): 413 with _IterationGuard(self): 414 for value in self.data.itervalues(): 415 yield value 416 417 def keyrefs(self): 418 """Return a list of weak references to the keys. 419 420 The references are not guaranteed to be 'live' at the time 421 they are used, so the result of calling the references needs 422 to be checked before being used. This can be used to avoid 423 creating references that will cause the garbage collector to 424 keep the keys around longer than needed. 425 426 """ 427 return self.data.keys() 428 429 def keys(self): 430 L = [] 431 for wr in self.data.keys(): 432 o = wr() 433 if o is not None: 434 L.append(o) 435 return L 436 437 def popitem(self): 438 while 1: 439 key, value = self.data.popitem() 440 o = key() 441 if o is not None: 442 return o, value 443 444 def pop(self, key, *args): 445 return self.data.pop(ref(key), *args) 446 447 def setdefault(self, key, default=None): 448 return self.data.setdefault(ref(key, self._remove),default) 449 450 def update(self, dict=None, **kwargs): 451 d = self.data 452 if dict is not None: 453 if not hasattr(dict, "items"): 454 dict = type({})(dict) 455 for key, value in dict.items(): 456 d[ref(key, self._remove)] = value 457 if len(kwargs): 458 self.update(kwargs) 459
