1 """Generic interface to all dbm clones.
2
3 Use
4
5 import dbm
6 d = dbm.open(file, 'w', 0o666)
7
8 The returned object is a dbm.gnu, dbm.ndbm or dbm.dumb object, dependent on the
9 type of database being opened (determined by the whichdb function) in the case
10 of an existing dbm. If the dbm does not exist and the create or new flag ('c'
11 or 'n') was specified, the dbm type will be determined by the availability of
12 the modules (tested in the above order).
13
14 It has the following interface (key and data are strings):
15
16 d[key] = data # store data at key (may override data at
17 # 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 = key in d # true if the key exists
23 list = d.keys() # return a list of all existing keys (slow!)
24
25 Future versions may change the order in which implementations are
26 tested for existence, and add interfaces to other dbm-like
27 implementations.
28 """
29
30 __all__ = ['open', 'whichdb', 'error']
31
32 import io
33 import os
34 import struct
35 import sys
36
37
38 class ESC[4;38;5;81merror(ESC[4;38;5;149mException):
39 pass
40
41 _names = ['dbm.gnu', 'dbm.ndbm', 'dbm.dumb']
42 _defaultmod = None
43 _modules = {}
44
45 error = (error, OSError)
46
47 try:
48 from dbm import ndbm
49 except ImportError:
50 ndbm = None
51
52
53 def open(file, flag='r', mode=0o666):
54 """Open or create database at path given by *file*.
55
56 Optional argument *flag* can be 'r' (default) for read-only access, 'w'
57 for read-write access of an existing database, 'c' for read-write access
58 to a new or existing database, and 'n' for read-write access to a new
59 database.
60
61 Note: 'r' and 'w' fail if the database doesn't exist; 'c' creates it
62 only if it doesn't exist; and 'n' always creates a new database.
63 """
64 global _defaultmod
65 if _defaultmod is None:
66 for name in _names:
67 try:
68 mod = __import__(name, fromlist=['open'])
69 except ImportError:
70 continue
71 if not _defaultmod:
72 _defaultmod = mod
73 _modules[name] = mod
74 if not _defaultmod:
75 raise ImportError("no dbm clone found; tried %s" % _names)
76
77 # guess the type of an existing database, if not creating a new one
78 result = whichdb(file) if 'n' not in flag else None
79 if result is None:
80 # db doesn't exist or 'n' flag was specified to create a new db
81 if 'c' in flag or 'n' in flag:
82 # file doesn't exist and the new flag was used so use default type
83 mod = _defaultmod
84 else:
85 raise error[0]("db file doesn't exist; "
86 "use 'c' or 'n' flag to create a new db")
87 elif result == "":
88 # db type cannot be determined
89 raise error[0]("db type could not be determined")
90 elif result not in _modules:
91 raise error[0]("db type is {0}, but the module is not "
92 "available".format(result))
93 else:
94 mod = _modules[result]
95 return mod.open(file, flag, mode)
96
97
98 def whichdb(filename):
99 """Guess which db package to use to open a db file.
100
101 Return values:
102
103 - None if the database file can't be read;
104 - empty string if the file can be read but can't be recognized
105 - the name of the dbm submodule (e.g. "ndbm" or "gnu") if recognized.
106
107 Importing the given module may still fail, and opening the
108 database using that module may still fail.
109 """
110
111 # Check for ndbm first -- this has a .pag and a .dir file
112 filename = os.fsencode(filename)
113 try:
114 f = io.open(filename + b".pag", "rb")
115 f.close()
116 f = io.open(filename + b".dir", "rb")
117 f.close()
118 return "dbm.ndbm"
119 except OSError:
120 # some dbm emulations based on Berkeley DB generate a .db file
121 # some do not, but they should be caught by the bsd checks
122 try:
123 f = io.open(filename + b".db", "rb")
124 f.close()
125 # guarantee we can actually open the file using dbm
126 # kind of overkill, but since we are dealing with emulations
127 # it seems like a prudent step
128 if ndbm is not None:
129 d = ndbm.open(filename)
130 d.close()
131 return "dbm.ndbm"
132 except OSError:
133 pass
134
135 # Check for dumbdbm next -- this has a .dir and a .dat file
136 try:
137 # First check for presence of files
138 os.stat(filename + b".dat")
139 size = os.stat(filename + b".dir").st_size
140 # dumbdbm files with no keys are empty
141 if size == 0:
142 return "dbm.dumb"
143 f = io.open(filename + b".dir", "rb")
144 try:
145 if f.read(1) in (b"'", b'"'):
146 return "dbm.dumb"
147 finally:
148 f.close()
149 except OSError:
150 pass
151
152 # See if the file exists, return None if not
153 try:
154 f = io.open(filename, "rb")
155 except OSError:
156 return None
157
158 with f:
159 # Read the start of the file -- the magic number
160 s16 = f.read(16)
161 s = s16[0:4]
162
163 # Return "" if not at least 4 bytes
164 if len(s) != 4:
165 return ""
166
167 # Convert to 4-byte int in native byte order -- return "" if impossible
168 try:
169 (magic,) = struct.unpack("=l", s)
170 except struct.error:
171 return ""
172
173 # Check for GNU dbm
174 if magic in (0x13579ace, 0x13579acd, 0x13579acf):
175 return "dbm.gnu"
176
177 # Later versions of Berkeley db hash file have a 12-byte pad in
178 # front of the file type
179 try:
180 (magic,) = struct.unpack("=l", s16[-4:])
181 except struct.error:
182 return ""
183
184 # Unknown
185 return ""
186
187
188 if __name__ == "__main__":
189 for filename in sys.argv[1:]:
190 print(whichdb(filename) or "UNKNOWN", filename)