| \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.} |
| |
| |
| 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 \module{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'} (to open an existing database for reading only --- default), |
| \code{'w'} (to open an existing database for reading and writing), |
| \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{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} |