← Back to branch summary

~ubuntu-branches/ubuntu/maverick/python3.1/maverick

« back to all changes in this revision

Viewing changes to Lib/dbm/dumb.py

  • Committer: Bazaar Package Importer
  • Author(s): Matthias Klose
  • Date: 2009-03-23 00:01:27 UTC
  • Revision ID: james.westby@ubuntu.com-20090323000127-5fstfxju4ufrhthq
Tags: upstream-3.1~a1+20090322
Import upstream version 3.1~a1+20090322

Show diffs side-by-side

added added

removed removed

Lines of Context:
Lib/dbm/dumb.py
 
1
"""A dumb and slow but simple dbm clone.
 
2
 
 
3
For database spam, spam.dir contains the index (a text file),
 
4
spam.bak *may* contain a backup of the index (also a text file),
 
5
while spam.dat contains the data (a binary file).
 
6
 
 
7
XXX TO DO:
 
8
 
 
9
- seems to contain a bug when updating...
 
10
 
 
11
- reclaim free space (currently, space once occupied by deleted or expanded
 
12
items is never reused)
 
13
 
 
14
- support concurrent access (currently, if two processes take turns making
 
15
updates, they can mess up the index)
 
16
 
 
17
- support efficient access to large databases (currently, the whole index
 
18
is read when the database is opened, and some updates rewrite the whole index)
 
19
 
 
20
- support opening for read-only (flag = 'm')
 
21
 
 
22
"""
 
23
 
 
24
import io as _io
 
25
import os as _os
 
26
import collections
 
27
 
 
28
__all__ = ["error", "open"]
 
29
 
 
30
_BLOCKSIZE = 512
 
31
 
 
32
error = IOError
 
33
 
 
34
class _Database(collections.MutableMapping):
 
35
 
 
36
    # The on-disk directory and data files can remain in mutually
 
37
    # inconsistent states for an arbitrarily long time (see comments
 
38
    # at the end of __setitem__).  This is only repaired when _commit()
 
39
    # gets called.  One place _commit() gets called is from __del__(),
 
40
    # and if that occurs at program shutdown time, module globals may
 
41
    # already have gotten rebound to None.  Since it's crucial that
 
42
    # _commit() finish successfully, we can't ignore shutdown races
 
43
    # here, and _commit() must not reference any globals.
 
44
    _os = _os       # for _commit()
 
45
    _io = _io       # for _commit()
 
46
 
 
47
    def __init__(self, filebasename, mode):
 
48
        self._mode = mode
 
49
 
 
50
        # The directory file is a text file.  Each line looks like
 
51
        #    "%r, (%d, %d)\n" % (key, pos, siz)
 
52
        # where key is the string key, pos is the offset into the dat
 
53
        # file of the associated value's first byte, and siz is the number
 
54
        # of bytes in the associated value.
 
55
        self._dirfile = filebasename + '.dir'
 
56
 
 
57
        # The data file is a binary file pointed into by the directory
 
58
        # file, and holds the values associated with keys.  Each value
 
59
        # begins at a _BLOCKSIZE-aligned byte offset, and is a raw
 
60
        # binary 8-bit string value.
 
61
        self._datfile = filebasename + '.dat'
 
62
        self._bakfile = filebasename + '.bak'
 
63
 
 
64
        # The index is an in-memory dict, mirroring the directory file.
 
65
        self._index = None  # maps keys to (pos, siz) pairs
 
66
 
 
67
        # Mod by Jack: create data file if needed
 
68
        try:
 
69
            f = _io.open(self._datfile, 'r', encoding="Latin-1")
 
70
        except IOError:
 
71
            f = _io.open(self._datfile, 'w', encoding="Latin-1")
 
72
            self._chmod(self._datfile)
 
73
        f.close()
 
74
        self._update()
 
75
 
 
76
    # Read directory file into the in-memory index dict.
 
77
    def _update(self):
 
78
        self._index = {}
 
79
        try:
 
80
            f = _io.open(self._dirfile, 'r', encoding="Latin-1")
 
81
        except IOError:
 
82
            pass
 
83
        else:
 
84
            for line in f:
 
85
                line = line.rstrip()
 
86
                key, pos_and_siz_pair = eval(line)
 
87
                key = key.encode('Latin-1')
 
88
                self._index[key] = pos_and_siz_pair
 
89
            f.close()
 
90
 
 
91
    # Write the index dict to the directory file.  The original directory
 
92
    # file (if any) is renamed with a .bak extension first.  If a .bak
 
93
    # file currently exists, it's deleted.
 
94
    def _commit(self):
 
95
        # CAUTION:  It's vital that _commit() succeed, and _commit() can
 
96
        # be called from __del__().  Therefore we must never reference a
 
97
        # global in this routine.
 
98
        if self._index is None:
 
99
            return  # nothing to do
 
100
 
 
101
        try:
 
102
            self._os.unlink(self._bakfile)
 
103
        except self._os.error:
 
104
            pass
 
105
 
 
106
        try:
 
107
            self._os.rename(self._dirfile, self._bakfile)
 
108
        except self._os.error:
 
109
            pass
 
110
 
 
111
        f = self._io.open(self._dirfile, 'w', encoding="Latin-1")
 
112
        self._chmod(self._dirfile)
 
113
        for key, pos_and_siz_pair in self._index.items():
 
114
            # Use Latin-1 since it has no qualms with any value in any
 
115
            # position; UTF-8, though, does care sometimes.
 
116
            f.write("%r, %r\n" % (key.decode('Latin-1'), pos_and_siz_pair))
 
117
        f.close()
 
118
 
 
119
    sync = _commit
 
120
 
 
121
    def __getitem__(self, key):
 
122
        if isinstance(key, str):
 
123
            key = key.encode('utf-8')
 
124
        pos, siz = self._index[key]     # may raise KeyError
 
125
        f = _io.open(self._datfile, 'rb')
 
126
        f.seek(pos)
 
127
        dat = f.read(siz)
 
128
        f.close()
 
129
        return dat
 
130
 
 
131
    # Append val to the data file, starting at a _BLOCKSIZE-aligned
 
132
    # offset.  The data file is first padded with NUL bytes (if needed)
 
133
    # to get to an aligned offset.  Return pair
 
134
    #     (starting offset of val, len(val))
 
135
    def _addval(self, val):
 
136
        f = _io.open(self._datfile, 'rb+')
 
137
        f.seek(0, 2)
 
138
        pos = int(f.tell())
 
139
        npos = ((pos + _BLOCKSIZE - 1) // _BLOCKSIZE) * _BLOCKSIZE
 
140
        f.write(b'\0'*(npos-pos))
 
141
        pos = npos
 
142
        f.write(val)
 
143
        f.close()
 
144
        return (pos, len(val))
 
145
 
 
146
    # Write val to the data file, starting at offset pos.  The caller
 
147
    # is responsible for ensuring that there's enough room starting at
 
148
    # pos to hold val, without overwriting some other value.  Return
 
149
    # pair (pos, len(val)).
 
150
    def _setval(self, pos, val):
 
151
        f = _io.open(self._datfile, 'rb+')
 
152
        f.seek(pos)
 
153
        f.write(val)
 
154
        f.close()
 
155
        return (pos, len(val))
 
156
 
 
157
    # key is a new key whose associated value starts in the data file
 
158
    # at offset pos and with length siz.  Add an index record to
 
159
    # the in-memory index dict, and append one to the directory file.
 
160
    def _addkey(self, key, pos_and_siz_pair):
 
161
        self._index[key] = pos_and_siz_pair
 
162
        f = _io.open(self._dirfile, 'a', encoding="Latin-1")
 
163
        self._chmod(self._dirfile)
 
164
        f.write("%r, %r\n" % (key.decode("Latin-1"), pos_and_siz_pair))
 
165
        f.close()
 
166
 
 
167
    def __setitem__(self, key, val):
 
168
        if isinstance(key, str):
 
169
            key = key.encode('utf-8')
 
170
        elif not isinstance(key, (bytes, bytearray)):
 
171
            raise TypeError("keys must be bytes or strings")
 
172
        if isinstance(val, str):
 
173
            val = val.encode('utf-8')
 
174
        elif not isinstance(val, (bytes, bytearray)):
 
175
            raise TypeError("values must be bytes or strings")
 
176
        if key not in self._index:
 
177
            self._addkey(key, self._addval(val))
 
178
        else:
 
179
            # See whether the new value is small enough to fit in the
 
180
            # (padded) space currently occupied by the old value.
 
181
            pos, siz = self._index[key]
 
182
            oldblocks = (siz + _BLOCKSIZE - 1) // _BLOCKSIZE
 
183
            newblocks = (len(val) + _BLOCKSIZE - 1) // _BLOCKSIZE
 
184
            if newblocks <= oldblocks:
 
185
                self._index[key] = self._setval(pos, val)
 
186
            else:
 
187
                # The new value doesn't fit in the (padded) space used
 
188
                # by the old value.  The blocks used by the old value are
 
189
                # forever lost.
 
190
                self._index[key] = self._addval(val)
 
191
 
 
192
            # Note that _index may be out of synch with the directory
 
193
            # file now:  _setval() and _addval() don't update the directory
 
194
            # file.  This also means that the on-disk directory and data
 
195
            # files are in a mutually inconsistent state, and they'll
 
196
            # remain that way until _commit() is called.  Note that this
 
197
            # is a disaster (for the database) if the program crashes
 
198
            # (so that _commit() never gets called).
 
199
 
 
200
    def __delitem__(self, key):
 
201
        if isinstance(key, str):
 
202
            key = key.encode('utf-8')
 
203
        # The blocks used by the associated value are lost.
 
204
        del self._index[key]
 
205
        # XXX It's unclear why we do a _commit() here (the code always
 
206
        # XXX has, so I'm not changing it).  _setitem__ doesn't try to
 
207
        # XXX keep the directory file in synch.  Why should we?  Or
 
208
        # XXX why shouldn't __setitem__?
 
209
        self._commit()
 
210
 
 
211
    def keys(self):
 
212
        return list(self._index.keys())
 
213
 
 
214
    def items(self):
 
215
        return [(key, self[key]) for key in self._index.keys()]
 
216
 
 
217
    def __contains__(self, key):
 
218
        if isinstance(key, str):
 
219
            key = key.encode('utf-8')
 
220
        return key in self._index
 
221
 
 
222
    def iterkeys(self):
 
223
        return iter(self._index.keys())
 
224
    __iter__ = iterkeys
 
225
 
 
226
    def __len__(self):
 
227
        return len(self._index)
 
228
 
 
229
    def close(self):
 
230
        self._commit()
 
231
        self._index = self._datfile = self._dirfile = self._bakfile = None
 
232
 
 
233
    __del__ = close
 
234
 
 
235
    def _chmod (self, file):
 
236
        if hasattr(self._os, 'chmod'):
 
237
            self._os.chmod(file, self._mode)
 
238
 
 
239
 
 
240
def open(file, flag=None, mode=0o666):
 
241
    """Open the database file, filename, and return corresponding object.
 
242
 
 
243
    The flag argument, used to control how the database is opened in the
 
244
    other DBM implementations, is ignored in the dbm.dumb module; the
 
245
    database is always opened for update, and will be created if it does
 
246
    not exist.
 
247
 
 
248
    The optional mode argument is the UNIX mode of the file, used only when
 
249
    the database has to be created.  It defaults to octal code 0o666 (and
 
250
    will be modified by the prevailing umask).
 
251
 
 
252
    """
 
253
    # flag argument is currently ignored
 
254
 
 
255
    # Modify mode depending on the umask
 
256
    try:
 
257
        um = _os.umask(0)
 
258
        _os.umask(um)
 
259
    except AttributeError:
 
260
        pass
 
261
    else:
 
262
        # Turn off any bits that are set in the umask
 
263
        mode = mode & (~um)
 
264
 
 
265
    return _Database(file, mode)