Doc/lib/libanydbm.tex

   1 \section{\module{anydbm} ---
   2          Generic access to DBM-style databases}
   3
   4 \declaremodule{standard}{anydbm}
   5 \modulesynopsis{Generic interface to DBM-style database modules.}
   6
   7
   8 \module{anydbm} is a generic interface to variants of the DBM
   9 database --- \refmodule{dbhash}\refstmodindex{dbhash} (requires
  10 \refmodule{bsddb}\refbimodindex{bsddb}),
  11 \refmodule{gdbm}\refbimodindex{gdbm}, or
  12 \refmodule{dbm}\refbimodindex{dbm}.  If none of these modules is
  13 installed, the slow-but-simple implementation in module
  14 \refmodule{dumbdbm}\refstmodindex{dumbdbm} will be used.
  15
  16 \begin{funcdesc}{open}{filename\optional{, flag\optional{, mode}}}
  17 Open the database file \var{filename} and return a corresponding object.
  18
  19 If the database file already exists, the \refmodule{whichdb} module is
  20 used to determine its type and the appropriate module is used; if it
  21 does not exist, the first module listed above that can be imported is
  22 used.
  23
  24 The optional \var{flag} argument can be
  25 \code{'r'} to open an existing database for reading only,
  26 \code{'w'} to open an existing database for reading and writing,
  27 \code{'c'} to create the database if it doesn't exist, or
  28 \code{'n'}, which will always create a new empty database.  If not
  29 specified, the default value is \code{'r'}.
  30
  31 The optional \var{mode} argument is the \UNIX{} mode of the file, used
  32 only when the database has to be created.  It defaults to octal
  33 \code{0666} (and will be modified by the prevailing umask).
  34 \end{funcdesc}
  35
  36 \begin{excdesc}{error}
  37 A tuple containing the exceptions that can be raised by each of the
  38 supported modules, with a unique exception \exception{anydbm.error} as
  39 the first item --- the latter is used when \exception{anydbm.error} is
  40 raised.
  41 \end{excdesc}
  42
  43 The object returned by \function{open()} supports most of the same
  44 functionality as dictionaries; keys and their corresponding values can
  45 be stored, retrieved, and deleted, and the \method{has_key()} and
  46 \method{keys()} methods are available.  Keys and values must always be
  47 strings.
  48
  49
  50 \begin{seealso}
  51   \seemodule{anydbm}{Generic interface to \code{dbm}-style databases.}
  52   \seemodule{dbhash}{BSD \code{db} database interface.}
  53   \seemodule{dbm}{Standard \UNIX{} database interface.}
  54   \seemodule{dumbdbm}{Portable implementation of the \code{dbm} interface.}
  55   \seemodule{gdbm}{GNU database interface, based on the \code{dbm} interface.}
  56   \seemodule{shelve}{General object persistence built on top of
  57                      the Python \code{dbm} interface.}
  58   \seemodule{whichdb}{Utility module used to determine the type of an
  59                       existing database.}
  60 \end{seealso}
  61
  62
  63 \section{\module{dumbdbm} ---
  64          Portable DBM implementation}
  65
  66 \declaremodule{standard}{dumbdbm}
  67 \modulesynopsis{Portable implementation of the simple DBM interface.}
  68
  69
  70 A simple and slow database implemented entirely in Python.  This
  71 should only be used when no other DBM-style database is available.
  72
  73
  74 \begin{funcdesc}{open}{filename\optional{, flag\optional{, mode}}}
  75 Open the database file \var{filename} and return a corresponding object.
  76 The optional \var{flag} argument can be
  77 \code{'r'} to open an existing database for reading only,
  78 \code{'w'} to open an existing database for reading and writing,
  79 \code{'c'} to create the database if it doesn't exist, or
  80 \code{'n'}, which will always create a new empty database.  If not
  81 specified, the default value is \code{'r'}.
  82
  83 The optional \var{mode} argument is the \UNIX{} mode of the file, used
  84 only when the database has to be created.  It defaults to octal
  85 \code{0666} (and will be modified by the prevailing umask).
  86 \end{funcdesc}
  87
  88 \begin{excdesc}{error}
  89 Raised for errors not reported as \exception{KeyError} errors.
  90 \end{excdesc}
  91
  92
  93 \begin{seealso}
  94   \seemodule{anydbm}{Generic interface to \code{dbm}-style databases.}
  95   \seemodule{whichdb}{Utility module used to determine the type of an
  96                       existing database.}
  97 \end{seealso}