
``dbm`` --- Simple "database" interface
***************************************

*Platforms: *Unix

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

The ``dbm`` module provides an interface to the Unix "(n)dbm" library.
Dbm objects behave like mappings (dictionaries), except that keys and
values are always strings. Printing a dbm object doesn't print the
keys and values, and the ``items()`` and ``values()`` methods are not
supported.

This module can be used with the "classic" ndbm interface, the BSD DB
compatibility interface, or the GNU GDBM compatibility interface. On
Unix, the **configure** script will attempt to locate the appropriate
header file to simplify building this module.

The module defines the following:

exception exception dbm.error

   Raised on dbm-specific errors, such as I/O errors. ``KeyError`` is
   raised for general mapping errors like specifying an incorrect key.

dbm.library

   Name of the ``ndbm`` implementation library used.

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

   Open a dbm database and return a dbm object.  The *filename*
   argument is the name of the database file (without the ``.dir`` or
   ``.pag`` extensions; note that the BSD DB implementation of the
   interface will append the extension ``.db`` and only create one
   file).

   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                     |
   +-----------+---------------------------------------------+

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

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

   dbm.close()

      Close the ``dbm`` database.

See also:

   Module ``anydbm``
      Generic interface to ``dbm``-style databases.

   Module ``gdbm``
      Similar interface to the GNU GDBM library.

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