Doc/library/dumbdbm.rst

   1 :mod:`dumbdbm` --- Portable DBM implementation
   2 ==============================================
   3
   4 .. module:: dumbdbm
   5    :synopsis: Portable implementation of the simple DBM interface.
   6
   7 .. note::
   8    The :mod:`dumbdbm` module has been renamed to :mod:`dbm.dumb` in Python 3.0.
   9    The :term:`2to3` tool will automatically adapt imports when converting your
  10    sources to 3.0.
  11
  12 .. index:: single: databases
  13
  14 .. note::
  15
  16    The :mod:`dumbdbm` module is intended as a last resort fallback for the
  17    :mod:`anydbm` module when no more robust module is available. The :mod:`dumbdbm`
  18    module is not written for speed and is not nearly as heavily used as the other
  19    database modules.
  20
  21 The :mod:`dumbdbm` module provides a persistent dictionary-like interface which
  22 is written entirely in Python.  Unlike other modules such as :mod:`gdbm` and
  23 :mod:`bsddb`, no external library is required.  As with other persistent
  24 mappings, the keys and values must always be strings.
  25
  26 The module defines the following:
  27
  28
  29 .. exception:: error
  30
  31    Raised on dumbdbm-specific errors, such as I/O errors.  :exc:`KeyError` is
  32    raised for general mapping errors like specifying an incorrect key.
  33
  34
  35 .. function:: open(filename[, flag[, mode]])
  36
  37    Open a dumbdbm database and return a dumbdbm object.  The *filename* argument is
  38    the basename of the database file (without any specific extensions).  When a
  39    dumbdbm database is created, files with :file:`.dat` and :file:`.dir` extensions
  40    are created.
  41
  42    The optional *flag* argument is currently ignored; the database is always opened
  43    for update, and will be created if it does not exist.
  44
  45    The optional *mode* argument is the Unix mode of the file, used only when the
  46    database has to be created.  It defaults to octal ``0666`` (and will be modified
  47    by the prevailing umask).
  48
  49    .. versionchanged:: 2.2
  50       The *mode* argument was ignored in earlier versions.
  51
  52
  53 .. seealso::
  54
  55    Module :mod:`anydbm`
  56       Generic interface to ``dbm``\ -style databases.
  57
  58    Module :mod:`dbm`
  59       Similar interface to the DBM/NDBM library.
  60
  61    Module :mod:`gdbm`
  62       Similar interface to the GNU GDBM library.
  63
  64    Module :mod:`shelve`
  65       Persistence module which stores non-string data.
  66
  67    Module :mod:`whichdb`
  68       Utility module used to determine the type of an existing database.
  69
  70
  71 .. _dumbdbm-objects:
  72
  73 Dumbdbm Objects
  74 ---------------
  75
  76 In addition to the methods provided by the :class:`UserDict.DictMixin` class,
  77 :class:`dumbdbm` objects provide the following methods.
  78
  79
  80 .. method:: dumbdbm.sync()
  81
  82    Synchronize the on-disk directory and data files.  This method is called by the
  83    :meth:`sync` method of :class:`Shelve` objects.
  84