1 2 :mod:`bsddb` --- Interface to Berkeley DB library 3 ================================================= 4 5 .. module:: bsddb 6 :synopsis: Interface to Berkeley DB database library 7 .. sectionauthor:: Skip Montanaro <skip (a] pobox.com> 8 9 .. deprecated:: 2.6 10 The :mod:`bsddb` module has been removed in Python 3. 11 12 13 The :mod:`bsddb` module provides an interface to the Berkeley DB library. Users 14 can create hash, btree or record based library files using the appropriate open 15 call. Bsddb objects behave generally like dictionaries. Keys and values must be 16 strings, however, so to use other objects as keys or to store other kinds of 17 objects the user must serialize them somehow, typically using 18 :func:`marshal.dumps` or :func:`pickle.dumps`. 19 20 The :mod:`bsddb` module requires a Berkeley DB library version from 4.0 thru 21 4.7. 22 23 24 .. seealso:: 25 26 http://www.jcea.es/programacion/pybsddb.htm 27 The website with documentation for the :mod:`bsddb.db` Python Berkeley DB 28 interface that closely mirrors the object oriented interface provided in 29 Berkeley DB 4.x itself. 30 31 http://www.oracle.com/database/berkeley-db/ 32 The Berkeley DB library. 33 34 A more modern DB, DBEnv and DBSequence object interface is available in the 35 :mod:`bsddb.db` module which closely matches the Berkeley DB C API documented at 36 the above URLs. Additional features provided by the :mod:`bsddb.db` API include 37 fine tuning, transactions, logging, and multiprocess concurrent database access. 38 39 The following is a description of the legacy :mod:`bsddb` interface compatible 40 with the old Python bsddb module. Starting in Python 2.5 this interface should 41 be safe for multithreaded access. The :mod:`bsddb.db` API is recommended for 42 threading users as it provides better control. 43 44 The :mod:`bsddb` module defines the following functions that create objects that 45 access the appropriate type of Berkeley DB file. The first two arguments of 46 each function are the same. For ease of portability, only the first two 47 arguments should be used in most instances. 48 49 50 .. function:: hashopen(filename[, flag[, mode[, pgsize[, ffactor[, nelem[, cachesize[, lorder[, hflags]]]]]]]]) 51 52 Open the hash format file named *filename*. Files never intended to be 53 preserved on disk may be created by passing ``None`` as the *filename*. The 54 optional *flag* identifies the mode used to open the file. It may be ``'r'`` 55 (read only), ``'w'`` (read-write), ``'c'`` (read-write - create if necessary; 56 the default) or ``'n'`` (read-write - truncate to zero length). The other 57 arguments are rarely used and are just passed to the low-level :c:func:`dbopen` 58 function. Consult the Berkeley DB documentation for their use and 59 interpretation. 60 61 62 .. function:: btopen(filename[, flag[, mode[, btflags[, cachesize[, maxkeypage[, minkeypage[, pgsize[, lorder]]]]]]]]) 63 64 Open the btree format file named *filename*. Files never intended to be 65 preserved on disk may be created by passing ``None`` as the *filename*. The 66 optional *flag* identifies the mode used to open the file. It may be ``'r'`` 67 (read only), ``'w'`` (read-write), ``'c'`` (read-write - create if necessary; 68 the default) or ``'n'`` (read-write - truncate to zero length). The other 69 arguments are rarely used and are just passed to the low-level dbopen function. 70 Consult the Berkeley DB documentation for their use and interpretation. 71 72 73 .. function:: rnopen(filename[, flag[, mode[, rnflags[, cachesize[, pgsize[, lorder[, rlen[, delim[, source[, pad]]]]]]]]]]) 74 75 Open a DB record format file named *filename*. Files never intended to be 76 preserved on disk may be created by passing ``None`` as the *filename*. The 77 optional *flag* identifies the mode used to open the file. It may be ``'r'`` 78 (read only), ``'w'`` (read-write), ``'c'`` (read-write - create if necessary; 79 the default) or ``'n'`` (read-write - truncate to zero length). The other 80 arguments are rarely used and are just passed to the low-level dbopen function. 81 Consult the Berkeley DB documentation for their use and interpretation. 82 83 .. note:: 84 85 Beginning in 2.3 some Unix versions of Python may have a :mod:`bsddb185` module. 86 This is present *only* to allow backwards compatibility with systems which ship 87 with the old Berkeley DB 1.85 database library. The :mod:`bsddb185` module 88 should never be used directly in new code. The module has been removed in 89 Python 3. If you find you still need it look in PyPI. 90 91 92 .. seealso:: 93 94 Module :mod:`dbhash` 95 DBM-style interface to the :mod:`bsddb` 96 97 98 .. _bsddb-objects: 99 100 Hash, BTree and Record Objects 101 ------------------------------ 102 103 Once instantiated, hash, btree and record objects support the same methods as 104 dictionaries. In addition, they support the methods listed below. 105 106 .. versionchanged:: 2.3.1 107 Added dictionary methods. 108 109 110 .. method:: bsddbobject.close() 111 112 Close the underlying file. The object can no longer be accessed. Since there 113 is no open :meth:`open` method for these objects, to open the file again a new 114 :mod:`bsddb` module open function must be called. 115 116 117 .. method:: bsddbobject.keys() 118 119 Return the list of keys contained in the DB file. The order of the list is 120 unspecified and should not be relied on. In particular, the order of the list 121 returned is different for different file formats. 122 123 124 .. method:: bsddbobject.has_key(key) 125 126 Return ``1`` if the DB file contains the argument as a key. 127 128 129 .. method:: bsddbobject.set_location(key) 130 131 Set the cursor to the item indicated by *key* and return a tuple containing the 132 key and its value. For binary tree databases (opened using :func:`btopen`), if 133 *key* does not actually exist in the database, the cursor will point to the next 134 item in sorted order and return that key and value. For other databases, 135 :exc:`KeyError` will be raised if *key* is not found in the database. 136 137 138 .. method:: bsddbobject.first() 139 140 Set the cursor to the first item in the DB file and return it. The order of 141 keys in the file is unspecified, except in the case of B-Tree databases. This 142 method raises :exc:`bsddb.error` if the database is empty. 143 144 145 .. method:: bsddbobject.next() 146 147 Set the cursor to the next item in the DB file and return it. The order of 148 keys in the file is unspecified, except in the case of B-Tree databases. 149 150 151 .. method:: bsddbobject.previous() 152 153 Set the cursor to the previous item in the DB file and return it. The order of 154 keys in the file is unspecified, except in the case of B-Tree databases. This 155 is not supported on hashtable databases (those opened with :func:`hashopen`). 156 157 158 .. method:: bsddbobject.last() 159 160 Set the cursor to the last item in the DB file and return it. The order of keys 161 in the file is unspecified. This is not supported on hashtable databases (those 162 opened with :func:`hashopen`). This method raises :exc:`bsddb.error` if the 163 database is empty. 164 165 166 .. method:: bsddbobject.sync() 167 168 Synchronize the database on disk. 169 170 Example:: 171 172 >>> import bsddb 173 >>> db = bsddb.btopen('spam.db', 'c') 174 >>> for i in range(10): db['%d'%i] = '%d'% (i*i) 175 ... 176 >>> db['3'] 177 '9' 178 >>> db.keys() 179 ['0', '1', '2', '3', '4', '5', '6', '7', '8', '9'] 180 >>> db.first() 181 ('0', '0') 182 >>> db.next() 183 ('1', '1') 184 >>> db.last() 185 ('9', '81') 186 >>> db.set_location('2') 187 ('2', '4') 188 >>> db.previous() 189 ('1', '1') 190 >>> for k, v in db.iteritems(): 191 ... print k, v 192 0 0 193 1 1 194 2 4 195 3 9 196 4 16 197 5 25 198 6 36 199 7 49 200 8 64 201 9 81 202 >>> '8' in db 203 True 204 >>> db.sync() 205 0 206 207
