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, the
  32    first module listed above that can be imported is used.
  33
  34    The optional *flag* argument can be ``'r'`` to open an existing database for
  35    reading only, ``'w'`` to open an existing database for reading and writing,
  36    ``'c'`` to create the database if it doesn't exist, or ``'n'``, which will
  37    always create a new empty database.  If not specified, the default value is
  38    ``'r'``.
  39
  40    The optional *mode* argument is the Unix mode of the file, used only when the
  41    database has to be created.  It defaults to octal ``0666`` (and will be modified
  42    by the prevailing umask).
  43
  44
  45 .. exception:: error
  46
  47    A tuple containing the exceptions that can be raised by each of the supported
  48    modules, with a unique exception also named :exc:`anydbm.error` as the first
  49    item --- the latter is used when :exc:`anydbm.error` is raised.
  50
  51 The object returned by :func:`open` supports most of the same functionality as
  52 dictionaries; keys and their corresponding values can be stored, retrieved, and
  53 deleted, and the :meth:`has_key` and :meth:`keys` methods are available.  Keys
  54 and values must always be strings.
  55
  56 The following example records some hostnames and a corresponding title,  and
  57 then prints out the contents of the database::
  58
  59    import anydbm
  60
  61    # Open database, creating it if necessary.
  62    db = anydbm.open('cache', 'c')
  63
  64    # Record some values
  65    db['www.python.org'] = 'Python Website'
  66    db['www.cnn.com'] = 'Cable News Network'
  67
  68    # Loop through contents.  Other dictionary methods
  69    # such as .keys(), .values() also work.
  70    for k, v in db.iteritems():
  71        print k, '\t', v
  72
  73    # Storing a non-string key or value will raise an exception (most
  74    # likely a TypeError).
  75    db['www.yahoo.com'] = 4
  76
  77    # Close when done.
  78    db.close()
  79
  80
  81 .. seealso::
  82
  83    Module :mod:`dbhash`
  84       BSD ``db`` database interface.
  85
  86    Module :mod:`dbm`
  87       Standard Unix database interface.
  88
  89    Module :mod:`dumbdbm`
  90       Portable implementation of the ``dbm`` interface.
  91
  92    Module :mod:`gdbm`
  93       GNU database interface, based on the ``dbm`` interface.
  94
  95    Module :mod:`shelve`
  96       General object persistence built on top of  the Python ``dbm`` interface.
  97
  98    Module :mod:`whichdb`
  99       Utility module used to determine the type of an existing database.
 100