Doc/lib/libdumbdbm.tex

   1 \section{\module{dumbdbm} ---
   2          Portable DBM implementation}
   3
   4 \declaremodule{standard}{dumbdbm}
   5 \modulesynopsis{Portable implementation of the simple DBM interface.}
   6
   7 \index{databases}
   8
   9 \begin{notice}
  10 The \module{dumbdbm} module is intended as a last resort fallback for
  11 the \refmodule{anydbm} module when no more robust module is available.
  12 The \module{dumbdbm} module is not written for speed and is not nearly as
  13 heavily used as the other database modules.
  14 \end{notice}
  15
  16 The \module{dumbdbm} module provides a persistent dictionary-like interface
  17 which is written entirely in Python.  Unlike other modules such as
  18 \refmodule{gdbm} and \refmodule{bsddb}, no external library is required.  As
  19 with other persistent mappings, the keys and values must always be strings.
  20
  21 The module defines the following:
  22
  23 \begin{excdesc}{error}
  24 Raised on dumbdbm-specific errors, such as I/O errors.  \exception{KeyError}
  25 is raised for general mapping errors like specifying an incorrect key.
  26 \end{excdesc}
  27
  28 \begin{funcdesc}{open}{filename\optional{, flag\optional{, mode}}}
  29 Open a dumbdbm database and return a dumbdbm object.  The \var{filename}
  30 argument is the basename of the database file (without any specific
  31 extensions).  When a dumbdbm database is created, files with \file{.dat} and
  32 \file{.dir} extensions are created.
  33
  34 The optional \var{flag} argument is currently ignored; the database is
  35 always opened for update, and will be created if it does not exist.
  36
  37 The optional \var{mode} argument is the \UNIX{} mode of the file, used
  38 only when the database has to be created.  It defaults to octal
  39 \code{0666} (and will be modified by the prevailing umask).
  40 \versionchanged[The \var{mode} argument was ignored in earlier
  41                 versions]{2.2}
  42 \end{funcdesc}
  43
  44
  45 \begin{seealso}
  46   \seemodule{anydbm}{Generic interface to \code{dbm}-style databases.}
  47   \seemodule{dbm}{Similar interface to the DBM/NDBM library.}
  48   \seemodule{gdbm}{Similar interface to the GNU GDBM library.}
  49   \seemodule{shelve}{Persistence module which stores non-string data.}
  50   \seemodule{whichdb}{Utility module used to determine the type of an
  51                       existing database.}
  52 \end{seealso}
  53
  54
  55 \subsection{Dumbdbm Objects \label{dumbdbm-objects}}
  56
  57 In addition to the methods provided by the \class{UserDict.DictMixin} class,
  58 \class{dumbdbm} objects provide the following methods.
  59
  60 \begin{methoddesc}{sync}{}
  61 Synchronize the on-disk directory and data files.  This method is called by
  62 the \method{sync} method of \class{Shelve} objects.
  63 \end{methoddesc}