Lib/shelve.py

   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
  14         d = shelve.open(filename) # open, with (g)dbm filename -- no suffix
  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 """
  30
  31 # Try using cPickle and cStringIO if available.
  32
  33 try:
  34     from cPickle import Pickler, Unpickler
  35 except ImportError:
  36     from pickle import Pickler, Unpickler
  37
  38 try:
  39     from cStringIO import StringIO
  40 except ImportError:
  41     from StringIO import StringIO
  42
  43 __all__ = ["Shelf","BsdDbShelf","DbfilenameShelf","open"]
  44
  45 class Shelf:
  46     """Base class for shelf implementations.
  47
  48     This is initialized with a dictionary-like object.
  49     See the module's __doc__ string for an overview of the interface.
  50     """
  51
  52     def __init__(self, dict):
  53         self.dict = dict
  54
  55     def keys(self):
  56         return self.dict.keys()
  57
  58     def __len__(self):
  59         return len(self.dict)
  60
  61     def has_key(self, key):
  62         return self.dict.has_key(key)
  63
  64     def get(self, key, default=None):
  65         if self.dict.has_key(key):
  66             return self[key]
  67         return default
  68
  69     def __getitem__(self, key):
  70         f = StringIO(self.dict[key])
  71         return Unpickler(f).load()
  72
  73     def __setitem__(self, key, value):
  74         f = StringIO()
  75         p = Pickler(f)
  76         p.dump(value)
  77         self.dict[key] = f.getvalue()
  78
  79     def __delitem__(self, key):
  80         del self.dict[key]
  81
  82     def close(self):
  83         try:
  84             self.dict.close()
  85         except:
  86             pass
  87         self.dict = 0
  88
  89     def __del__(self):
  90         self.close()
  91
  92     def sync(self):
  93         if hasattr(self.dict, 'sync'):
  94             self.dict.sync()
  95
  96
  97 class BsdDbShelf(Shelf):
  98     """Shelf implementation using the "BSD" db interface.
  99
 100     This adds methods first(), next(), previous(), last() and
 101     set_location() that have no counterpart in [g]dbm databases.
 102
 103     The actual database must be opened using one of the "bsddb"
 104     modules "open" routines (i.e. bsddb.hashopen, bsddb.btopen or
 105     bsddb.rnopen) and passed to the constructor.
 106
 107     See the module's __doc__ string for an overview of the interface.
 108     """
 109
 110     def __init__(self, dict):
 111         Shelf.__init__(self, dict)
 112
 113     def set_location(self, key):
 114         (key, value) = self.dict.set_location(key)
 115         f = StringIO(value)
 116         return (key, Unpickler(f).load())
 117
 118     def next(self):
 119         (key, value) = self.dict.next()
 120         f = StringIO(value)
 121         return (key, Unpickler(f).load())
 122
 123     def previous(self):
 124         (key, value) = self.dict.previous()
 125         f = StringIO(value)
 126         return (key, Unpickler(f).load())
 127
 128     def first(self):
 129         (key, value) = self.dict.first()
 130         f = StringIO(value)
 131         return (key, Unpickler(f).load())
 132
 133     def last(self):
 134         (key, value) = self.dict.last()
 135         f = StringIO(value)
 136         return (key, Unpickler(f).load())
 137
 138
 139 class DbfilenameShelf(Shelf):
 140     """Shelf implementation using the "anydbm" generic dbm interface.
 141
 142     This is initialized with the filename for the dbm database.
 143     See the module's __doc__ string for an overview of the interface.
 144     """
 145
 146     def __init__(self, filename, flag='c'):
 147         import anydbm
 148         Shelf.__init__(self, anydbm.open(filename, flag))
 149
 150
 151 def open(filename, flag='c'):
 152     """Open a persistent dictionary for reading and writing.
 153
 154     Argument is the filename for the dbm database.
 155     See the module's __doc__ string for an overview of the interface.
 156     """
 157
 158     return DbfilenameShelf(filename, flag)