bsddb docs from Skip Montanaro; added interesting links.

3 files changed, 146 insertions, 2 deletions

diff --git a/Doc/lib/libanydbm.tex b/Doc/lib/libanydbm.tex
index 4df6628..367daf6 100644
--- a/Doc/lib/libanydbm.tex
+++ b/Doc/lib/libanydbm.tex
@@ -7,7 +7,7 @@
 
 \module{anydbm} is a generic interface to variants of the DBM
 database --- \refmodule{dbhash}\refstmodindex{dbhash} (requires
-\module{bsddb}\refbimodindex{bsddb}),
+\refmodule{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
diff --git a/Doc/lib/libbsddb.tex b/Doc/lib/libbsddb.tex
new file mode 100644
index 0000000..385f558
--- /dev/null
+++ b/Doc/lib/libbsddb.tex
@@ -0,0 +1,143 @@
+\section{\module{bsddb} ---
+         Interface to Berkeley DB library}
+
+\declaremodule{extension}{bsddb}
+  \platform{Unix, Windows}
+\modulesynopsis{Interface to Berkeley DB database library}
+\sectionauthor{Skip Montanaro}{skip@mojam.com}
+
+
+The \module{bsddb} module provides an interface to the Berkeley DB library.
+Users can create hash, btree or record based library files using the
+appropriate open call. Bsddb objects behave generally like dictionaries.
+Keys and values must be strings, however, so to use other objects as keys or 
+to store other kinds of objects the user must serialize them somehow,
+typically using marshal.dumps or pickle.dumps.
+
+The \module{bsddb} module is only available on \UNIX{} systems, so it is not
+built by default in the standard Python distribution.  Also, there are two
+incompatible versions of the underlying library.  Version 1.85 is widely
+available, but has some known bugs.  Version 2 is not quite as widely used,
+but does offer some improvements.  The \module{bsddb} module uses the 1.85
+interface.  Users wishing to use version 2 of the Berkeley DB library will
+have to modify the source for the module to include db_185.h instead of
+db.h.
+
+The \module{bsddb} module defines the following functions that create
+objects that access the appropriate type of Berkeley DB file.  The first two
+arguments of each function are the same.  For ease of portability, only the
+first two arguments should be used in most instances.
+
+\begin{funcdesc}{hashopen}{filename\optional{, flag\optional{,
+mode\optional{, bsize\optional{, ffactor\optional{, nelem\optional{,
+cachesize\optional{, hash\optional{, lorder}}}}}}}}}
+Open the hash format file named \var{filename}.  The optional \var{flag}
+identifies the mode used to open the file.  It may be ``r'' (read only),
+``w'' (read-write), ``c'' (read-write - create if necessary) or ``n''
+(read-write - truncate to zero length).  The other arguments are rarely used
+and are just passed to the low-level dbopen function.  Consult the
+Berkeley DB documentation for their use and interpretation.
+\end{funcdesc}
+
+
+\begin{funcdesc}{btopen}{filename\optional{, flag\optional{,
+mode\optional{, btflags\optional{, cachesize\optional{, maxkeypage\optional{,
+minkeypage\optional{, psize\optional{, lorder}}}}}}}}}
+Open the btree format file named \var{filename}.  The optional \var{flag}
+identifies the mode used to open the file.  It may be ``r'' (read only),
+``w'' (read-write), ``c'' (read-write - create if necessary) or ``n''
+(read-write - truncate to zero length).  The other arguments are rarely used
+and are just passed to the low-level dbopen function.  Consult the
+Berkeley DB documentation for their use and interpretation.
+\end{funcdesc}
+
+\begin{funcdesc}{rnopen}{filename\optional{, flag\optional{, mode\optional{,
+rnflags\optional{, cachesize\optional{, psize\optional{, lorder\optional{,
+reclen\optional{, bval\optional{, bfname}}}}}}}}}}
+Open a DB record format file named \var{filename}.  The optional \var{flag}
+identifies the mode used to open the file.  It may be ``r'' (read only),
+``w'' (read-write), ``c'' (read-write - create if necessary) or ``n''
+(read-write - truncate to zero length).  The other arguments are rarely used
+and are just passed to the low-level dbopen function.  Consult the
+Berkeley DB documentation for their use and interpretation.
+\end{funcdesc}
+
+
+\begin{seealso}
+  \seemodule{dbhash}{DBM-style interface to the \module{bsddb}}
+\end{seealso}
+
+
+\subsection{Hash, BTree and Record Objects \label{bsddb-objects}}
+
+Once instantiated, hash, btree and record objects support the following
+methods:
+
+\begin{methoddesc}{close}{}
+Close the underlying file.  The object can no longer be accessed.  Since
+there is no open \method{open} method for these objects, to open the file
+again a new \module{bsddb} module open function must be called.
+\end{methoddesc}
+
+\begin{methoddesc}{keys}{}
+Return the list of keys contained in the DB file.  The order of the list is
+unspecified and should not be relied on.  In particular, the order of the
+list returned is different for different file formats.
+\end{methoddesc}
+
+\begin{methoddesc}{has_key}{key}
+Return 1 if the DB file contains the argument as a key.
+\end{methoddesc}
+
+\begin{methoddesc}{set_location}{key}
+Set the cursor to the item indicated by the key and return it.
+\end{methoddesc}
+
+\begin{methoddesc}{first}{}
+Set the cursor to the first item in the DB file and return it.  The order of 
+keys in the file is unspecified.
+\end{methoddesc}
+
+\begin{methoddesc}{next}{}
+Set the cursor to the next item in the DB file and return it.  The order of 
+keys in the file is unspecified.
+\end{methoddesc}
+
+\begin{methoddesc}{previous}{}
+Set the cursor to the first item in the DB file and return it.  The order of 
+keys in the file is unspecified.
+\end{methoddesc}
+
+\begin{methoddesc}{last}{}
+Set the cursor to the last item in the DB file and return it.  The order of 
+keys in the file is unspecified.
+\end{methoddesc}
+
+\begin{methoddesc}{sync}{}
+Synchronize the database on disk.
+\end{methoddesc}
+
+Example:
+
+\begin{verbatim}
+>>> import bsddb
+>>> db = bsddb.btopen('/tmp/spam.db', 'c')
+>>> for i in range(10): db['%d'%i] = '%d'% (i*i)
+... 
+>>> db['3']
+'9'
+>>> db.keys()
+['0', '1', '2', '3', '4', '5', '6', '7', '8', '9']
+>>> db.first()
+('0', '0')
+>>> db.next()
+('1', '1')
+>>> db.last()
+('9', '81')
+>>> db.set_location('2')
+('2', '4')
+>>> db.previous() 
+('1', '1')
+>>> db.sync()
+0
+\end{verbatim}
diff --git a/Doc/lib/libdbhash.tex b/Doc/lib/libdbhash.tex
index 9ad031c..61b0163 100644
--- a/Doc/lib/libdbhash.tex
+++ b/Doc/lib/libdbhash.tex
@@ -10,7 +10,7 @@
 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 
+databases.  The \refmodule{bsddb}\refbimodindex{bsddb} module is required 
 to use \module{dbhash}.
 
 This module provides an exception and a function:
@@ -42,6 +42,7 @@ This module provides an exception and a function:
 
 \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}