Doc/lib/libdbhash.tex

   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 \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
   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
  13 databases.  The \refmodule{bsddb}\refbimodindex{bsddb} module is required
  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
  24 \begin{funcdesc}{open}{path\optional{, flag\optional{, mode}}}
  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
  29   \code{'r'} (the default), \code{'w'},
  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{bsddb}{Lower-level interface to the BSD \code{db} library.}
  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 and mapping objects.  The following
  55 methods are available in addition to the standard methods.
  56
  57 \begin{methoddesc}[dbhash]{first}{}
  58   It's possible to loop over every key/value pair in the database using
  59   this method   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/value pair in a database traversal.  This may be used to
  66   begin a reverse-order traversal; see \method{previous()}.
  67 \end{methoddesc}
  68
  69 \begin{methoddesc}[dbhash]{next}{}
  70   Returns the key next key/value pair in a database traversal.  The
  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}
  75 print db.first()
  76 for i in xrange(1, len(db)):
  77     print db.next()
  78 \end{verbatim}
  79 \end{methoddesc}
  80
  81 \begin{methoddesc}[dbhash]{previous}{}
  82   Returns the previous key/value pair in a forward-traversal of the database.
  83   In conjunction with \method{last()}, this may be used to implement
  84   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}