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

1 files changed, 89 insertions, 0 deletions

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}