| \section{\module{bsddb} --- |
| Interface to Berkeley DB library} |
| |
| \declaremodule{extension}{bsddb} |
| \platform{Unix, Windows} |
| \modulesynopsis{Interface to Berkeley DB database library} |
| \sectionauthor{Skip Montanaro}{skip@mojam.com} |
| |
| |
| The \module{bsddb} module provides an interface to the Berkeley DB |
| library. Users can create hash, btree or record based library files |
| using the appropriate open call. Bsddb objects behave generally like |
| dictionaries. Keys and values must be strings, however, so to use |
| other objects as keys or to store other kinds of objects the user must |
| serialize them somehow, typically using marshal.dumps or pickle.dumps. |
| |
| Starting with Python 2.3 the \module{bsddb} module requires the |
| Berkeley DB library version 3.1 or later (it is known to work with 3.1 |
| thru 4.1 at the time of this writing). |
| |
| \begin{seealso} |
| \seeurl{http://pybsddb.sourceforge.net/}{Website with documentation |
| for the new python Berkeley DB interface that closely mirrors the |
| sleepycat object oriented interface provided in Berkeley DB 3 and 4.} |
| \seeurl{http://www.sleepycat.com/}{Sleepycat Software produces the |
| modern Berkeley DB library.} |
| \end{seealso} |
| |
| The following is a description of the legacy \module{bsddb} interface |
| compatible with the old python bsddb module. For details about the more |
| modern Db and DbEnv object oriented interface see the above mentioned |
| pybsddb URL. |
| |
| The \module{bsddb} module defines the following functions that create |
| objects that access the appropriate type of Berkeley DB file. The |
| first two arguments of each function are the same. For ease of |
| portability, only the first two arguments should be used in most |
| instances. |
| |
| \begin{funcdesc}{hashopen}{filename\optional{, flag\optional{, |
| mode\optional{, bsize\optional{, |
| ffactor\optional{, nelem\optional{, |
| cachesize\optional{, hash\optional{, |
| lorder}}}}}}}}} |
| Open the hash format file named \var{filename}. Files never intended |
| to be preserved on disk may be created by passing \code{None} as the |
| \var{filename}. The optional |
| \var{flag} identifies the mode used to open the file. It may be |
| \character{r} (read only, default), \character{w} (read-write) , |
| \character{c} (read-write - create if necessary) or |
| \character{n} (read-write - truncate to zero length). The other |
| arguments are rarely used and are just passed to the low-level |
| \cfunction{dbopen()} function. Consult the Berkeley DB documentation |
| for their use and interpretation. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{btopen}{filename\optional{, flag\optional{, |
| mode\optional{, btflags\optional{, cachesize\optional{, maxkeypage\optional{, |
| minkeypage\optional{, psize\optional{, lorder}}}}}}}}} |
| |
| Open the btree format file named \var{filename}. Files never intended |
| to be preserved on disk may be created by passing \code{None} as the |
| \var{filename}. The optional |
| \var{flag} identifies the mode used to open the file. It may be |
| \character{r} (read only, default), \character{w} (read-write), |
| \character{c} (read-write - create if necessary) or |
| \character{n} (read-write - truncate to zero length). The other |
| arguments are rarely used and are just passed to the low-level dbopen |
| function. Consult the Berkeley DB documentation for their use and |
| interpretation. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{rnopen}{filename\optional{, flag\optional{, mode\optional{, |
| rnflags\optional{, cachesize\optional{, psize\optional{, lorder\optional{, |
| reclen\optional{, bval\optional{, bfname}}}}}}}}}} |
| |
| Open a DB record format file named \var{filename}. Files never intended |
| to be preserved on disk may be created by passing \code{None} as the |
| \var{filename}. The optional |
| \var{flag} identifies the mode used to open the file. It may be |
| \character{r} (read only, default), \character{w} (read-write), |
| \character{c} (read-write - create if necessary) or |
| \character{n} (read-write - truncate to zero length). The other |
| arguments are rarely used and are just passed to the low-level dbopen |
| function. Consult the Berkeley DB documentation for their use and |
| interpretation. |
| \end{funcdesc} |
| |
| |
| \begin{seealso} |
| \seemodule{dbhash}{DBM-style interface to the \module{bsddb}} |
| \end{seealso} |
| |
| \begin{notice} |
| Beginning in 2.3 some Unix versions of Python may have a \module{bsddb185} |
| module. This is present \emph{only} to allow backwards compatibility with |
| systems which ship with the old Berkeley DB 1.85 database library. The |
| \module{bsddb185} module should never be used directly in new code. |
| \end{notice} |
| |
| \subsection{Hash, BTree and Record Objects \label{bsddb-objects}} |
| |
| Once instantiated, hash, btree and record objects support |
| the same methods as dictionaries. In addition, they support |
| the methods listed below. |
| \versionchanged[Added dictionary methods]{2.3.1} |
| |
| \begin{methoddesc}{close}{} |
| Close the underlying file. The object can no longer be accessed. Since |
| there is no open \method{open} method for these objects, to open the file |
| again a new \module{bsddb} module open function must be called. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{keys}{} |
| Return the list of keys contained in the DB file. The order of the list is |
| unspecified and should not be relied on. In particular, the order of the |
| list returned is different for different file formats. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{has_key}{key} |
| Return \code{1} if the DB file contains the argument as a key. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{set_location}{key} |
| Set the cursor to the item indicated by \var{key} and return a tuple |
| containing the key and its value. For binary tree databases (opened |
| using \function{btopen()}), if \var{key} does not actually exist in |
| the database, the cursor will point to the next item in sorted order |
| and return that key and value. For other databases, |
| \exception{KeyError} will be raised if \var{key} is not found in the |
| database. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{first}{} |
| Set the cursor to the first item in the DB file and return it. The order of |
| keys in the file is unspecified, except in the case of B-Tree databases. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{next}{} |
| Set the cursor to the next item in the DB file and return it. The order of |
| keys in the file is unspecified, except in the case of B-Tree databases. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{previous}{} |
| Set the cursor to the previous item in the DB file and return it. The |
| order of keys in the file is unspecified, except in the case of B-Tree |
| databases. This is not supported on hashtable databases (those opened |
| with \function{hashopen()}). |
| \end{methoddesc} |
| |
| \begin{methoddesc}{last}{} |
| Set the cursor to the last item in the DB file and return it. The |
| order of keys in the file is unspecified. This is not supported on |
| hashtable databases (those opened with \function{hashopen()}). |
| \end{methoddesc} |
| |
| \begin{methoddesc}{sync}{} |
| Synchronize the database on disk. |
| \end{methoddesc} |
| |
| Example: |
| |
| \begin{verbatim} |
| >>> import bsddb |
| >>> db = bsddb.btopen('/tmp/spam.db', 'c') |
| >>> for i in range(10): db['%d'%i] = '%d'% (i*i) |
| ... |
| >>> db['3'] |
| '9' |
| >>> db.keys() |
| ['0', '1', '2', '3', '4', '5', '6', '7', '8', '9'] |
| >>> db.first() |
| ('0', '0') |
| >>> db.next() |
| ('1', '1') |
| >>> db.last() |
| ('9', '81') |
| >>> db.set_location('2') |
| ('2', '4') |
| >>> db.previous() |
| ('1', '1') |
| >>> for k, v in db.iteritems(): |
| ... print k, v |
| 0 0 |
| 1 1 |
| 2 4 |
| 3 9 |
| 4 16 |
| 5 25 |
| 6 36 |
| 7 49 |
| 8 64 |
| 9 81 |
| >>> 8 in db |
| True |
| >>> db.sync() |
| 0 |
| \end{verbatim} |