diff options
| -rw-r--r-- | Doc/lib/lib.tex | 1 | ||||
| -rw-r--r-- | Doc/lib/libanydbm.tex | 5 | ||||
| -rw-r--r-- | Doc/lib/libdbhash.tex | 89 | ||||
| -rw-r--r-- | Doc/lib/libshelve.tex | 2 |
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.} |