diff options
| -rw-r--r-- | Doc/lib/libanydbm.tex | 2 | ||||
| -rw-r--r-- | Doc/lib/libbsddb.tex | 143 | ||||
| -rw-r--r-- | Doc/lib/libdbhash.tex | 3 |
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} |