
``anydbm`` --- Generic access to DBM-style databases
****************************************************

Note: The ``anydbm`` module has been renamed to ``dbm`` in Python 3.0.
  The *2to3* tool will automatically adapt imports when converting
  your sources to 3.0.

``anydbm`` is a generic interface to variants of the DBM database ---
``dbhash`` (requires ``bsddb``), ``gdbm``, or ``dbm``.  If none of
these modules is installed, the slow-but-simple implementation in
module ``dumbdbm`` will be used.

anydbm.open(filename[, flag[, mode]])

   Open the database file *filename* and return a corresponding
   object.

   If the database file already exists, the ``whichdb`` module is
   used to determine its type and the appropriate module is used; if
   it does not exist, the first module listed above that can be
   imported is used.

   The optional *flag* argument can be ``'r'`` to open an existing
   database for reading only, ``'w'`` to open an existing database for
   reading and writing, ``'c'`` to create the database if it doesn't
   exist, or ``'n'``, which will always create a new empty database.
   If not specified, the default value is ``'r'``.

   The optional *mode* argument is the Unix mode of the file, used
   only when the database has to be created.  It defaults to octal
   ``0666`` (and will be modified by the prevailing umask).

exception anydbm.error

   A tuple containing the exceptions that can be raised by each of the
   supported modules, with a unique exception also named
   ``anydbm.error`` as the first item --- the latter is used when
   ``anydbm.error`` is raised.

The object returned by ``open()`` supports most of the same
functionality as dictionaries; keys and their corresponding values can
be stored, retrieved, and deleted, and the ``has_key()`` and
``keys()`` methods are available.  Keys and values must always be
strings.

The following example records some hostnames and a corresponding
title,  and then prints out the contents of the database:

   import anydbm

   # Open database, creating it if necessary.
   db = anydbm.open('cache', 'c')

   # Record some values
   db['www.python.org'] = 'Python Website'
   db['www.cnn.com'] = 'Cable News Network'

   # Loop through contents.  Other dictionary methods
   # such as .keys(), .values() also work.
   for k, v in db.iteritems():
       print k, '\t', v

   # Storing a non-string key or value will raise an exception (most
   # likely a TypeError).
   db['www.yahoo.com'] = 4

   # Close when done.
   db.close()

See also:

   Module ``dbhash``
      BSD ``db`` database interface.

   Module ``dbm``
      Standard Unix database interface.

   Module ``dumbdbm``
      Portable implementation of the ``dbm`` interface.

   Module ``gdbm``
      GNU database interface, based on the ``dbm`` interface.

   Module ``shelve``
      General object persistence built on top of  the Python ``dbm``
      interface.

   Module ``whichdb``
      Utility module used to determine the type of an existing
      database.
