mirror of https://github.com/python/cpython
178 lines
7.0 KiB
TeX
178 lines
7.0 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.
|
|
|
|
There are two incompatible versions of the underlying library.
|
|
Version 1.85 is widely available, but has some known bugs. Version 2
|
|
is not quite as widely used, but does offer some improvements. The
|
|
\module{bsddb} module uses the 1.85 interface. Starting with Python
|
|
2.0, the \program{configure} script can usually determine the
|
|
version of the library which is available and build it correctly. If
|
|
you have difficulty getting \program{configure} to do the right thing,
|
|
run it with the \longprogramopt{help} option to get information about
|
|
additional options that can help. On Windows, you will need to define
|
|
the \code{HAVE_DB_185_H} macro if you are building Python from source
|
|
and using version 2 of the DB library.
|
|
|
|
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) 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) 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) 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 following
|
|
methods:
|
|
|
|
\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')
|
|
>>> db.sync()
|
|
0
|
|
\end{verbatim}
|