1"""Generic interface to all dbm clones.
2
3Use
4
5        import dbm
6        d = dbm.open(file, 'w', 0o666)
7
8The returned object is a dbm.gnu, dbm.ndbm or dbm.dumb object, dependent on the
9type of database being opened (determined by the whichdb function) in the case
10of an existing dbm. If the dbm does not exist and the create or new flag ('c'
11or 'n') was specified, the dbm type will be determined by the availability of
12the modules (tested in the above order).
13
14It 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
25Future versions may change the order in which implementations are
26tested for existence, and add interfaces to other dbm-like
27implementations.
28"""
29
30__all__ = ['open', 'whichdb', 'error']
31
32import io
33import os
34import struct
35import sys
36
37
38class error(Exception):
39    pass
40
41_names = ['dbm.gnu', 'dbm.ndbm', 'dbm.dumb']
42_defaultmod = None
43_modules = {}
44
45error = (error, OSError)
46
47try:
48    from dbm import ndbm
49except ImportError:
50    ndbm = None
51
52
53def 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
98def 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
188if __name__ == "__main__":
189    for filename in sys.argv[1:]:
190        print(whichdb(filename) or "UNKNOWN", filename)
191