source: trunk/essentials/dev-lang/python/Doc/lib/libdbhash.tex@ 3368

\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.}{[email protected]}


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}