Python code coverage for Lib/shelve.py

#	count	content
1	n/a	"""Manage shelves of pickled objects.
2	n/a
3	n/a	A "shelf" is a persistent, dictionary-like object. The difference
4	n/a	with dbm databases is that the values (not the keys!) in a shelf can
5	n/a	be essentially arbitrary Python objects -- anything that the "pickle"
6	n/a	module can handle. This includes most class instances, recursive data
7	n/a	types, and objects containing lots of shared sub-objects. The keys
8	n/a	are ordinary strings.
9	n/a
10	n/a	To summarize the interface (key is a string, data is an arbitrary
11	n/a	object):
12	n/a
13	n/a	import shelve
14	n/a	d = shelve.open(filename) # open, with (g)dbm filename -- no suffix
15	n/a
16	n/a	d[key] = data # store data at key (overwrites old data if
17	n/a	# using an existing key)
18	n/a	data = d[key] # retrieve a COPY of the data at key (raise
19	n/a	# KeyError if no such key) -- NOTE that this
20	n/a	# access returns a copy of the entry!
21	n/a	del d[key] # delete data stored at key (raises KeyError
22	n/a	# if no such key)
23	n/a	flag = key in d # true if the key exists
24	n/a	list = d.keys() # a list of all existing keys (slow!)
25	n/a
26	n/a	d.close() # close it
27	n/a
28	n/a	Dependent on the implementation, closing a persistent dictionary may
29	n/a	or may not be necessary to flush changes to disk.
30	n/a
31	n/a	Normally, d[key] returns a COPY of the entry. This needs care when
32	n/a	mutable entries are mutated: for example, if d[key] is a list,
33	n/a	d[key].append(anitem)
34	n/a	does NOT modify the entry d[key] itself, as stored in the persistent
35	n/a	mapping -- it only modifies the copy, which is then immediately
36	n/a	discarded, so that the append has NO effect whatsoever. To append an
37	n/a	item to d[key] in a way that will affect the persistent mapping, use:
38	n/a	data = d[key]
39	n/a	data.append(anitem)
40	n/a	d[key] = data
41	n/a
42	n/a	To avoid the problem with mutable entries, you may pass the keyword
43	n/a	argument writeback=True in the call to shelve.open. When you use:
44	n/a	d = shelve.open(filename, writeback=True)
45	n/a	then d keeps a cache of all entries you access, and writes them all back
46	n/a	to the persistent mapping when you call d.close(). This ensures that
47	n/a	such usage as d[key].append(anitem) works as intended.
48	n/a
49	n/a	However, using keyword argument writeback=True may consume vast amount
50	n/a	of memory for the cache, and it may make d.close() very slow, if you
51	n/a	access many of d's entries after opening it in this way: d has no way to
52	n/a	check which of the entries you access are mutable and/or which ones you
53	n/a	actually mutate, so it must cache, and write back at close, all of the
54	n/a	entries that you access. You can call d.sync() to write back all the
55	n/a	entries in the cache, and empty the cache (d.sync() also synchronizes
56	n/a	the persistent dictionary on disk, if feasible).
57	n/a	"""
58	n/a
59	n/a	from pickle import Pickler, Unpickler
60	n/a	from io import BytesIO
61	n/a
62	n/a	import collections
63	n/a
64	n/a	__all__ = ["Shelf", "BsdDbShelf", "DbfilenameShelf", "open"]
65	n/a
66	n/a	class _ClosedDict(collections.MutableMapping):
67	n/a	'Marker for a closed dict. Access attempts raise a ValueError.'
68	n/a
69	n/a	def closed(self, *args):
70	n/a	raise ValueError('invalid operation on closed shelf')
71	n/a	__iter__ = __len__ = __getitem__ = __setitem__ = __delitem__ = keys = closed
72	n/a
73	n/a	def __repr__(self):
74	n/a	return '<Closed Dictionary>'
75	n/a
76	n/a
77	n/a	class Shelf(collections.MutableMapping):
78	n/a	"""Base class for shelf implementations.
79	n/a
80	n/a	This is initialized with a dictionary-like object.
81	n/a	See the module's __doc__ string for an overview of the interface.
82	n/a	"""
83	n/a
84	n/a	def __init__(self, dict, protocol=None, writeback=False,
85	n/a	keyencoding="utf-8"):
86	n/a	self.dict = dict
87	n/a	if protocol is None:
88	n/a	protocol = 3
89	n/a	self._protocol = protocol
90	n/a	self.writeback = writeback
91	n/a	self.cache = {}
92	n/a	self.keyencoding = keyencoding
93	n/a
94	n/a	def __iter__(self):
95	n/a	for k in self.dict.keys():
96	n/a	yield k.decode(self.keyencoding)
97	n/a
98	n/a	def __len__(self):
99	n/a	return len(self.dict)
100	n/a
101	n/a	def __contains__(self, key):
102	n/a	return key.encode(self.keyencoding) in self.dict
103	n/a
104	n/a	def get(self, key, default=None):
105	n/a	if key.encode(self.keyencoding) in self.dict:
106	n/a	return self[key]
107	n/a	return default
108	n/a
109	n/a	def __getitem__(self, key):
110	n/a	try:
111	n/a	value = self.cache[key]
112	n/a	except KeyError:
113	n/a	f = BytesIO(self.dict[key.encode(self.keyencoding)])
114	n/a	value = Unpickler(f).load()
115	n/a	if self.writeback:
116	n/a	self.cache[key] = value
117	n/a	return value
118	n/a
119	n/a	def __setitem__(self, key, value):
120	n/a	if self.writeback:
121	n/a	self.cache[key] = value
122	n/a	f = BytesIO()
123	n/a	p = Pickler(f, self._protocol)
124	n/a	p.dump(value)
125	n/a	self.dict[key.encode(self.keyencoding)] = f.getvalue()
126	n/a
127	n/a	def __delitem__(self, key):
128	n/a	del self.dict[key.encode(self.keyencoding)]
129	n/a	try:
130	n/a	del self.cache[key]
131	n/a	except KeyError:
132	n/a	pass
133	n/a
134	n/a	def __enter__(self):
135	n/a	return self
136	n/a
137	n/a	def __exit__(self, type, value, traceback):
138	n/a	self.close()
139	n/a
140	n/a	def close(self):
141	n/a	if self.dict is None:
142	n/a	return
143	n/a	try:
144	n/a	self.sync()
145	n/a	try:
146	n/a	self.dict.close()
147	n/a	except AttributeError:
148	n/a	pass
149	n/a	finally:
150	n/a	# Catch errors that may happen when close is called from __del__
151	n/a	# because CPython is in interpreter shutdown.
152	n/a	try:
153	n/a	self.dict = _ClosedDict()
154	n/a	except:
155	n/a	self.dict = None
156	n/a
157	n/a	def __del__(self):
158	n/a	if not hasattr(self, 'writeback'):
159	n/a	# __init__ didn't succeed, so don't bother closing
160	n/a	# see http://bugs.python.org/issue1339007 for details
161	n/a	return
162	n/a	self.close()
163	n/a
164	n/a	def sync(self):
165	n/a	if self.writeback and self.cache:
166	n/a	self.writeback = False
167	n/a	for key, entry in self.cache.items():
168	n/a	self[key] = entry
169	n/a	self.writeback = True
170	n/a	self.cache = {}
171	n/a	if hasattr(self.dict, 'sync'):
172	n/a	self.dict.sync()
173	n/a
174	n/a
175	n/a	class BsdDbShelf(Shelf):
176	n/a	"""Shelf implementation using the "BSD" db interface.
177	n/a
178	n/a	This adds methods first(), next(), previous(), last() and
179	n/a	set_location() that have no counterpart in [g]dbm databases.
180	n/a
181	n/a	The actual database must be opened using one of the "bsddb"
182	n/a	modules "open" routines (i.e. bsddb.hashopen, bsddb.btopen or
183	n/a	bsddb.rnopen) and passed to the constructor.
184	n/a
185	n/a	See the module's __doc__ string for an overview of the interface.
186	n/a	"""
187	n/a
188	n/a	def __init__(self, dict, protocol=None, writeback=False,
189	n/a	keyencoding="utf-8"):
190	n/a	Shelf.__init__(self, dict, protocol, writeback, keyencoding)
191	n/a
192	n/a	def set_location(self, key):
193	n/a	(key, value) = self.dict.set_location(key)
194	n/a	f = BytesIO(value)
195	n/a	return (key.decode(self.keyencoding), Unpickler(f).load())
196	n/a
197	n/a	def next(self):
198	n/a	(key, value) = next(self.dict)
199	n/a	f = BytesIO(value)
200	n/a	return (key.decode(self.keyencoding), Unpickler(f).load())
201	n/a
202	n/a	def previous(self):
203	n/a	(key, value) = self.dict.previous()
204	n/a	f = BytesIO(value)
205	n/a	return (key.decode(self.keyencoding), Unpickler(f).load())
206	n/a
207	n/a	def first(self):
208	n/a	(key, value) = self.dict.first()
209	n/a	f = BytesIO(value)
210	n/a	return (key.decode(self.keyencoding), Unpickler(f).load())
211	n/a
212	n/a	def last(self):
213	n/a	(key, value) = self.dict.last()
214	n/a	f = BytesIO(value)
215	n/a	return (key.decode(self.keyencoding), Unpickler(f).load())
216	n/a
217	n/a
218	n/a	class DbfilenameShelf(Shelf):
219	n/a	"""Shelf implementation using the "dbm" generic dbm interface.
220	n/a
221	n/a	This is initialized with the filename for the dbm database.
222	n/a	See the module's __doc__ string for an overview of the interface.
223	n/a	"""
224	n/a
225	n/a	def __init__(self, filename, flag='c', protocol=None, writeback=False):
226	n/a	import dbm
227	n/a	Shelf.__init__(self, dbm.open(filename, flag), protocol, writeback)
228	n/a
229	n/a
230	n/a	def open(filename, flag='c', protocol=None, writeback=False):
231	n/a	"""Open a persistent dictionary for reading and writing.
232	n/a
233	n/a	The filename parameter is the base filename for the underlying
234	n/a	database. As a side-effect, an extension may be added to the
235	n/a	filename and more than one file may be created. The optional flag
236	n/a	parameter has the same interpretation as the flag parameter of
237	n/a	dbm.open(). The optional protocol parameter specifies the
238	n/a	version of the pickle protocol (0, 1, or 2).
239	n/a
240	n/a	See the module's __doc__ string for an overview of the interface.
241	n/a	"""
242	n/a
243	n/a	return DbfilenameShelf(filename, flag, protocol, writeback)