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

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

``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 must be one of these values:

   +-----------+---------------------------------------------+
   | Value     | Meaning                                     |
   +===========+=============================================+
   | ``'r'``   | Open existing database for reading only     |
   |           | (default)                                   |
   +-----------+---------------------------------------------+
   | ``'w'``   | Open existing database for reading and      |
   |           | writing                                     |
   +-----------+---------------------------------------------+
   | ``'c'``   | Open database for reading and writing,      |
   |           | creating it if it doesn't exist             |
   +-----------+---------------------------------------------+
   | ``'n'``   | Always create a new, empty database, open   |
   |           | for reading and writing                     |
   +-----------+---------------------------------------------+

   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 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()

In addition to the dictionary-like methods, ``anydbm`` objects provide
the following method:

anydbm.close()

   Close the ``anydbm`` database.

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.
