Fred Drake | 9d15881 | 1999-04-19 21:19:21 +0000 | [diff] [blame] | 1 | \section{\module{bsddb} --- |
| 2 | Interface to Berkeley DB library} |
| 3 | |
| 4 | \declaremodule{extension}{bsddb} |
| 5 | \platform{Unix, Windows} |
| 6 | \modulesynopsis{Interface to Berkeley DB database library} |
| 7 | \sectionauthor{Skip Montanaro}{skip@mojam.com} |
| 8 | |
| 9 | |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 10 | The \module{bsddb} module provides an interface to the Berkeley DB |
| 11 | library. Users can create hash, btree or record based library files |
| 12 | using the appropriate open call. Bsddb objects behave generally like |
| 13 | dictionaries. Keys and values must be strings, however, so to use |
| 14 | other objects as keys or to store other kinds of objects the user must |
Andrew M. Kuchling | 9747301 | 2005-12-22 20:12:54 +0000 | [diff] [blame] | 15 | serialize them somehow, typically using \function{marshal.dumps()} or |
| 16 | \function{pickle.dumps}. |
Fred Drake | 9d15881 | 1999-04-19 21:19:21 +0000 | [diff] [blame] | 17 | |
Gregory P. Smith | 5772513 | 2003-05-28 07:56:45 +0000 | [diff] [blame] | 18 | Starting with Python 2.3 the \module{bsddb} module requires the |
Gregory P. Smith | b845ef0 | 2003-11-13 08:30:03 +0000 | [diff] [blame] | 19 | Berkeley DB library version 3.2 or later (it is known to work with 3.2 |
Raymond Hettinger | 6880431 | 2005-01-01 00:28:46 +0000 | [diff] [blame] | 20 | through 4.3 at the time of this writing). |
Gregory P. Smith | 5772513 | 2003-05-28 07:56:45 +0000 | [diff] [blame] | 21 | |
Gregory P. Smith | 5772513 | 2003-05-28 07:56:45 +0000 | [diff] [blame] | 22 | \begin{seealso} |
| 23 | \seeurl{http://pybsddb.sourceforge.net/}{Website with documentation |
| 24 | for the new python Berkeley DB interface that closely mirrors the |
| 25 | sleepycat object oriented interface provided in Berkeley DB 3 and 4.} |
| 26 | \seeurl{http://www.sleepycat.com/}{Sleepycat Software produces the |
Gregory P. Smith | dad5860 | 2003-05-28 16:20:03 +0000 | [diff] [blame] | 27 | modern Berkeley DB library.} |
Gregory P. Smith | 5772513 | 2003-05-28 07:56:45 +0000 | [diff] [blame] | 28 | \end{seealso} |
| 29 | |
| 30 | The following is a description of the legacy \module{bsddb} interface |
| 31 | compatible with the old python bsddb module. For details about the more |
| 32 | modern Db and DbEnv object oriented interface see the above mentioned |
| 33 | pybsddb URL. |
Fred Drake | 9d15881 | 1999-04-19 21:19:21 +0000 | [diff] [blame] | 34 | |
| 35 | The \module{bsddb} module defines the following functions that create |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 36 | objects that access the appropriate type of Berkeley DB file. The |
| 37 | first two arguments of each function are the same. For ease of |
| 38 | portability, only the first two arguments should be used in most |
| 39 | instances. |
Fred Drake | 9d15881 | 1999-04-19 21:19:21 +0000 | [diff] [blame] | 40 | |
| 41 | \begin{funcdesc}{hashopen}{filename\optional{, flag\optional{, |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 42 | mode\optional{, bsize\optional{, |
| 43 | ffactor\optional{, nelem\optional{, |
| 44 | cachesize\optional{, hash\optional{, |
| 45 | lorder}}}}}}}}} |
Anthony Baxter | 8388895 | 2002-04-23 02:11:05 +0000 | [diff] [blame] | 46 | Open the hash format file named \var{filename}. Files never intended |
| 47 | to be preserved on disk may be created by passing \code{None} as the |
| 48 | \var{filename}. The optional |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 49 | \var{flag} identifies the mode used to open the file. It may be |
Fred Drake | fdccf1a | 2004-07-26 16:33:29 +0000 | [diff] [blame] | 50 | \character{r} (read only), \character{w} (read-write) , |
| 51 | \character{c} (read-write - create if necessary; the default) or |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 52 | \character{n} (read-write - truncate to zero length). The other |
| 53 | arguments are rarely used and are just passed to the low-level |
| 54 | \cfunction{dbopen()} function. Consult the Berkeley DB documentation |
| 55 | for their use and interpretation. |
Fred Drake | 9d15881 | 1999-04-19 21:19:21 +0000 | [diff] [blame] | 56 | \end{funcdesc} |
| 57 | |
Fred Drake | 9d15881 | 1999-04-19 21:19:21 +0000 | [diff] [blame] | 58 | \begin{funcdesc}{btopen}{filename\optional{, flag\optional{, |
| 59 | mode\optional{, btflags\optional{, cachesize\optional{, maxkeypage\optional{, |
Andrew M. Kuchling | 8dbe1a7 | 2005-06-08 21:51:28 +0000 | [diff] [blame] | 60 | minkeypage\optional{, pgsize\optional{, lorder}}}}}}}}} |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 61 | |
Anthony Baxter | 8388895 | 2002-04-23 02:11:05 +0000 | [diff] [blame] | 62 | Open the btree format file named \var{filename}. Files never intended |
| 63 | to be preserved on disk may be created by passing \code{None} as the |
| 64 | \var{filename}. The optional |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 65 | \var{flag} identifies the mode used to open the file. It may be |
Fred Drake | fdccf1a | 2004-07-26 16:33:29 +0000 | [diff] [blame] | 66 | \character{r} (read only), \character{w} (read-write), |
| 67 | \character{c} (read-write - create if necessary; the default) or |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 68 | \character{n} (read-write - truncate to zero length). The other |
| 69 | arguments are rarely used and are just passed to the low-level dbopen |
| 70 | function. Consult the Berkeley DB documentation for their use and |
| 71 | interpretation. |
Fred Drake | 9d15881 | 1999-04-19 21:19:21 +0000 | [diff] [blame] | 72 | \end{funcdesc} |
| 73 | |
| 74 | \begin{funcdesc}{rnopen}{filename\optional{, flag\optional{, mode\optional{, |
Andrew M. Kuchling | 8dbe1a7 | 2005-06-08 21:51:28 +0000 | [diff] [blame] | 75 | rnflags\optional{, cachesize\optional{, pgsize\optional{, lorder\optional{, |
Fred Drake | 9d15881 | 1999-04-19 21:19:21 +0000 | [diff] [blame] | 76 | reclen\optional{, bval\optional{, bfname}}}}}}}}}} |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 77 | |
Anthony Baxter | 8388895 | 2002-04-23 02:11:05 +0000 | [diff] [blame] | 78 | Open a DB record format file named \var{filename}. Files never intended |
| 79 | to be preserved on disk may be created by passing \code{None} as the |
| 80 | \var{filename}. The optional |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 81 | \var{flag} identifies the mode used to open the file. It may be |
Fred Drake | fdccf1a | 2004-07-26 16:33:29 +0000 | [diff] [blame] | 82 | \character{r} (read only), \character{w} (read-write), |
| 83 | \character{c} (read-write - create if necessary; the default) or |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 84 | \character{n} (read-write - truncate to zero length). The other |
| 85 | arguments are rarely used and are just passed to the low-level dbopen |
| 86 | function. Consult the Berkeley DB documentation for their use and |
| 87 | interpretation. |
Fred Drake | 9d15881 | 1999-04-19 21:19:21 +0000 | [diff] [blame] | 88 | \end{funcdesc} |
| 89 | |
| 90 | |
Skip Montanaro | 6d9f45b | 2003-05-06 20:40:17 +0000 | [diff] [blame] | 91 | \begin{notice} |
| 92 | Beginning in 2.3 some Unix versions of Python may have a \module{bsddb185} |
| 93 | module. This is present \emph{only} to allow backwards compatibility with |
| 94 | systems which ship with the old Berkeley DB 1.85 database library. The |
| 95 | \module{bsddb185} module should never be used directly in new code. |
| 96 | \end{notice} |
Fred Drake | 9d15881 | 1999-04-19 21:19:21 +0000 | [diff] [blame] | 97 | |
Fred Drake | b86aa99 | 2004-06-24 06:03:59 +0000 | [diff] [blame] | 98 | |
| 99 | \begin{seealso} |
| 100 | \seemodule{dbhash}{DBM-style interface to the \module{bsddb}} |
| 101 | \end{seealso} |
| 102 | |
Fred Drake | 9d15881 | 1999-04-19 21:19:21 +0000 | [diff] [blame] | 103 | \subsection{Hash, BTree and Record Objects \label{bsddb-objects}} |
| 104 | |
Raymond Hettinger | deadbf5 | 2003-09-12 06:33:37 +0000 | [diff] [blame] | 105 | Once instantiated, hash, btree and record objects support |
| 106 | the same methods as dictionaries. In addition, they support |
Raymond Hettinger | 3404034 | 2003-09-16 21:45:22 +0000 | [diff] [blame] | 107 | the methods listed below. |
| 108 | \versionchanged[Added dictionary methods]{2.3.1} |
Fred Drake | 9d15881 | 1999-04-19 21:19:21 +0000 | [diff] [blame] | 109 | |
| 110 | \begin{methoddesc}{close}{} |
| 111 | Close the underlying file. The object can no longer be accessed. Since |
| 112 | there is no open \method{open} method for these objects, to open the file |
| 113 | again a new \module{bsddb} module open function must be called. |
| 114 | \end{methoddesc} |
| 115 | |
| 116 | \begin{methoddesc}{keys}{} |
| 117 | Return the list of keys contained in the DB file. The order of the list is |
| 118 | unspecified and should not be relied on. In particular, the order of the |
| 119 | list returned is different for different file formats. |
| 120 | \end{methoddesc} |
| 121 | |
| 122 | \begin{methoddesc}{has_key}{key} |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 123 | Return \code{1} if the DB file contains the argument as a key. |
Fred Drake | 9d15881 | 1999-04-19 21:19:21 +0000 | [diff] [blame] | 124 | \end{methoddesc} |
| 125 | |
| 126 | \begin{methoddesc}{set_location}{key} |
Fred Drake | e1d4715 | 2001-01-05 06:44:19 +0000 | [diff] [blame] | 127 | Set the cursor to the item indicated by \var{key} and return a tuple |
| 128 | containing the key and its value. For binary tree databases (opened |
| 129 | using \function{btopen()}), if \var{key} does not actually exist in |
| 130 | the database, the cursor will point to the next item in sorted order |
| 131 | and return that key and value. For other databases, |
| 132 | \exception{KeyError} will be raised if \var{key} is not found in the |
| 133 | database. |
Fred Drake | 9d15881 | 1999-04-19 21:19:21 +0000 | [diff] [blame] | 134 | \end{methoddesc} |
| 135 | |
| 136 | \begin{methoddesc}{first}{} |
| 137 | Set the cursor to the first item in the DB file and return it. The order of |
Fred Drake | 29cf682 | 1999-04-23 20:32:59 +0000 | [diff] [blame] | 138 | keys in the file is unspecified, except in the case of B-Tree databases. |
Fred Drake | ba100c9 | 2004-08-10 19:22:48 +0000 | [diff] [blame] | 139 | This method raises \exception{bsddb.error} if the database is empty. |
Fred Drake | 9d15881 | 1999-04-19 21:19:21 +0000 | [diff] [blame] | 140 | \end{methoddesc} |
| 141 | |
| 142 | \begin{methoddesc}{next}{} |
| 143 | Set the cursor to the next item in the DB file and return it. The order of |
Fred Drake | 29cf682 | 1999-04-23 20:32:59 +0000 | [diff] [blame] | 144 | keys in the file is unspecified, except in the case of B-Tree databases. |
Fred Drake | 9d15881 | 1999-04-19 21:19:21 +0000 | [diff] [blame] | 145 | \end{methoddesc} |
| 146 | |
| 147 | \begin{methoddesc}{previous}{} |
Skip Montanaro | 6141812 | 2002-11-17 11:09:50 +0000 | [diff] [blame] | 148 | Set the cursor to the previous item in the DB file and return it. The |
Fred Drake | 29cf682 | 1999-04-23 20:32:59 +0000 | [diff] [blame] | 149 | order of keys in the file is unspecified, except in the case of B-Tree |
| 150 | databases. This is not supported on hashtable databases (those opened |
| 151 | with \function{hashopen()}). |
Fred Drake | 9d15881 | 1999-04-19 21:19:21 +0000 | [diff] [blame] | 152 | \end{methoddesc} |
| 153 | |
| 154 | \begin{methoddesc}{last}{} |
Fred Drake | 2ea30f4 | 1999-04-22 14:06:36 +0000 | [diff] [blame] | 155 | Set the cursor to the last item in the DB file and return it. The |
| 156 | order of keys in the file is unspecified. This is not supported on |
| 157 | hashtable databases (those opened with \function{hashopen()}). |
Fred Drake | ba100c9 | 2004-08-10 19:22:48 +0000 | [diff] [blame] | 158 | This method raises \exception{bsddb.error} if the database is empty. |
Fred Drake | 9d15881 | 1999-04-19 21:19:21 +0000 | [diff] [blame] | 159 | \end{methoddesc} |
| 160 | |
| 161 | \begin{methoddesc}{sync}{} |
| 162 | Synchronize the database on disk. |
| 163 | \end{methoddesc} |
| 164 | |
| 165 | Example: |
| 166 | |
| 167 | \begin{verbatim} |
| 168 | >>> import bsddb |
| 169 | >>> db = bsddb.btopen('/tmp/spam.db', 'c') |
| 170 | >>> for i in range(10): db['%d'%i] = '%d'% (i*i) |
| 171 | ... |
| 172 | >>> db['3'] |
| 173 | '9' |
| 174 | >>> db.keys() |
| 175 | ['0', '1', '2', '3', '4', '5', '6', '7', '8', '9'] |
| 176 | >>> db.first() |
| 177 | ('0', '0') |
| 178 | >>> db.next() |
| 179 | ('1', '1') |
| 180 | >>> db.last() |
| 181 | ('9', '81') |
| 182 | >>> db.set_location('2') |
| 183 | ('2', '4') |
| 184 | >>> db.previous() |
| 185 | ('1', '1') |
Raymond Hettinger | deadbf5 | 2003-09-12 06:33:37 +0000 | [diff] [blame] | 186 | >>> for k, v in db.iteritems(): |
| 187 | ... print k, v |
| 188 | 0 0 |
| 189 | 1 1 |
| 190 | 2 4 |
| 191 | 3 9 |
| 192 | 4 16 |
| 193 | 5 25 |
| 194 | 6 36 |
| 195 | 7 49 |
| 196 | 8 64 |
| 197 | 9 81 |
Raymond Hettinger | ff294fe | 2003-12-07 13:00:25 +0000 | [diff] [blame] | 198 | >>> '8' in db |
Raymond Hettinger | deadbf5 | 2003-09-12 06:33:37 +0000 | [diff] [blame] | 199 | True |
Fred Drake | 9d15881 | 1999-04-19 21:19:21 +0000 | [diff] [blame] | 200 | >>> db.sync() |
| 201 | 0 |
| 202 | \end{verbatim} |