Document the dbhash module, and link to it from appropriate places.

4 files changed, 94 insertions, 3 deletions

diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex
index 214674b..08b36de 100644
--- a/Doc/lib/lib.tex
+++ b/Doc/lib/lib.tex
@@ -143,6 +143,7 @@ add new extensions to Python and how to embed it in other applications.
 \input{libthreading}
 \input{libqueue}
 \input{libanydbm}
+\input{libdbhash}
 \input{libwhichdb}
 \input{libzlib}
 \input{libgzip}
diff --git a/Doc/lib/libanydbm.tex b/Doc/lib/libanydbm.tex
index c05e3ac..4df6628 100644
--- a/Doc/lib/libanydbm.tex
+++ b/Doc/lib/libanydbm.tex
@@ -6,7 +6,8 @@
 
 
 \module{anydbm} is a generic interface to variants of the DBM
-database --- \module{dbhash}\refbimodindex{dbhash},
+database --- \refmodule{dbhash}\refstmodindex{dbhash} (requires
+\module{bsddb}\refbimodindex{bsddb}),
 \refmodule{gdbm}\refbimodindex{gdbm}, or
 \refmodule{dbm}\refbimodindex{dbm}.  If none of these modules is
 installed, the slow-but-simple implementation in module
@@ -48,7 +49,7 @@ strings.
 
 \begin{seealso}
   \seemodule{anydbm}{Generic interface to \code{dbm}-style databases.}
-  % Should include entry for dbhash, but that isn't documented.
+  \seemodule{dbhash}{BSD \code{db} database interface.}
   \seemodule{dbm}{Standard \UNIX{} database interface.}
   \seemodule{dumbdbm}{Portable implementation of the \code{dbm} interface.}
   \seemodule{gdbm}{GNU database interface, based on the \code{dbm} interface.}
diff --git a/Doc/lib/libdbhash.tex b/Doc/lib/libdbhash.tex
new file mode 100644
index 0000000..e2ac326
--- /dev/null
+++ b/Doc/lib/libdbhash.tex
@@ -0,0 +1,89 @@
+\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}
diff --git a/Doc/lib/libshelve.tex b/Doc/lib/libshelve.tex
index 6b96872..de8e04c 100644
--- a/Doc/lib/libshelve.tex
+++ b/Doc/lib/libshelve.tex
@@ -66,7 +66,7 @@ requires knowledge about the database implementation used.
 
 \begin{seealso}
   \seemodule{anydbm}{Generic interface to \code{dbm}-style databases.}
-  % Should include entry for dbhash, but that isn't documented.
+  \seemodule{dbhash}{BSD \code{db} database interface.}
   \seemodule{dbm}{Standard \UNIX{} database interface.}
   \seemodule{dumbdbm}{Portable implementation of the \code{dbm} interface.}
   \seemodule{gdbm}{GNU database interface, based on the \code{dbm} interface.}