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.} |
| 7 | |
| 8 | |
| 9 | The \module{dbhash} module provides a function to open databases using |
| 10 | the BSD \code{db} library. This module mirrors the interface of the |
| 11 | other Python database modules that provide access to DBM-style |
| 12 | databases. The \module{bsddb}\refbimodindex{bsddb} module is required |
| 13 | to use \module{dbhash}. |
| 14 | |
| 15 | This module provides an exception and a function: |
| 16 | |
| 17 | |
| 18 | \begin{excdesc}{error} |
| 19 | Exception raised on database errors other than |
| 20 | \exception{KeyError}. It is a synonym for \exception{bsddb.error}. |
| 21 | \end{excdesc} |
| 22 | |
| 23 | \begin{funcdesc}{open}{path, flag\optional{, mode}} |
| 24 | Open a \code{db} database and return the database object. The |
| 25 | \var{path} argument is the name of the database file. |
| 26 | |
| 27 | The \var{flag} argument can be |
| 28 | \code{'r'} (to open an existing database for reading only --- default), |
| 29 | \code{'w'} (to open an existing database for reading and writing), |
| 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.} |
| 45 | \seemodule{whichdb}{Utility module used to determine the type of an |
| 46 | existing database.} |
| 47 | \end{seealso} |
| 48 | |
| 49 | |
| 50 | \subsection{Database Objects \label{dbhash-objects}} |
| 51 | |
| 52 | The database objects returned by \function{open()} provide the methods |
| 53 | common to all the DBM-style databases. The following methods are |
| 54 | available in addition to the standard methods. |
| 55 | |
| 56 | \begin{methoddesc}[dbhash]{first}{} |
| 57 | It's possible to loop over every key in the database using this method |
| 58 | and the \method{next()} method. The traversal is ordered by |
| 59 | the databases internal hash values, and won't be sorted by the key |
| 60 | values. This method returns the starting key. |
| 61 | \end{methoddesc} |
| 62 | |
| 63 | \begin{methoddesc}[dbhash]{last}{} |
| 64 | Return the last key in a database traversal. This may be used to |
| 65 | begin a reverse-order traversal; see \method{previous()}. |
| 66 | \end{methoddesc} |
| 67 | |
| 68 | \begin{methoddesc}[dbhash]{next}{key} |
| 69 | Returns the key that follows \var{key} in the traversal. The |
| 70 | following code prints every key in the database \code{db}, without |
| 71 | having to create a list in memory that contains them all: |
| 72 | |
| 73 | \begin{verbatim} |
| 74 | k = db.first() |
| 75 | while k != None: |
| 76 | print k |
| 77 | k = db.next(k) |
| 78 | \end{verbatim} |
| 79 | \end{methoddesc} |
| 80 | |
| 81 | \begin{methoddesc}[dbhash]{previous}{key} |
| 82 | Return the key that comes before \var{key} in a forward-traversal of |
| 83 | the database. In conjunction with \method{last()}, this may be used |
| 84 | to implement a reverse-order traversal. |
| 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} |