mirror of https://github.com/python/cpython
90 lines
3.2 KiB
TeX
90 lines
3.2 KiB
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.}
|
||
|
|
|
||
|
|
|
||
|
|
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}
|