212 lines
8.0 KiB
TeX
212 lines
8.0 KiB
TeX
\section{\module{bsddb} ---
|
|
Interface to Berkeley DB library}
|
|
|
|
\declaremodule{extension}{bsddb}
|
|
\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 \function{marshal.dumps()} or
|
|
\function{pickle.dumps()}.
|
|
|
|
The \module{bsddb} module requires a Berkeley DB library version from
|
|
3.3 thru 4.5.
|
|
|
|
\begin{seealso}
|
|
\seeurl{http://pybsddb.sourceforge.net/}
|
|
{The website with documentation for the \module{bsddb.db}
|
|
Python Berkeley DB interface that closely mirrors the object
|
|
oriented interface provided in Berkeley DB 3 and 4.}
|
|
|
|
\seeurl{http://www.oracle.com/database/berkeley-db/}
|
|
{The Berkeley DB library.}
|
|
\end{seealso}
|
|
|
|
A more modern DB, DBEnv and DBSequence object interface is available in the
|
|
\module{bsddb.db} module which closely matches the Berkeley DB C API
|
|
documented at the above URLs. Additional features provided by the
|
|
\module{bsddb.db} API include fine tuning, transactions, logging, and
|
|
multiprocess concurrent database access.
|
|
|
|
The following is a description of the legacy \module{bsddb} interface
|
|
compatible with the old Python bsddb module. Starting in Python 2.5 this
|
|
interface should be safe for multithreaded access. The \module{bsddb.db}
|
|
API is recommended for threading users as it provides better control.
|
|
|
|
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{, pgsize\optional{,
|
|
ffactor\optional{, nelem\optional{,
|
|
cachesize\optional{, lorder\optional{,
|
|
hflags}}}}}}}}}
|
|
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{, pgsize\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{, pgsize\optional{, lorder\optional{,
|
|
rlen\optional{, delim\optional{, source\optional{, pad}}}}}}}}}}}
|
|
|
|
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{classdesc}{StringKeys}{db}
|
|
Wrapper class around a DB object that supports string keys
|
|
(rather than bytes). All keys are encoded as UTF-8, then passed
|
|
to the underlying object. \versionadded{3.0}
|
|
\end{classdesc}
|
|
|
|
\begin{classdesc}{StringValues}{db}
|
|
Wrapper class around a DB object that supports string values
|
|
(rather than bytes). All values are encoded as UTF-8, then passed
|
|
to the underlying object. \versionadded{3.0}
|
|
\end{classdesc}
|
|
|
|
\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}[bsddbobject]{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}[bsddbobject]{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}[bsddbobject]{has_key}{key}
|
|
Return \code{1} if the DB file contains the argument as a key.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[bsddbobject]{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}[bsddbobject]{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.
|
|
This method raises \exception{bsddb.error} if the database is empty.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[bsddbobject]{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}[bsddbobject]{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}[bsddbobject]{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()}).
|
|
This method raises \exception{bsddb.error} if the database is empty.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[bsddbobject]{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}
|