mirror of https://github.com/python/cpython
200 lines
7.3 KiB
TeX
200 lines
7.3 KiB
TeX
\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.2 or later (it is known to work with 3.2
|
|
thru 4.2 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), \character{w} (read-write) ,
|
|
\character{c} (read-write - create if necessary; the default) 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), \character{w} (read-write),
|
|
\character{c} (read-write - create if necessary; the default) 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), \character{w} (read-write),
|
|
\character{c} (read-write - create if necessary; the default) 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{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}
|
|
|
|
|
|
\begin{seealso}
|
|
\seemodule{dbhash}{DBM-style interface to the \module{bsddb}}
|
|
\end{seealso}
|
|
|
|
\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}
|