diff options
Diffstat (limited to 'Doc/lib/libbsddb.tex')
-rw-r--r-- | Doc/lib/libbsddb.tex | 211 |
1 files changed, 0 insertions, 211 deletions
diff --git a/Doc/lib/libbsddb.tex b/Doc/lib/libbsddb.tex deleted file mode 100644 index 8f23324..0000000 --- a/Doc/lib/libbsddb.tex +++ /dev/null @@ -1,211 +0,0 @@ -\section{\module{bsddb} --- - Interface to Berkeley DB library} - -\declaremodule{extension}{bsddb} -\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 \function{marshal.dumps()} or -\function{pickle.dumps()}. - -The \module{bsddb} module requires a Berkeley DB library version from -3.3 thru 4.5. - -\begin{seealso} - \seeurl{http://pybsddb.sourceforge.net/} - {The website with documentation for the \module{bsddb.db} - Python Berkeley DB interface that closely mirrors the object - oriented interface provided in Berkeley DB 3 and 4.} - - \seeurl{http://www.oracle.com/database/berkeley-db/} - {The Berkeley DB library.} -\end{seealso} - -A more modern DB, DBEnv and DBSequence object interface is available in the -\module{bsddb.db} module which closely matches the Berkeley DB C API -documented at the above URLs. Additional features provided by the -\module{bsddb.db} API include fine tuning, transactions, logging, and -multiprocess concurrent database access. - -The following is a description of the legacy \module{bsddb} interface -compatible with the old Python bsddb module. Starting in Python 2.5 this -interface should be safe for multithreaded access. The \module{bsddb.db} -API is recommended for threading users as it provides better control. - -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{, pgsize\optional{, - ffactor\optional{, nelem\optional{, - cachesize\optional{, lorder\optional{, - hflags}}}}}}}}} -Open the hash format file named \var{filename}. Files never intended -to be preserved on disk may be created by passing \code{None} as the -\var{filename}. The optional -\var{flag} identifies the mode used to open the file. It may be -\character{r} (read only), \character{w} (read-write) , -\character{c} (read-write - create if necessary; the default) or -\character{n} (read-write - truncate to zero length). The other -arguments are rarely used and are just passed to the low-level -\cfunction{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{, pgsize\optional{, lorder}}}}}}}}} - -Open the btree format file named \var{filename}. Files never intended -to be preserved on disk may be created by passing \code{None} as the -\var{filename}. The optional -\var{flag} identifies the mode used to open the file. It may be -\character{r} (read only), \character{w} (read-write), -\character{c} (read-write - create if necessary; the default) or -\character{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{, pgsize\optional{, lorder\optional{, -rlen\optional{, delim\optional{, source\optional{, pad}}}}}}}}}}} - -Open a DB record format file named \var{filename}. Files never intended -to be preserved on disk may be created by passing \code{None} as the -\var{filename}. The optional -\var{flag} identifies the mode used to open the file. It may be -\character{r} (read only), \character{w} (read-write), -\character{c} (read-write - create if necessary; the default) or -\character{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{classdesc}{StringKeys}{db} - Wrapper class around a DB object that supports string keys - (rather than bytes). All keys are encoded as UTF-8, then passed - to the underlying object. \versionadded{3.0} -\end{classdesc} - -\begin{classdesc}{StringValues}{db} - Wrapper class around a DB object that supports string values - (rather than bytes). All values are encoded as UTF-8, then passed - to the underlying object. \versionadded{3.0} -\end{classdesc} - -\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 same methods as dictionaries. In addition, they support -the methods listed below. -\versionchanged[Added dictionary methods]{2.3.1} - -\begin{methoddesc}[bsddbobject]{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}[bsddbobject]{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}[bsddbobject]{has_key}{key} -Return \code{1} if the DB file contains the argument as a key. -\end{methoddesc} - -\begin{methoddesc}[bsddbobject]{set_location}{key} -Set the cursor to the item indicated by \var{key} and return a tuple -containing the key and its value. For binary tree databases (opened -using \function{btopen()}), if \var{key} does not actually exist in -the database, the cursor will point to the next item in sorted order -and return that key and value. For other databases, -\exception{KeyError} will be raised if \var{key} is not found in the -database. -\end{methoddesc} - -\begin{methoddesc}[bsddbobject]{first}{} -Set the cursor to the first item in the DB file and return it. The order of -keys in the file is unspecified, except in the case of B-Tree databases. -This method raises \exception{bsddb.error} if the database is empty. -\end{methoddesc} - -\begin{methoddesc}[bsddbobject]{next}{} -Set the cursor to the next item in the DB file and return it. The order of -keys in the file is unspecified, except in the case of B-Tree databases. -\end{methoddesc} - -\begin{methoddesc}[bsddbobject]{previous}{} -Set the cursor to the previous item in the DB file and return it. The -order of keys in the file is unspecified, except in the case of B-Tree -databases. This is not supported on hashtable databases (those opened -with \function{hashopen()}). -\end{methoddesc} - -\begin{methoddesc}[bsddbobject]{last}{} -Set the cursor to the last item in the DB file and return it. The -order of keys in the file is unspecified. This is not supported on -hashtable databases (those opened with \function{hashopen()}). -This method raises \exception{bsddb.error} if the database is empty. -\end{methoddesc} - -\begin{methoddesc}[bsddbobject]{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') ->>> for k, v in db.iteritems(): -... print k, v -0 0 -1 1 -2 4 -3 9 -4 16 -5 25 -6 36 -7 49 -8 64 -9 81 ->>> '8' in db -True ->>> db.sync() -0 -\end{verbatim} |