blob: 61b01639fd910cf58b2b91aa0e7b516a38ee4a81 [file] [log] [blame]
\section{\module{dbhash} ---
DBM-style interface to the BSD database library}
\declaremodule{standard}{dbhash}
\platform{Unix, Windows}
\modulesynopsis{DBM-style interface to the BSD database library.}
\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
The \module{dbhash} module provides a function to open databases using
the BSD \code{db} library. This module mirrors the interface of the
other Python database modules that provide access to DBM-style
databases. The \refmodule{bsddb}\refbimodindex{bsddb} module is required
to use \module{dbhash}.
This module provides an exception and a function:
\begin{excdesc}{error}
Exception raised on database errors other than
\exception{KeyError}. It is a synonym for \exception{bsddb.error}.
\end{excdesc}
\begin{funcdesc}{open}{path, flag\optional{, mode}}
Open a \code{db} database and return the database object. The
\var{path} argument is the name of the database file.
The \var{flag} argument can be
\code{'r'} (the default), \code{'w'},
\code{'c'} (which creates the database if it doesn't exist), or
\code{'n'} (which always creates a new empty database).
For platforms on which the BSD \code{db} library supports locking,
an \character{l} can be appended to indicate that locking should be
used.
The optional \var{mode} parameter is used to indicate the \UNIX{}
permission bits that should be set if a new database must be
created; this will be masked by the current umask value for the
process.
\end{funcdesc}
\begin{seealso}
\seemodule{anydbm}{Generic interface to \code{dbm}-style databases.}
\seemodule{bsddb}{Lower-level interface to the BSD \code{db} library.}
\seemodule{whichdb}{Utility module used to determine the type of an
existing database.}
\end{seealso}
\subsection{Database Objects \label{dbhash-objects}}
The database objects returned by \function{open()} provide the methods
common to all the DBM-style databases. The following methods are
available in addition to the standard methods.
\begin{methoddesc}[dbhash]{first}{}
It's possible to loop over every key in the database using this method
and the \method{next()} method. The traversal is ordered by
the databases internal hash values, and won't be sorted by the key
values. This method returns the starting key.
\end{methoddesc}
\begin{methoddesc}[dbhash]{last}{}
Return the last key in a database traversal. This may be used to
begin a reverse-order traversal; see \method{previous()}.
\end{methoddesc}
\begin{methoddesc}[dbhash]{next}{key}
Returns the key that follows \var{key} in the traversal. The
following code prints every key in the database \code{db}, without
having to create a list in memory that contains them all:
\begin{verbatim}
k = db.first()
while k != None:
print k
k = db.next(k)
\end{verbatim}
\end{methoddesc}
\begin{methoddesc}[dbhash]{previous}{key}
Return the key that comes before \var{key} in a forward-traversal of
the database. In conjunction with \method{last()}, this may be used
to implement a reverse-order traversal.
\end{methoddesc}
\begin{methoddesc}[dbhash]{sync}{}
This method forces any unwritten data to be written to the disk.
\end{methoddesc}