Doc/lib/libdbhash.tex

\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}