Debian Codegraph @

Lib/dbm/__init__.py

raw
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.sqlite3, dbm.gnu, dbm.ndbm or dbm.dumb database 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 error(Exception):
39 pass
40
41 _names = ['dbm.sqlite3', '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 # Check for SQLite3 header string.
168 if s16 == b"SQLite format 3\0":
169 return "dbm.sqlite3"
170
171 # Convert to 4-byte int in native byte order -- return "" if impossible
172 try:
173 (magic,) = struct.unpack("=l", s)
174 except struct.error:
175 return ""
176
177 # Check for GNU dbm
178 if magic in (0x13579ace, 0x13579acd, 0x13579acf):
179 return "dbm.gnu"
180
181 # Later versions of Berkeley db hash file have a 12-byte pad in
182 # front of the file type
183 try:
184 (magic,) = struct.unpack("=l", s16[-4:])
185 except struct.error:
186 return ""
187
188 # Unknown
189 return ""
190
191
192 if __name__ == "__main__":
193 for filename in sys.argv[1:]:
194 print(whichdb(filename) or "UNKNOWN", filename)