Doc/library/anydbm.rst

   1 :mod:`anydbm` --- Generic access to DBM-style databases
   2 =======================================================
   3
   4 .. module:: anydbm
   5    :synopsis: Generic interface to DBM-style database modules.
   6
   7
   8 .. note::
   9    The :mod:`anydbm` module has been renamed to :mod:`dbm` in Python 3.0.  The
  10    :term:`2to3` tool will automatically adapt imports when converting your
  11    sources to 3.0.
  12
  13 .. index::
  14    module: dbhash
  15    module: bsddb
  16    module: gdbm
  17    module: dbm
  18    module: dumbdbm
  19
  20 :mod:`anydbm` is a generic interface to variants of the DBM database ---
  21 :mod:`dbhash` (requires :mod:`bsddb`), :mod:`gdbm`, or :mod:`dbm`.  If none of
  22 these modules is installed, the slow-but-simple implementation in module
  23 :mod:`dumbdbm` will be used.
  24
  25
  26 .. function:: open(filename[, flag[, mode]])
  27
  28    Open the database file *filename* and return a corresponding object.
  29
  30    If the database file already exists, the :mod:`whichdb` module is used to
  31    determine its type and the appropriate module is used; if it does not exist,
  32    the first module listed above that can be imported is used.
  33
  34    The optional *flag* argument must be one of these values:
  35
  36    +---------+-------------------------------------------+
  37    | Value   | Meaning                                   |
  38    +=========+===========================================+
  39    | ``'r'`` | Open existing database for reading only   |
  40    |         | (default)                                 |
  41    +---------+-------------------------------------------+
  42    | ``'w'`` | Open existing database for reading and    |
  43    |         | writing                                   |
  44    +---------+-------------------------------------------+
  45    | ``'c'`` | Open database for reading and writing,    |
  46    |         | creating it if it doesn't exist           |
  47    +---------+-------------------------------------------+
  48    | ``'n'`` | Always create a new, empty database, open |
  49    |         | for reading and writing                   |
  50    +---------+-------------------------------------------+
  51
  52    If not specified, the default value is ``'r'``.
  53
  54    The optional *mode* argument is the Unix mode of the file, used only when the
  55    database has to be created.  It defaults to octal ``0666`` (and will be
  56    modified by the prevailing umask).
  57
  58
  59 .. exception:: error
  60
  61    A tuple containing the exceptions that can be raised by each of the supported
  62    modules, with a unique exception also named :exc:`anydbm.error` as the first
  63    item --- the latter is used when :exc:`anydbm.error` is raised.
  64
  65 The object returned by :func:`.open` supports most of the same functionality as
  66 dictionaries; keys and their corresponding values can be stored, retrieved, and
  67 deleted, and the :meth:`has_key` and :meth:`keys` methods are available.  Keys
  68 and values must always be strings.
  69
  70 The following example records some hostnames and a corresponding title,  and
  71 then prints out the contents of the database::
  72
  73    import anydbm
  74
  75    # Open database, creating it if necessary.
  76    db = anydbm.open('cache', 'c')
  77
  78    # Record some values
  79    db['www.python.org'] = 'Python Website'
  80    db['www.cnn.com'] = 'Cable News Network'
  81
  82    # Loop through contents.  Other dictionary methods
  83    # such as .keys(), .values() also work.
  84    for k, v in db.iteritems():
  85        print k, '\t', v
  86
  87    # Storing a non-string key or value will raise an exception (most
  88    # likely a TypeError).
  89    db['www.yahoo.com'] = 4
  90
  91    # Close when done.
  92    db.close()
  93
  94
  95 .. seealso::
  96
  97    Module :mod:`dbhash`
  98       BSD ``db`` database interface.
  99
 100    Module :mod:`dbm`
 101       Standard Unix database interface.
 102
 103    Module :mod:`dumbdbm`
 104       Portable implementation of the ``dbm`` interface.
 105
 106    Module :mod:`gdbm`
 107       GNU database interface, based on the ``dbm`` interface.
 108
 109    Module :mod:`shelve`
 110       General object persistence built on top of  the Python ``dbm`` interface.
 111
 112    Module :mod:`whichdb`
 113       Utility module used to determine the type of an existing database.
 114