ref: 5b7d8e1f6fb4167e354545fef7e6dd6676986441
dir: /sys/src/cmd/python/Doc/lib/libdbhash.tex/
\section{\module{dbhash} ---
DBM-style interface to the BSD database library}
\declaremodule{standard}{dbhash}
\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\optional{, 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 and mapping objects. The following
methods are available in addition to the standard methods.
\begin{methoddesc}[dbhash]{first}{}
It's possible to loop over every key/value pair 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/value pair in a database traversal. This may be used to
begin a reverse-order traversal; see \method{previous()}.
\end{methoddesc}
\begin{methoddesc}[dbhash]{next}{}
Returns the key next key/value pair in a database 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}
print db.first()
for i in xrange(1, len(db)):
print db.next()
\end{verbatim}
\end{methoddesc}
\begin{methoddesc}[dbhash]{previous}{}
Returns the previous key/value pair 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}