Guido van Rossum | cc6764c | 1995-02-09 17:18:10 +0000 | [diff] [blame] | 1 | """Manage shelves of pickled objects. |
| 2 | |
| 3 | A "shelf" is a persistent, dictionary-like object. The difference |
| 4 | with dbm databases is that the values (not the keys!) in a shelf can |
| 5 | be essentially arbitrary Python objects -- anything that the "pickle" |
| 6 | module can handle. This includes most class instances, recursive data |
| 7 | types, and objects containing lots of shared sub-objects. The keys |
| 8 | are ordinary strings. |
| 9 | |
| 10 | To summarize the interface (key is a string, data is an arbitrary |
| 11 | object): |
| 12 | |
| 13 | import shelve |
Guido van Rossum | 256cbd7 | 1995-02-16 16:30:50 +0000 | [diff] [blame] | 14 | d = shelve.open(filename) # open, with (g)dbm filename -- no suffix |
Guido van Rossum | cc6764c | 1995-02-09 17:18:10 +0000 | [diff] [blame] | 15 | |
| 16 | d[key] = data # store data at key (overwrites old data if |
| 17 | # using an existing key) |
| 18 | data = d[key] # retrieve data at key (raise KeyError if no |
| 19 | # such key) |
| 20 | del d[key] # delete data stored at key (raises KeyError |
| 21 | # if no such key) |
| 22 | flag = d.has_key(key) # true if the key exists |
| 23 | list = d.keys() # a list of all existing keys (slow!) |
| 24 | |
| 25 | d.close() # close it |
| 26 | |
| 27 | Dependent on the implementation, closing a persistent dictionary may |
| 28 | or may not be necessary to flush changes to disk. |
| 29 | """ |
Guido van Rossum | a48061a | 1995-01-10 00:31:14 +0000 | [diff] [blame] | 30 | |
Guido van Rossum | 914c938 | 1997-06-06 21:12:45 +0000 | [diff] [blame] | 31 | # Try using cPickle and cStringIO if available. |
| 32 | |
| 33 | try: |
Guido van Rossum | f62cf61 | 1998-04-06 14:14:25 +0000 | [diff] [blame^] | 34 | from cPickle import Pickler, Unpickler |
Guido van Rossum | 914c938 | 1997-06-06 21:12:45 +0000 | [diff] [blame] | 35 | except ImportError: |
Guido van Rossum | f62cf61 | 1998-04-06 14:14:25 +0000 | [diff] [blame^] | 36 | from pickle import Pickler, Unpickler |
Guido van Rossum | 914c938 | 1997-06-06 21:12:45 +0000 | [diff] [blame] | 37 | |
| 38 | try: |
Guido van Rossum | f62cf61 | 1998-04-06 14:14:25 +0000 | [diff] [blame^] | 39 | from cStringIO import StringIO |
Guido van Rossum | 914c938 | 1997-06-06 21:12:45 +0000 | [diff] [blame] | 40 | except ImportError: |
Guido van Rossum | f62cf61 | 1998-04-06 14:14:25 +0000 | [diff] [blame^] | 41 | from StringIO import StringIO |
Guido van Rossum | a48061a | 1995-01-10 00:31:14 +0000 | [diff] [blame] | 42 | |
Guido van Rossum | cc6764c | 1995-02-09 17:18:10 +0000 | [diff] [blame] | 43 | |
Guido van Rossum | a48061a | 1995-01-10 00:31:14 +0000 | [diff] [blame] | 44 | class Shelf: |
Guido van Rossum | cc6764c | 1995-02-09 17:18:10 +0000 | [diff] [blame] | 45 | """Base class for shelf implementations. |
| 46 | |
| 47 | This is initialized with a dictionary-like object. |
| 48 | See the module's __doc__ string for an overview of the interface. |
| 49 | """ |
Guido van Rossum | a48061a | 1995-01-10 00:31:14 +0000 | [diff] [blame] | 50 | |
| 51 | def __init__(self, dict): |
| 52 | self.dict = dict |
| 53 | |
| 54 | def keys(self): |
| 55 | return self.dict.keys() |
| 56 | |
| 57 | def __len__(self): |
Guido van Rossum | 5f8ea10 | 1996-09-10 17:39:56 +0000 | [diff] [blame] | 58 | return len(self.dict) |
Guido van Rossum | a48061a | 1995-01-10 00:31:14 +0000 | [diff] [blame] | 59 | |
| 60 | def has_key(self, key): |
| 61 | return self.dict.has_key(key) |
| 62 | |
| 63 | def __getitem__(self, key): |
Guido van Rossum | 914c938 | 1997-06-06 21:12:45 +0000 | [diff] [blame] | 64 | f = StringIO(self.dict[key]) |
| 65 | return Unpickler(f).load() |
Guido van Rossum | a48061a | 1995-01-10 00:31:14 +0000 | [diff] [blame] | 66 | |
| 67 | def __setitem__(self, key, value): |
Guido van Rossum | 914c938 | 1997-06-06 21:12:45 +0000 | [diff] [blame] | 68 | f = StringIO() |
| 69 | p = Pickler(f) |
Guido van Rossum | a48061a | 1995-01-10 00:31:14 +0000 | [diff] [blame] | 70 | p.dump(value) |
| 71 | self.dict[key] = f.getvalue() |
| 72 | |
| 73 | def __delitem__(self, key): |
| 74 | del self.dict[key] |
| 75 | |
| 76 | def close(self): |
Guido van Rossum | 6599fb0 | 1997-12-09 14:18:33 +0000 | [diff] [blame] | 77 | try: |
Guido van Rossum | f62cf61 | 1998-04-06 14:14:25 +0000 | [diff] [blame^] | 78 | self.dict.close() |
Guido van Rossum | 6599fb0 | 1997-12-09 14:18:33 +0000 | [diff] [blame] | 79 | except: |
| 80 | pass |
| 81 | self.dict = 0 |
Guido van Rossum | a48061a | 1995-01-10 00:31:14 +0000 | [diff] [blame] | 82 | |
Guido van Rossum | cc6764c | 1995-02-09 17:18:10 +0000 | [diff] [blame] | 83 | def __del__(self): |
| 84 | self.close() |
Guido van Rossum | a48061a | 1995-01-10 00:31:14 +0000 | [diff] [blame] | 85 | |
Roger E. Masse | 4fc7067 | 1997-03-25 16:06:03 +0000 | [diff] [blame] | 86 | def sync(self): |
| 87 | if hasattr(self.dict, 'sync'): |
| 88 | self.dict.sync() |
| 89 | |
Guido van Rossum | cc6764c | 1995-02-09 17:18:10 +0000 | [diff] [blame] | 90 | |
Guido van Rossum | abad1cc | 1995-08-11 14:19:16 +0000 | [diff] [blame] | 91 | class BsdDbShelf(Shelf): |
| 92 | """Shelf implementation using the "BSD" db interface. |
| 93 | |
Guido van Rossum | 914c938 | 1997-06-06 21:12:45 +0000 | [diff] [blame] | 94 | This adds methods first(), next(), previous(), last() and |
| 95 | set_location() that have no counterpart in [g]dbm databases. |
Guido van Rossum | abad1cc | 1995-08-11 14:19:16 +0000 | [diff] [blame] | 96 | |
Guido van Rossum | 914c938 | 1997-06-06 21:12:45 +0000 | [diff] [blame] | 97 | The actual database must be opened using one of the "bsddb" |
| 98 | modules "open" routines (i.e. bsddb.hashopen, bsddb.btopen or |
| 99 | bsddb.rnopen) and passed to the constructor. |
Guido van Rossum | abad1cc | 1995-08-11 14:19:16 +0000 | [diff] [blame] | 100 | |
| 101 | See the module's __doc__ string for an overview of the interface. |
| 102 | """ |
| 103 | |
| 104 | def __init__(self, dict): |
| 105 | Shelf.__init__(self, dict) |
| 106 | |
| 107 | def set_location(self, key): |
| 108 | (key, value) = self.dict.set_location(key) |
Guido van Rossum | 914c938 | 1997-06-06 21:12:45 +0000 | [diff] [blame] | 109 | f = StringIO(value) |
| 110 | return (key, Unpickler(f).load()) |
Guido van Rossum | abad1cc | 1995-08-11 14:19:16 +0000 | [diff] [blame] | 111 | |
| 112 | def next(self): |
| 113 | (key, value) = self.dict.next() |
Guido van Rossum | 914c938 | 1997-06-06 21:12:45 +0000 | [diff] [blame] | 114 | f = StringIO(value) |
| 115 | return (key, Unpickler(f).load()) |
Guido van Rossum | abad1cc | 1995-08-11 14:19:16 +0000 | [diff] [blame] | 116 | |
| 117 | def previous(self): |
| 118 | (key, value) = self.dict.previous() |
Guido van Rossum | 914c938 | 1997-06-06 21:12:45 +0000 | [diff] [blame] | 119 | f = StringIO(value) |
| 120 | return (key, Unpickler(f).load()) |
Guido van Rossum | abad1cc | 1995-08-11 14:19:16 +0000 | [diff] [blame] | 121 | |
| 122 | def first(self): |
| 123 | (key, value) = self.dict.first() |
Guido van Rossum | 914c938 | 1997-06-06 21:12:45 +0000 | [diff] [blame] | 124 | f = StringIO(value) |
| 125 | return (key, Unpickler(f).load()) |
Guido van Rossum | abad1cc | 1995-08-11 14:19:16 +0000 | [diff] [blame] | 126 | |
| 127 | def last(self): |
| 128 | (key, value) = self.dict.last() |
Guido van Rossum | 914c938 | 1997-06-06 21:12:45 +0000 | [diff] [blame] | 129 | f = StringIO(value) |
| 130 | return (key, Unpickler(f).load()) |
Guido van Rossum | abad1cc | 1995-08-11 14:19:16 +0000 | [diff] [blame] | 131 | |
| 132 | |
| 133 | class DbfilenameShelf(Shelf): |
Guido van Rossum | cc6764c | 1995-02-09 17:18:10 +0000 | [diff] [blame] | 134 | """Shelf implementation using the "anydbm" generic dbm interface. |
| 135 | |
| 136 | This is initialized with the filename for the dbm database. |
| 137 | See the module's __doc__ string for an overview of the interface. |
| 138 | """ |
| 139 | |
Guido van Rossum | abad1cc | 1995-08-11 14:19:16 +0000 | [diff] [blame] | 140 | def __init__(self, filename, flag='c'): |
Guido van Rossum | cc6764c | 1995-02-09 17:18:10 +0000 | [diff] [blame] | 141 | import anydbm |
Guido van Rossum | abad1cc | 1995-08-11 14:19:16 +0000 | [diff] [blame] | 142 | Shelf.__init__(self, anydbm.open(filename, flag)) |
Guido van Rossum | cc6764c | 1995-02-09 17:18:10 +0000 | [diff] [blame] | 143 | |
| 144 | |
Guido van Rossum | abad1cc | 1995-08-11 14:19:16 +0000 | [diff] [blame] | 145 | def open(filename, flag='c'): |
Guido van Rossum | cc6764c | 1995-02-09 17:18:10 +0000 | [diff] [blame] | 146 | """Open a persistent dictionary for reading and writing. |
| 147 | |
| 148 | Argument is the filename for the dbm database. |
| 149 | See the module's __doc__ string for an overview of the interface. |
| 150 | """ |
| 151 | |
Guido van Rossum | abad1cc | 1995-08-11 14:19:16 +0000 | [diff] [blame] | 152 | return DbfilenameShelf(filename, flag) |