Python code coverage for Lib/weakref.py

#	count	content
1	n/a	"""Weak reference support for Python.
2	n/a
3	n/a	This module is an implementation of PEP 205:
4	n/a
5	n/a	http://www.python.org/dev/peps/pep-0205/
6	n/a	"""
7	n/a
8	n/a	# Naming convention: Variables named "wr" are weak reference objects;
9	n/a	# they are called this instead of "ref" to avoid name collisions with
10	n/a	# the module-global ref() function imported from _weakref.
11	n/a
12	n/a	from _weakref import (
13	n/a	getweakrefcount,
14	n/a	getweakrefs,
15	n/a	ref,
16	n/a	proxy,
17	n/a	CallableProxyType,
18	n/a	ProxyType,
19	n/a	ReferenceType,
20	n/a	_remove_dead_weakref)
21	n/a
22	n/a	from _weakrefset import WeakSet, _IterationGuard
23	n/a
24	n/a	import collections # Import after _weakref to avoid circular import.
25	n/a	import sys
26	n/a	import itertools
27	n/a
28	n/a	ProxyTypes = (ProxyType, CallableProxyType)
29	n/a
30	n/a	__all__ = ["ref", "proxy", "getweakrefcount", "getweakrefs",
31	n/a	"WeakKeyDictionary", "ReferenceType", "ProxyType",
32	n/a	"CallableProxyType", "ProxyTypes", "WeakValueDictionary",
33	n/a	"WeakSet", "WeakMethod", "finalize"]
34	n/a
35	n/a
36	n/a	class WeakMethod(ref):
37	n/a	"""
38	n/a	A custom `weakref.ref` subclass which simulates a weak reference to
39	n/a	a bound method, working around the lifetime problem of bound methods.
40	n/a	"""
41	n/a
42	n/a	__slots__ = "_func_ref", "_meth_type", "_alive", "__weakref__"
43	n/a
44	n/a	def __new__(cls, meth, callback=None):
45	n/a	try:
46	n/a	obj = meth.__self__
47	n/a	func = meth.__func__
48	n/a	except AttributeError:
49	n/a	raise TypeError("argument should be a bound method, not {}"
50	n/a	.format(type(meth))) from None
51	n/a	def _cb(arg):
52	n/a	# The self-weakref trick is needed to avoid creating a reference
53	n/a	# cycle.
54	n/a	self = self_wr()
55	n/a	if self._alive:
56	n/a	self._alive = False
57	n/a	if callback is not None:
58	n/a	callback(self)
59	n/a	self = ref.__new__(cls, obj, _cb)
60	n/a	self._func_ref = ref(func, _cb)
61	n/a	self._meth_type = type(meth)
62	n/a	self._alive = True
63	n/a	self_wr = ref(self)
64	n/a	return self
65	n/a
66	n/a	def __call__(self):
67	n/a	obj = super().__call__()
68	n/a	func = self._func_ref()
69	n/a	if obj is None or func is None:
70	n/a	return None
71	n/a	return self._meth_type(func, obj)
72	n/a
73	n/a	def __eq__(self, other):
74	n/a	if isinstance(other, WeakMethod):
75	n/a	if not self._alive or not other._alive:
76	n/a	return self is other
77	n/a	return ref.__eq__(self, other) and self._func_ref == other._func_ref
78	n/a	return False
79	n/a
80	n/a	def __ne__(self, other):
81	n/a	if isinstance(other, WeakMethod):
82	n/a	if not self._alive or not other._alive:
83	n/a	return self is not other
84	n/a	return ref.__ne__(self, other) or self._func_ref != other._func_ref
85	n/a	return True
86	n/a
87	n/a	__hash__ = ref.__hash__
88	n/a
89	n/a
90	n/a	class WeakValueDictionary(collections.MutableMapping):
91	n/a	"""Mapping class that references values weakly.
92	n/a
93	n/a	Entries in the dictionary will be discarded when no strong
94	n/a	reference to the value exists anymore
95	n/a	"""
96	n/a	# We inherit the constructor without worrying about the input
97	n/a	# dictionary; since it uses our .update() method, we get the right
98	n/a	# checks (if the other dictionary is a WeakValueDictionary,
99	n/a	# objects are unwrapped on the way out, and we always wrap on the
100	n/a	# way in).
101	n/a
102	n/a	def __init__(args, *kw):
103	n/a	if not args:
104	n/a	raise TypeError("descriptor '__init__' of 'WeakValueDictionary' "
105	n/a	"object needs an argument")
106	n/a	self, *args = args
107	n/a	if len(args) > 1:
108	n/a	raise TypeError('expected at most 1 arguments, got %d' % len(args))
109	n/a	def remove(wr, selfref=ref(self), _atomic_removal=_remove_dead_weakref):
110	n/a	self = selfref()
111	n/a	if self is not None:
112	n/a	if self._iterating:
113	n/a	self._pending_removals.append(wr.key)
114	n/a	else:
115	n/a	# Atomic removal is necessary since this function
116	n/a	# can be called asynchronously by the GC
117	n/a	_atomic_removal(d, wr.key)
118	n/a	self._remove = remove
119	n/a	# A list of keys to be removed
120	n/a	self._pending_removals = []
121	n/a	self._iterating = set()
122	n/a	self.data = d = {}
123	n/a	self.update(args, *kw)
124	n/a
125	n/a	def _commit_removals(self):
126	n/a	l = self._pending_removals
127	n/a	d = self.data
128	n/a	# We shouldn't encounter any KeyError, because this method should
129	n/a	# always be called before mutating the dict.
130	n/a	while l:
131	n/a	key = l.pop()
132	n/a	_remove_dead_weakref(d, key)
133	n/a
134	n/a	def __getitem__(self, key):
135	n/a	if self._pending_removals:
136	n/a	self._commit_removals()
137	n/a	o = self.data[key]()
138	n/a	if o is None:
139	n/a	raise KeyError(key)
140	n/a	else:
141	n/a	return o
142	n/a
143	n/a	def __delitem__(self, key):
144	n/a	if self._pending_removals:
145	n/a	self._commit_removals()
146	n/a	del self.data[key]
147	n/a
148	n/a	def __len__(self):
149	n/a	if self._pending_removals:
150	n/a	self._commit_removals()
151	n/a	return len(self.data)
152	n/a
153	n/a	def __contains__(self, key):
154	n/a	if self._pending_removals:
155	n/a	self._commit_removals()
156	n/a	try:
157	n/a	o = self.data[key]()
158	n/a	except KeyError:
159	n/a	return False
160	n/a	return o is not None
161	n/a
162	n/a	def __repr__(self):
163	n/a	return "<%s at %#x>" % (self.__class__.__name__, id(self))
164	n/a
165	n/a	def __setitem__(self, key, value):
166	n/a	if self._pending_removals:
167	n/a	self._commit_removals()
168	n/a	self.data[key] = KeyedRef(value, self._remove, key)
169	n/a
170	n/a	def copy(self):
171	n/a	if self._pending_removals:
172	n/a	self._commit_removals()
173	n/a	new = WeakValueDictionary()
174	n/a	for key, wr in self.data.items():
175	n/a	o = wr()
176	n/a	if o is not None:
177	n/a	new[key] = o
178	n/a	return new
179	n/a
180	n/a	__copy__ = copy
181	n/a
182	n/a	def __deepcopy__(self, memo):
183	n/a	from copy import deepcopy
184	n/a	if self._pending_removals:
185	n/a	self._commit_removals()
186	n/a	new = self.__class__()
187	n/a	for key, wr in self.data.items():
188	n/a	o = wr()
189	n/a	if o is not None:
190	n/a	new[deepcopy(key, memo)] = o
191	n/a	return new
192	n/a
193	n/a	def get(self, key, default=None):
194	n/a	if self._pending_removals:
195	n/a	self._commit_removals()
196	n/a	try:
197	n/a	wr = self.data[key]
198	n/a	except KeyError:
199	n/a	return default
200	n/a	else:
201	n/a	o = wr()
202	n/a	if o is None:
203	n/a	# This should only happen
204	n/a	return default
205	n/a	else:
206	n/a	return o
207	n/a
208	n/a	def items(self):
209	n/a	if self._pending_removals:
210	n/a	self._commit_removals()
211	n/a	with _IterationGuard(self):
212	n/a	for k, wr in self.data.items():
213	n/a	v = wr()
214	n/a	if v is not None:
215	n/a	yield k, v
216	n/a
217	n/a	def keys(self):
218	n/a	if self._pending_removals:
219	n/a	self._commit_removals()
220	n/a	with _IterationGuard(self):
221	n/a	for k, wr in self.data.items():
222	n/a	if wr() is not None:
223	n/a	yield k
224	n/a
225	n/a	__iter__ = keys
226	n/a
227	n/a	def itervaluerefs(self):
228	n/a	"""Return an iterator that yields the weak references to the values.
229	n/a
230	n/a	The references are not guaranteed to be 'live' at the time
231	n/a	they are used, so the result of calling the references needs
232	n/a	to be checked before being used. This can be used to avoid
233	n/a	creating references that will cause the garbage collector to
234	n/a	keep the values around longer than needed.
235	n/a
236	n/a	"""
237	n/a	if self._pending_removals:
238	n/a	self._commit_removals()
239	n/a	with _IterationGuard(self):
240	n/a	yield from self.data.values()
241	n/a
242	n/a	def values(self):
243	n/a	if self._pending_removals:
244	n/a	self._commit_removals()
245	n/a	with _IterationGuard(self):
246	n/a	for wr in self.data.values():
247	n/a	obj = wr()
248	n/a	if obj is not None:
249	n/a	yield obj
250	n/a
251	n/a	def popitem(self):
252	n/a	if self._pending_removals:
253	n/a	self._commit_removals()
254	n/a	while True:
255	n/a	key, wr = self.data.popitem()
256	n/a	o = wr()
257	n/a	if o is not None:
258	n/a	return key, o
259	n/a
260	n/a	def pop(self, key, *args):
261	n/a	if self._pending_removals:
262	n/a	self._commit_removals()
263	n/a	try:
264	n/a	o = self.data.pop(key)()
265	n/a	except KeyError:
266	n/a	o = None
267	n/a	if o is None:
268	n/a	if args:
269	n/a	return args[0]
270	n/a	else:
271	n/a	raise KeyError(key)
272	n/a	else:
273	n/a	return o
274	n/a
275	n/a	def setdefault(self, key, default=None):
276	n/a	try:
277	n/a	o = self.data[key]()
278	n/a	except KeyError:
279	n/a	o = None
280	n/a	if o is None:
281	n/a	if self._pending_removals:
282	n/a	self._commit_removals()
283	n/a	self.data[key] = KeyedRef(default, self._remove, key)
284	n/a	return default
285	n/a	else:
286	n/a	return o
287	n/a
288	n/a	def update(args, *kwargs):
289	n/a	if not args:
290	n/a	raise TypeError("descriptor 'update' of 'WeakValueDictionary' "
291	n/a	"object needs an argument")
292	n/a	self, *args = args
293	n/a	if len(args) > 1:
294	n/a	raise TypeError('expected at most 1 arguments, got %d' % len(args))
295	n/a	dict = args[0] if args else None
296	n/a	if self._pending_removals:
297	n/a	self._commit_removals()
298	n/a	d = self.data
299	n/a	if dict is not None:
300	n/a	if not hasattr(dict, "items"):
301	n/a	dict = type({})(dict)
302	n/a	for key, o in dict.items():
303	n/a	d[key] = KeyedRef(o, self._remove, key)
304	n/a	if len(kwargs):
305	n/a	self.update(kwargs)
306	n/a
307	n/a	def valuerefs(self):
308	n/a	"""Return a list of weak references to the values.
309	n/a
310	n/a	The references are not guaranteed to be 'live' at the time
311	n/a	they are used, so the result of calling the references needs
312	n/a	to be checked before being used. This can be used to avoid
313	n/a	creating references that will cause the garbage collector to
314	n/a	keep the values around longer than needed.
315	n/a
316	n/a	"""
317	n/a	if self._pending_removals:
318	n/a	self._commit_removals()
319	n/a	return list(self.data.values())
320	n/a
321	n/a
322	n/a	class KeyedRef(ref):
323	n/a	"""Specialized reference that includes a key corresponding to the value.
324	n/a
325	n/a	This is used in the WeakValueDictionary to avoid having to create
326	n/a	a function object for each key stored in the mapping. A shared
327	n/a	callback object can use the 'key' attribute of a KeyedRef instead
328	n/a	of getting a reference to the key from an enclosing scope.
329	n/a
330	n/a	"""
331	n/a
332	n/a	__slots__ = "key",
333	n/a
334	n/a	def __new__(type, ob, callback, key):
335	n/a	self = ref.__new__(type, ob, callback)
336	n/a	self.key = key
337	n/a	return self
338	n/a
339	n/a	def __init__(self, ob, callback, key):
340	n/a	super().__init__(ob, callback)
341	n/a
342	n/a
343	n/a	class WeakKeyDictionary(collections.MutableMapping):
344	n/a	""" Mapping class that references keys weakly.
345	n/a
346	n/a	Entries in the dictionary will be discarded when there is no
347	n/a	longer a strong reference to the key. This can be used to
348	n/a	associate additional data with an object owned by other parts of
349	n/a	an application without adding attributes to those objects. This
350	n/a	can be especially useful with objects that override attribute
351	n/a	accesses.
352	n/a	"""
353	n/a
354	n/a	def __init__(self, dict=None):
355	n/a	self.data = {}
356	n/a	def remove(k, selfref=ref(self)):
357	n/a	self = selfref()
358	n/a	if self is not None:
359	n/a	if self._iterating:
360	n/a	self._pending_removals.append(k)
361	n/a	else:
362	n/a	del self.data[k]
363	n/a	self._remove = remove
364	n/a	# A list of dead weakrefs (keys to be removed)
365	n/a	self._pending_removals = []
366	n/a	self._iterating = set()
367	n/a	self._dirty_len = False
368	n/a	if dict is not None:
369	n/a	self.update(dict)
370	n/a
371	n/a	def _commit_removals(self):
372	n/a	# NOTE: We don't need to call this method before mutating the dict,
373	n/a	# because a dead weakref never compares equal to a live weakref,
374	n/a	# even if they happened to refer to equal objects.
375	n/a	# However, it means keys may already have been removed.
376	n/a	l = self._pending_removals
377	n/a	d = self.data
378	n/a	while l:
379	n/a	try:
380	n/a	del d[l.pop()]
381	n/a	except KeyError:
382	n/a	pass
383	n/a
384	n/a	def _scrub_removals(self):
385	n/a	d = self.data
386	n/a	self._pending_removals = [k for k in self._pending_removals if k in d]
387	n/a	self._dirty_len = False
388	n/a
389	n/a	def __delitem__(self, key):
390	n/a	self._dirty_len = True
391	n/a	del self.data[ref(key)]
392	n/a
393	n/a	def __getitem__(self, key):
394	n/a	return self.data[ref(key)]
395	n/a
396	n/a	def __len__(self):
397	n/a	if self._dirty_len and self._pending_removals:
398	n/a	# self._pending_removals may still contain keys which were
399	n/a	# explicitly removed, we have to scrub them (see issue #21173).
400	n/a	self._scrub_removals()
401	n/a	return len(self.data) - len(self._pending_removals)
402	n/a
403	n/a	def __repr__(self):
404	n/a	return "<%s at %#x>" % (self.__class__.__name__, id(self))
405	n/a
406	n/a	def __setitem__(self, key, value):
407	n/a	self.data[ref(key, self._remove)] = value
408	n/a
409	n/a	def copy(self):
410	n/a	new = WeakKeyDictionary()
411	n/a	for key, value in self.data.items():
412	n/a	o = key()
413	n/a	if o is not None:
414	n/a	new[o] = value
415	n/a	return new
416	n/a
417	n/a	__copy__ = copy
418	n/a
419	n/a	def __deepcopy__(self, memo):
420	n/a	from copy import deepcopy
421	n/a	new = self.__class__()
422	n/a	for key, value in self.data.items():
423	n/a	o = key()
424	n/a	if o is not None:
425	n/a	new[o] = deepcopy(value, memo)
426	n/a	return new
427	n/a
428	n/a	def get(self, key, default=None):
429	n/a	return self.data.get(ref(key),default)
430	n/a
431	n/a	def __contains__(self, key):
432	n/a	try:
433	n/a	wr = ref(key)
434	n/a	except TypeError:
435	n/a	return False
436	n/a	return wr in self.data
437	n/a
438	n/a	def items(self):
439	n/a	with _IterationGuard(self):
440	n/a	for wr, value in self.data.items():
441	n/a	key = wr()
442	n/a	if key is not None:
443	n/a	yield key, value
444	n/a
445	n/a	def keys(self):
446	n/a	with _IterationGuard(self):
447	n/a	for wr in self.data:
448	n/a	obj = wr()
449	n/a	if obj is not None:
450	n/a	yield obj
451	n/a
452	n/a	__iter__ = keys
453	n/a
454	n/a	def values(self):
455	n/a	with _IterationGuard(self):
456	n/a	for wr, value in self.data.items():
457	n/a	if wr() is not None:
458	n/a	yield value
459	n/a
460	n/a	def keyrefs(self):
461	n/a	"""Return a list of weak references to the keys.
462	n/a
463	n/a	The references are not guaranteed to be 'live' at the time
464	n/a	they are used, so the result of calling the references needs
465	n/a	to be checked before being used. This can be used to avoid
466	n/a	creating references that will cause the garbage collector to
467	n/a	keep the keys around longer than needed.
468	n/a
469	n/a	"""
470	n/a	return list(self.data)
471	n/a
472	n/a	def popitem(self):
473	n/a	self._dirty_len = True
474	n/a	while True:
475	n/a	key, value = self.data.popitem()
476	n/a	o = key()
477	n/a	if o is not None:
478	n/a	return o, value
479	n/a
480	n/a	def pop(self, key, *args):
481	n/a	self._dirty_len = True
482	n/a	return self.data.pop(ref(key), *args)
483	n/a
484	n/a	def setdefault(self, key, default=None):
485	n/a	return self.data.setdefault(ref(key, self._remove),default)
486	n/a
487	n/a	def update(self, dict=None, **kwargs):
488	n/a	d = self.data
489	n/a	if dict is not None:
490	n/a	if not hasattr(dict, "items"):
491	n/a	dict = type({})(dict)
492	n/a	for key, value in dict.items():
493	n/a	d[ref(key, self._remove)] = value
494	n/a	if len(kwargs):
495	n/a	self.update(kwargs)
496	n/a
497	n/a
498	n/a	class finalize:
499	n/a	"""Class for finalization of weakrefable objects
500	n/a
501	n/a	finalize(obj, func, args, *kwargs) returns a callable finalizer
502	n/a	object which will be called when obj is garbage collected. The
503	n/a	first time the finalizer is called it evaluates func(arg, *kwargs)
504	n/a	and returns the result. After this the finalizer is dead, and
505	n/a	calling it just returns None.
506	n/a
507	n/a	When the program exits any remaining finalizers for which the
508	n/a	atexit attribute is true will be run in reverse order of creation.
509	n/a	By default atexit is true.
510	n/a	"""
511	n/a
512	n/a	# Finalizer objects don't have any state of their own. They are
513	n/a	# just used as keys to lookup _Info objects in the registry. This
514	n/a	# ensures that they cannot be part of a ref-cycle.
515	n/a
516	n/a	__slots__ = ()
517	n/a	_registry = {}
518	n/a	_shutdown = False
519	n/a	_index_iter = itertools.count()
520	n/a	_dirty = False
521	n/a	_registered_with_atexit = False
522	n/a
523	n/a	class _Info:
524	n/a	__slots__ = ("weakref", "func", "args", "kwargs", "atexit", "index")
525	n/a
526	n/a	def __init__(self, obj, func, args, *kwargs):
527	n/a	if not self._registered_with_atexit:
528	n/a	# We may register the exit function more than once because
529	n/a	# of a thread race, but that is harmless
530	n/a	import atexit
531	n/a	atexit.register(self._exitfunc)
532	n/a	finalize._registered_with_atexit = True
533	n/a	info = self._Info()
534	n/a	info.weakref = ref(obj, self)
535	n/a	info.func = func
536	n/a	info.args = args
537	n/a	info.kwargs = kwargs or None
538	n/a	info.atexit = True
539	n/a	info.index = next(self._index_iter)
540	n/a	self._registry[self] = info
541	n/a	finalize._dirty = True
542	n/a
543	n/a	def __call__(self, _=None):
544	n/a	"""If alive then mark as dead and return func(args, *kwargs);
545	n/a	otherwise return None"""
546	n/a	info = self._registry.pop(self, None)
547	n/a	if info and not self._shutdown:
548	n/a	return info.func(info.args, *(info.kwargs or {}))
549	n/a
550	n/a	def detach(self):
551	n/a	"""If alive then mark as dead and return (obj, func, args, kwargs);
552	n/a	otherwise return None"""
553	n/a	info = self._registry.get(self)
554	n/a	obj = info and info.weakref()
555	n/a	if obj is not None and self._registry.pop(self, None):
556	n/a	return (obj, info.func, info.args, info.kwargs or {})
557	n/a
558	n/a	def peek(self):
559	n/a	"""If alive then return (obj, func, args, kwargs);
560	n/a	otherwise return None"""
561	n/a	info = self._registry.get(self)
562	n/a	obj = info and info.weakref()
563	n/a	if obj is not None:
564	n/a	return (obj, info.func, info.args, info.kwargs or {})
565	n/a
566	n/a	@property
567	n/a	def alive(self):
568	n/a	"""Whether finalizer is alive"""
569	n/a	return self in self._registry
570	n/a
571	n/a	@property
572	n/a	def atexit(self):
573	n/a	"""Whether finalizer should be called at exit"""
574	n/a	info = self._registry.get(self)
575	n/a	return bool(info) and info.atexit
576	n/a
577	n/a	@atexit.setter
578	n/a	def atexit(self, value):
579	n/a	info = self._registry.get(self)
580	n/a	if info:
581	n/a	info.atexit = bool(value)
582	n/a
583	n/a	def __repr__(self):
584	n/a	info = self._registry.get(self)
585	n/a	obj = info and info.weakref()
586	n/a	if obj is None:
587	n/a	return '<%s object at %#x; dead>' % (type(self).__name__, id(self))
588	n/a	else:
589	n/a	return '<%s object at %#x; for %r at %#x>' % \
590	n/a	(type(self).__name__, id(self), type(obj).__name__, id(obj))
591	n/a
592	n/a	@classmethod
593	n/a	def _select_for_exit(cls):
594	n/a	# Return live finalizers marked for exit, oldest first
595	n/a	L = [(f,i) for (f,i) in cls._registry.items() if i.atexit]
596	n/a	L.sort(key=lambda item:item[1].index)
597	n/a	return [f for (f,i) in L]
598	n/a
599	n/a	@classmethod
600	n/a	def _exitfunc(cls):
601	n/a	# At shutdown invoke finalizers for which atexit is true.
602	n/a	# This is called once all other non-daemonic threads have been
603	n/a	# joined.
604	n/a	reenable_gc = False
605	n/a	try:
606	n/a	if cls._registry:
607	n/a	import gc
608	n/a	if gc.isenabled():
609	n/a	reenable_gc = True
610	n/a	gc.disable()
611	n/a	pending = None
612	n/a	while True:
613	n/a	if pending is None or finalize._dirty:
614	n/a	pending = cls._select_for_exit()
615	n/a	finalize._dirty = False
616	n/a	if not pending:
617	n/a	break
618	n/a	f = pending.pop()
619	n/a	try:
620	n/a	# gc is disabled, so (assuming no daemonic
621	n/a	# threads) the following is the only line in
622	n/a	# this function which might trigger creation
623	n/a	# of a new finalizer
624	n/a	f()
625	n/a	except Exception:
626	n/a	sys.excepthook(*sys.exc_info())
627	n/a	assert f not in cls._registry
628	n/a	finally:
629	n/a	# prevent any more finalizers from executing during shutdown
630	n/a	finalize._shutdown = True
631	n/a	if reenable_gc:
632	n/a	gc.enable()