Fred Drake | 666255f | 1999-04-15 15:11:40 +0000 | [diff] [blame] | 1 | \section{\module{dbhash} --- |
| 2 | DBM-style interface to the BSD database library} |
| 3 | |
| 4 | \declaremodule{standard}{dbhash} |
| 5 | \platform{Unix, Windows} |
| 6 | \modulesynopsis{DBM-style interface to the BSD database library.} |
Fred Drake | 31bfbc6 | 1999-04-16 14:03:32 +0000 | [diff] [blame] | 7 | \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} |
Fred Drake | 666255f | 1999-04-15 15:11:40 +0000 | [diff] [blame] | 8 | |
| 9 | |
| 10 | The \module{dbhash} module provides a function to open databases using |
| 11 | the BSD \code{db} library. This module mirrors the interface of the |
| 12 | other Python database modules that provide access to DBM-style |
Fred Drake | 9d15881 | 1999-04-19 21:19:21 +0000 | [diff] [blame] | 13 | databases. The \refmodule{bsddb}\refbimodindex{bsddb} module is required |
Fred Drake | 666255f | 1999-04-15 15:11:40 +0000 | [diff] [blame] | 14 | to use \module{dbhash}. |
| 15 | |
| 16 | This module provides an exception and a function: |
| 17 | |
| 18 | |
| 19 | \begin{excdesc}{error} |
| 20 | Exception raised on database errors other than |
| 21 | \exception{KeyError}. It is a synonym for \exception{bsddb.error}. |
| 22 | \end{excdesc} |
| 23 | |
Thomas Wouters | 6994097 | 2001-06-27 13:49:59 +0000 | [diff] [blame] | 24 | \begin{funcdesc}{open}{path\optional{, flag\optional{, mode}}} |
Fred Drake | 666255f | 1999-04-15 15:11:40 +0000 | [diff] [blame] | 25 | Open a \code{db} database and return the database object. The |
| 26 | \var{path} argument is the name of the database file. |
| 27 | |
| 28 | The \var{flag} argument can be |
Fred Drake | 31bfbc6 | 1999-04-16 14:03:32 +0000 | [diff] [blame] | 29 | \code{'r'} (the default), \code{'w'}, |
Fred Drake | 666255f | 1999-04-15 15:11:40 +0000 | [diff] [blame] | 30 | \code{'c'} (which creates the database if it doesn't exist), or |
| 31 | \code{'n'} (which always creates a new empty database). |
| 32 | For platforms on which the BSD \code{db} library supports locking, |
| 33 | an \character{l} can be appended to indicate that locking should be |
| 34 | used. |
| 35 | |
| 36 | The optional \var{mode} parameter is used to indicate the \UNIX{} |
| 37 | permission bits that should be set if a new database must be |
| 38 | created; this will be masked by the current umask value for the |
| 39 | process. |
| 40 | \end{funcdesc} |
| 41 | |
| 42 | |
| 43 | \begin{seealso} |
| 44 | \seemodule{anydbm}{Generic interface to \code{dbm}-style databases.} |
Fred Drake | 9d15881 | 1999-04-19 21:19:21 +0000 | [diff] [blame] | 45 | \seemodule{bsddb}{Lower-level interface to the BSD \code{db} library.} |
Fred Drake | 666255f | 1999-04-15 15:11:40 +0000 | [diff] [blame] | 46 | \seemodule{whichdb}{Utility module used to determine the type of an |
| 47 | existing database.} |
| 48 | \end{seealso} |
| 49 | |
| 50 | |
| 51 | \subsection{Database Objects \label{dbhash-objects}} |
| 52 | |
| 53 | The database objects returned by \function{open()} provide the methods |
| 54 | common to all the DBM-style databases. The following methods are |
| 55 | available in addition to the standard methods. |
| 56 | |
| 57 | \begin{methoddesc}[dbhash]{first}{} |
| 58 | It's possible to loop over every key in the database using this method |
| 59 | and the \method{next()} method. The traversal is ordered by |
| 60 | the databases internal hash values, and won't be sorted by the key |
| 61 | values. This method returns the starting key. |
| 62 | \end{methoddesc} |
| 63 | |
| 64 | \begin{methoddesc}[dbhash]{last}{} |
| 65 | Return the last key in a database traversal. This may be used to |
| 66 | begin a reverse-order traversal; see \method{previous()}. |
| 67 | \end{methoddesc} |
| 68 | |
Raymond Hettinger | 0d6e8cd | 2003-09-10 04:44:29 +0000 | [diff] [blame] | 69 | \begin{methoddesc}[dbhash]{next}{} |
| 70 | Returns the key next key in a database traversal. The |
Fred Drake | 666255f | 1999-04-15 15:11:40 +0000 | [diff] [blame] | 71 | following code prints every key in the database \code{db}, without |
| 72 | having to create a list in memory that contains them all: |
| 73 | |
| 74 | \begin{verbatim} |
Raymond Hettinger | 0d6e8cd | 2003-09-10 04:44:29 +0000 | [diff] [blame] | 75 | print db.first() |
| 76 | for i in xrange(1, len(d)): |
| 77 | print db.next() |
Fred Drake | 666255f | 1999-04-15 15:11:40 +0000 | [diff] [blame] | 78 | \end{verbatim} |
| 79 | \end{methoddesc} |
| 80 | |
Raymond Hettinger | 0d6e8cd | 2003-09-10 04:44:29 +0000 | [diff] [blame] | 81 | \begin{methoddesc}[dbhash]{previous}{} |
| 82 | Returns the previous key in a forward-traversal of the database. |
| 83 | In conjunction with \method{last()}, this may be used to implement |
| 84 | a reverse-order traversal. |
Fred Drake | 666255f | 1999-04-15 15:11:40 +0000 | [diff] [blame] | 85 | \end{methoddesc} |
| 86 | |
| 87 | \begin{methoddesc}[dbhash]{sync}{} |
| 88 | This method forces any unwritten data to be written to the disk. |
| 89 | \end{methoddesc} |